π OpenHands: AI-Driven Development
fix: migrate Linear integration to streamable HTTP /mcp endpoint (#1132)
Hiep Le614477e5c959
diff --git a/__tests__/components/features/mcp-page/install-server-modal.test.tsx b/__tests__/components/features/mcp-page/install-server-modal.test.tsxindex 21f7730f47..8473b4429e 100644--- a/__tests__/components/features/mcp-page/install-server-modal.test.tsx+++ b/__tests__/components/features/mcp-page/install-server-modal.test.tsx@@ -11,6 +11,7 @@ import {INTEGRATION_CATALOG as MCP_MARKETPLACE,type IntegrationCatalogEntry as MarketplaceEntry,} from "@openhands/extensions/integrations";+import { getMcpMarketplaceCatalog } from "#/utils/mcp-marketplace-utils";function renderWith(ui: React.ReactNode) {return render(ui, {@@ -207,6 +208,53 @@ describe("InstallServerModal", () => {await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));});+ it("installs Linear over streamable HTTP with the api key as a bearer credential", async () => {+ // Arrange: the marketplace serves the patched Linear entry (shttp+ // /mcp endpoint, bearer auth) β the UI must never touch the removed+ // /sse transport.+ const linear = getMcpMarketplaceCatalog(MCP_MARKETPLACE).find(+ (e) => e.id === "linear",+ )!;+ const testSpy = vi+ .spyOn(McpService, "testServer")+ .mockResolvedValue({ ok: true, tools: [] });+ const getSpy = vi+ .spyOn(SettingsService, "getSettings")+ .mockResolvedValue(MOCK_DEFAULT_USER_SETTINGS);+ const saveSpy = vi+ .spyOn(SettingsService, "saveSettings")+ .mockResolvedValue(true);++ renderWith(<InstallServerModal entry={linear} onClose={vi.fn()} />);+ await screen.findByTestId("mcp-install-modal");+ // Wait for useSettings() so the add-mcp-server mutation doesn't bail.+ await waitFor(() => expect(getSpy).toHaveBeenCalled());++ // Act: provide the optional Linear API key and install.+ fireEvent.change(screen.getByTestId("mcp-install-field-api_key"), {+ target: { value: "lin_api_secret" },+ });+ fireEvent.click(screen.getByTestId("mcp-install-submit"));++ // Assert: both the pre-flight test and the persisted config target+ // the new endpoint over streamable HTTP with the bearer credential.+ await waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(1));+ expect(testSpy).toHaveBeenCalledWith(+ expect.objectContaining({+ type: "shttp",+ url: "https://mcp.linear.app/mcp",+ api_key: "lin_api_secret",+ }),+ );+ const sent = (saveSpy.mock.calls[0][0] as Record<string, unknown>)+ .agent_settings_diff as {+ mcp_config: { mcpServers: Record<string, unknown> };+ };+ expect(sent.mcp_config.mcpServers).toMatchObject({+ shttp: { url: "https://mcp.linear.app/mcp", auth: "lin_api_secret" },+ });+ });+it("closes from the top-right close button", async () => {const onClose = vi.fn();const slack = MCP_MARKETPLACE.find((e) => e.id === "slack")!;diff --git a/__tests__/constants/extensions-catalogs.test.ts b/__tests__/constants/extensions-catalogs.test.tsindex 3233e40b45..d62605fb9b 100644--- a/__tests__/constants/extensions-catalogs.test.ts+++ b/__tests__/constants/extensions-catalogs.test.ts@@ -34,6 +34,43 @@ describe("OpenHands extensions catalogs", () => {);});+ it("patches Linear to the streamable HTTP /mcp endpoint with bearer auth", () => {+ // Arrange: upstream still ships the removed /sse SSE transport; the+ // marketplace catalog must serve the patched entry instead.+ const catalog = getMcpMarketplaceCatalog(INTEGRATION_CATALOG);++ // Act+ const linear = catalog.find((entry) => entry.id === "linear")!;++ // Assert+ expect(getDefaultMcpTransport(linear)).toEqual({+ kind: "shttp",+ url: "https://mcp.linear.app/mcp",+ apiKeyOptional: true,+ });+ expect(linear.docsUrl).toBe("https://linear.app/docs/mcp");+ const mcpOption = linear.connectionOptions.find(+ (option) => option.transport?.kind === "shttp",+ );+ expect(mcpOption?.auth.strategy).toBe("bearer");+ });++ it("does not mutate the imported catalog when patching Linear", () => {+ // Arrange/Act: run the patch, then inspect the raw imported entry.+ getMcpMarketplaceCatalog(INTEGRATION_CATALOG);+ const raw = INTEGRATION_CATALOG.find((entry) => entry.id === "linear");++ // Assert: the shared JSON module still carries the upstream values.+ const rawOption = raw?.connectionOptions.find(+ (option) => option.transport?.kind === "sse",+ );+ expect(rawOption?.transport).toEqual({+ kind: "sse",+ url: "https://mcp.linear.app/sse",+ apiKeyOptional: true,+ });+ });+it("drops deprecated MCP entries that no longer have maintained replacements", () => {const catalogIds = new Set(getMcpMarketplaceCatalog(INTEGRATION_CATALOG).map((entry) => entry.id),diff --git a/__tests__/utils/mcp-config.test.ts b/__tests__/utils/mcp-config.test.tsindex 1fa12ef79c..691018fbec 100644--- a/__tests__/utils/mcp-config.test.ts+++ b/__tests__/utils/mcp-config.test.ts@@ -151,3 +151,102 @@ describe("toSdkMcpConfig", () => {expect("myname" in out2).toBe(true);});});++describe("parseMcpConfig β deprecated Linear SSE migration", () => {+ // Linear removed its MCP SSE transport; persisted configs that still+ // point at https://mcp.linear.app/sse must be rewritten to streamable+ // HTTP at https://mcp.linear.app/mcp.++ it("migrates a legacy Linear SSE server to the /mcp endpoint", () => {+ // Arrange+ const persisted = {+ mcpServers: {+ sse: { url: "https://mcp.linear.app/sse", transport: "sse" },+ },+ };++ // Act+ const parsed = parseMcpConfig(persisted);++ // Assert+ expect(parsed.sse_servers).toEqual([]);+ expect(parsed.shttp_servers).toEqual([+ { url: "https://mcp.linear.app/mcp" },+ ]);+ });++ it("preserves the api key and tolerates a trailing slash when migrating", () => {+ // Arrange+ const persisted = {+ mcpServers: {+ sse: {+ url: "https://mcp.linear.app/sse/",+ transport: "sse",+ auth: "lin_api_secret",+ },+ },+ };++ // Act+ const parsed = parseMcpConfig(persisted);++ // Assert+ expect(parsed.shttp_servers).toEqual([+ { url: "https://mcp.linear.app/mcp", api_key: "lin_api_secret" },+ ]);+ });++ it("leaves non-Linear SSE servers untouched", () => {+ // Arrange+ const persisted = {+ mcpServers: {+ sse: { url: "https://other.example/sse", transport: "sse" },+ },+ };++ // Act+ const parsed = parseMcpConfig(persisted);++ // Assert+ expect(parsed.sse_servers).toEqual([{ url: "https://other.example/sse" }]);+ expect(parsed.shttp_servers).toEqual([]);+ });++ it("keeps a hand-added /mcp entry instead of duplicating it on migration", () => {+ // Arrange: legacy SSE install plus a manual /mcp entry that already+ // carries its own credential β the manual entry must win.+ const persisted = {+ mcpServers: {+ sse: { url: "https://mcp.linear.app/sse", transport: "sse" },+ shttp: { url: "https://mcp.linear.app/mcp", auth: "manual_key" },+ },+ };++ // Act+ const parsed = parseMcpConfig(persisted);++ // Assert+ expect(parsed.shttp_servers).toEqual([+ { url: "https://mcp.linear.app/mcp", api_key: "manual_key" },+ ]);+ });++ it("persists the migration as an shttp server on the next save", () => {+ // Arrange: the exact broken state from the field β the server key+ // "sse" is what produced the rejected `sse_save_comment` tool name.+ const persisted = {+ mcpServers: {+ sse: { url: "https://mcp.linear.app/sse", transport: "sse" },+ },+ };++ // Act: parse (load) then serialize (what every MCP save does).+ const written = toSdkMcpConfig(parseMcpConfig(persisted));++ // Assert: re-persisted under the shttp key with no transport field,+ // so the backend connects via streamable HTTP to the new endpoint.+ expect(written).toEqual({+ mcpServers: { shttp: { url: "https://mcp.linear.app/mcp" } },+ });+ });+});diff --git a/__tests__/utils/mcp-marketplace-utils.test.ts b/__tests__/utils/mcp-marketplace-utils.test.tsindex 5cfa5b835b..899647fdab 100644--- a/__tests__/utils/mcp-marketplace-utils.test.ts+++ b/__tests__/utils/mcp-marketplace-utils.test.ts@@ -69,22 +69,22 @@ describe("findInstalledMatch", () => {expect(result).toEqual(expect.objectContaining({ id: "stdio-0" }));});- it("matches SSE servers loosely on URL", () => {+ it("matches HTTP servers loosely on URL", () => {const result = findInstalledMatch(getDefaultMcpTransport(linearEntry)!, [{- id: "sse-0",- type: "sse",- url: "https://mcp.linear.app/sse/",+ id: "shttp-0",+ type: "shttp",+ url: "https://mcp.linear.app/mcp/",},]);- expect(result).toEqual(expect.objectContaining({ id: "sse-0" }));+ expect(result).toEqual(expect.objectContaining({ id: "shttp-0" }));});it("returns null when servers carry malformed urls (defensive)", () => {const result = findInstalledMatch(getDefaultMcpTransport(linearEntry)!, [// Cast to any to simulate runtime data slipping past the type.// eslint-disable-next-line @typescript-eslint/no-explicit-any- { id: "sse-0", type: "sse", url: undefined as any },+ { id: "shttp-0", type: "shttp", url: undefined as any },]);expect(result).toBeNull();});@@ -236,19 +236,19 @@ describe("findCatalogEntryForServer", () => {).toBeUndefined();});- it("matches an SSE server whose URL differs only by trailing slash", () => {+ it("matches an HTTP server whose URL differs only by trailing slash", () => {// Regression coverage for the strict-=== URL match that previously// diverged from findInstalledMatch and caused installed cards to// render the generic icon while the marketplace tile said// "Installed".const linear = mcpMarketplace.find((e) => e.id === "linear")!;const linearTransport = getDefaultMcpTransport(linear);- if (linearTransport?.kind !== "sse") {- throw new Error("Linear template should be SSE");+ if (linearTransport?.kind !== "shttp") {+ throw new Error("Linear template should be shttp");}const normalizedUrl = linearTransport.url.replace(/\/$/, "");const match = findCatalogEntryForServer(- { id: "sse-0", type: "sse", url: `${normalizedUrl}/` },+ { id: "shttp-0", type: "shttp", url: `${normalizedUrl}/` },mcpMarketplace,);expect(match?.id).toBe("linear");diff --git a/src/utils/mcp-config.ts b/src/utils/mcp-config.tsindex 68c8915c40..14e36f729e 100644--- a/src/utils/mcp-config.ts+++ b/src/utils/mcp-config.ts@@ -12,6 +12,25 @@ const EMPTY_MCP_CONFIG: MCPConfig = {shttp_servers: [],};+const LINEAR_DEPRECATED_SSE_URL = "https://mcp.linear.app/sse";+const LINEAR_SHTTP_URL = "https://mcp.linear.app/mcp";++/**+ * Linear removed its MCP SSE transport (the /sse endpoint rejects every+ * call since 2026-04-08). Detect persisted configs that still point at+ * the dead endpoint so they can be migrated to streamable HTTP at the+ * /mcp replacement. Matches only the exact deprecated URL (tolerating a+ * trailing slash or query string) β nothing else is rewritten.+ */+function isDeprecatedLinearSse(+ url: string,+ transport: string | undefined,+): boolean {+ if (transport !== "sse") return false;+ const normalized = url.split("?")[0].replace(/\/+$/, "");+ return normalized === LINEAR_DEPRECATED_SSE_URL;+}+type SdkMcpServerConfig = Record<string, SettingsValue>;type SdkMcpConfig = { mcpServers: Record<string, SdkMcpServerConfig> };@@ -37,6 +56,10 @@ export function parseMcpConfig(value: unknown): MCPConfig {const sseServers: (string | MCPSSEServer)[] = [];const stdioServers: MCPStdioServer[] = [];const shttpServers: (string | MCPSHTTPServer)[] = [];+ // Legacy Linear SSE entries rewritten to the /mcp endpoint. Collected+ // separately and merged after the loop so an existing hand-added /mcp+ // entry (with its own api_key/timeout) wins over the migrated one.+ const migratedShttpServers: MCPSHTTPServer[] = [];const mcpServers = obj.mcpServers as Record<string, Record<string, unknown>>;@@ -51,7 +74,11 @@ export function parseMcpConfig(value: unknown): MCPConfig {const apiKey =typeof auth === "string" && auth !== "oauth" ? auth : undefined;- if (transport === "sse") {+ if (isDeprecatedLinearSse(url, transport)) {+ const server: MCPSHTTPServer = { url: LINEAR_SHTTP_URL };+ if (apiKey) server.api_key = apiKey;+ migratedShttpServers.push(server);+ } else if (transport === "sse") {const server: MCPSSEServer = { url };if (apiKey) server.api_key = apiKey;sseServers.push(server);@@ -78,6 +105,15 @@ export function parseMcpConfig(value: unknown): MCPConfig {}}+ const normalizeUrl = (u: string) => u.replace(/\/+$/, "");+ for (const migrated of migratedShttpServers) {+ const alreadyPresent = shttpServers.some((entry) => {+ const entryUrl = typeof entry === "string" ? entry : entry.url;+ return normalizeUrl(entryUrl) === normalizeUrl(migrated.url);+ });+ if (!alreadyPresent) shttpServers.push(migrated);+ }+return {sse_servers: sseServers,stdio_servers: stdioServers,diff --git a/src/utils/mcp-marketplace-utils.ts b/src/utils/mcp-marketplace-utils.tsindex 24f6448bd2..9b7f7d7251 100644--- a/src/utils/mcp-marketplace-utils.ts+++ b/src/utils/mcp-marketplace-utils.ts@@ -59,10 +59,56 @@ export function getDefaultMcpTransport(return getDefaultMcpConnectionOption(entry)?.transport;}+const LINEAR_DEPRECATED_SSE_URL = "https://mcp.linear.app/sse";+const LINEAR_SHTTP_URL = "https://mcp.linear.app/mcp";+const LINEAR_DOCS_URL = "https://linear.app/docs/mcp";++/**+ * Upstream @openhands/extensions still ships Linear's deprecated SSE+ * transport (removed upstream on 2026-04-08; the /sse endpoint now+ * rejects every call). Rewrite the entry to streamable HTTP at the+ * /mcp replacement endpoint until the pinned dependency catches up.+ *+ * The /mcp endpoint authenticates via OAuth 2.1 or a Linear API key+ * sent as "Authorization: Bearer <token>". This client has no+ * interactive OAuth flow for MCP installs, so switch the auth+ * strategy from "none" to "bearer" β the install modal then offers+ * an (optional) API key field and the agent server forwards it as a+ * Bearer header.+ *+ * Patches immutably β the imported catalog JSON is shared module+ * state and must not be mutated.+ */+function patchLinearEntry(entry: MarketplaceEntry): MarketplaceEntry {+ if (entry.id !== "linear") return entry;+ return {+ ...entry,+ docsUrl: LINEAR_DOCS_URL,+ installHint:+ "Authenticate with a Linear API key (Linear β Settings β Security & access) β sent as a Bearer token. Optional when the endpoint accepts your OAuth session.",+ connectionOptions: entry.connectionOptions.map((option) =>+ option.transport?.kind === "sse" &&+ urlsMatch(option.transport.url, LINEAR_DEPRECATED_SSE_URL)+ ? {+ ...option,+ auth: { ...option.auth, strategy: "bearer" as const },+ transport: {+ kind: "shttp" as const,+ url: LINEAR_SHTTP_URL,+ apiKeyOptional: option.transport.apiKeyOptional,+ },+ }+ : option,+ ),+ };+}+export function getMcpMarketplaceCatalog(catalog: MarketplaceEntry[],): MarketplaceEntry[] {- return catalog.filter((entry) => !!getDefaultMcpConnectionOption(entry));+ return catalog+ .map(patchLinearEntry)+ .filter((entry) => !!getDefaultMcpConnectionOption(entry));}const tryUrl = (raw: string): URL | null => {