From 4a6dacec5e4afb69f211458e08be5233c57dd307 Mon Sep 17 00:00:00 2001 From: James Long Date: Thu, 22 Oct 2026 15:56:44 -0400 Subject: [PATCH] feat(server): add client MCP websocket endpoint (experimental) (#57505) --- packages/client/src/effect/api/api.ts | 11 +- .../client/src/effect/generated/client.ts | 11 + .../client/src/promise/generated/client.ts | 17 + .../client/src/promise/generated/types.ts | 26 +- packages/core/src/pty/ticket.ts | 32 +- packages/core/test/pty/ticket.test.ts | 12 + packages/protocol/src/api.ts | 10 +- packages/protocol/src/client.ts | 10 +- packages/protocol/src/groups/mcp.ts | 250 ++++++++------ packages/server/src/handlers/mcp.ts | 104 +++++- .../server/src/middleware/authorization.ts | 7 +- packages/server/src/process.ts | 4 +- packages/server/test/client-mcp.test.ts | 305 ++++++++++++++++++ packages/server/test/fetch.test.ts | 12 + 14 files changed, 687 insertions(+), 124 deletions(-) create mode 100644 packages/server/test/client-mcp.test.ts diff --git a/packages/client/src/effect/api/api.ts b/packages/client/src/effect/api/api.ts index 7b740e56765..2fdb04475c6 100644 --- a/packages/client/src/effect/api/api.ts +++ b/packages/client/src/effect/api/api.ts @@ -29,13 +29,13 @@ import type { Form } from "@opencode/schema/form" import type { Provider } from "@opencode/schema/provider" import type { Integration } from "@opencode/schema/integration" import type { Mcp } from "@opencode/schema/mcp" +import type { PtyTicket } from "@opencode/schema/pty-ticket" import type { Credential } from "@opencode/schema/credential" import type { PermissionSaved } from "@opencode/schema/permission-saved" import type { FileSystem } from "@opencode/schema/filesystem" import type { Command } from "@opencode/schema/command" import type { OpenCodeEvent } from "@opencode/protocol/groups/event" import type { Pty } from "@opencode/schema/pty" -import type { PtyTicket } from "@opencode/schema/pty-ticket" import type { Reference } from "@opencode/schema/reference" import type { Worktree } from "@opencode/schema/worktree" import type { Vcs } from "@opencode/schema/vcs" @@ -1669,6 +1669,14 @@ export type McpResourceCatalogOperation = ( input?: McpResourceCatalogInput, ) => Effect.Effect +export type McpClientTokenInput = { + readonly location?: { readonly directory?: string | undefined } | undefined + readonly name: string + readonly "x-opencode-ticket"?: string | undefined +} +export type McpClientTokenOutput = { readonly location: Location.PublicRef; readonly data: PtyTicket.ConnectToken } +export type McpClientTokenOperation = (input: McpClientTokenInput) => Effect.Effect + export interface McpApi { readonly list: McpListOperation readonly add: McpAddOperation @@ -1676,6 +1684,7 @@ export interface McpApi { readonly connect: McpConnectOperation readonly disconnect: McpDisconnectOperation readonly resource: { readonly catalog: McpResourceCatalogOperation } + readonly client: { readonly token: McpClientTokenOperation } } export type CredentialListOutput = ReadonlyArray diff --git a/packages/client/src/effect/generated/client.ts b/packages/client/src/effect/generated/client.ts index 6bc3693c131..8459a58e041 100644 --- a/packages/client/src/effect/generated/client.ts +++ b/packages/client/src/effect/generated/client.ts @@ -160,6 +160,8 @@ import type { McpDisconnectOutput, McpResourceCatalogInput, McpResourceCatalogOutput, + McpClientTokenInput, + McpClientTokenOutput, CredentialListOutput, CredentialCreateInput, CredentialCreateOutput, @@ -1087,6 +1089,14 @@ const EndpointMcpResourceCatalog = (raw: RawClient["server.mcp"]) => (input?: Mc raw["mcp.resource.catalog"]({ query: { location: input?.["location"] } }).pipe(Effect.mapError(mapClientError)), ) +const EndpointMcpClientToken = (raw: RawClient["server.mcp"]) => (input: McpClientTokenInput) => + preserveEffect()( + raw["mcp.clientToken"]({ + query: { location: input["location"], name: input["name"] }, + headers: { "x-opencode-ticket": input["x-opencode-ticket"] }, + }).pipe(Effect.mapError(mapClientError)), + ) + const adaptGroupMcp = (raw: RawClient["server.mcp"]) => ({ list: EndpointMcpList(raw), add: EndpointMcpAdd(raw), @@ -1094,6 +1104,7 @@ const adaptGroupMcp = (raw: RawClient["server.mcp"]) => ({ connect: EndpointMcpConnect(raw), disconnect: EndpointMcpDisconnect(raw), resource: { catalog: EndpointMcpResourceCatalog(raw) }, + client: { token: EndpointMcpClientToken(raw) }, }) const EndpointCredentialList = (raw: RawClient["server.credential"]) => () => diff --git a/packages/client/src/promise/generated/client.ts b/packages/client/src/promise/generated/client.ts index c8348a656eb..388b4e801bc 100644 --- a/packages/client/src/promise/generated/client.ts +++ b/packages/client/src/promise/generated/client.ts @@ -154,6 +154,8 @@ import type { McpDisconnectOutput, McpResourceCatalogInput, McpResourceCatalogOutput, + McpClientTokenInput, + McpClientTokenOutput, CredentialListOutput, CredentialCreateInput, CredentialCreateOutput, @@ -1463,6 +1465,21 @@ export function make(options: ClientOptions) { requestOptions, ), }, + client: { + token: (input: McpClientTokenInput, requestOptions?: RequestOptions) => + request( + { + method: "POST", + path: `/api/experimental/client-mcp/token`, + query: { location: input["location"], name: input["name"] }, + headers: { "x-opencode-ticket": input["x-opencode-ticket"] }, + successStatus: 200, + declaredStatuses: [400, 401, 403, 404], + empty: false, + }, + requestOptions, + ), + }, }, credential: { list: (requestOptions?: RequestOptions) => diff --git a/packages/client/src/promise/generated/types.ts b/packages/client/src/promise/generated/types.ts index 5b3526d2c63..af129ebf00f 100644 --- a/packages/client/src/promise/generated/types.ts +++ b/packages/client/src/promise/generated/types.ts @@ -244,6 +244,8 @@ export type McpResourceTemplate = { mimeType?: string } +export type PtyTicketConnectToken = { ticket: string; expires_in: number } + export type CredentialKey = { type: "key"; key: string; metadata?: { [x: string]: JsonValue } } export type ProjectVcs = string @@ -285,8 +287,6 @@ export type SessionStatus = } | { type: "busy" } -export type PtyTicketConnectToken = { ticket: string; expires_in: number } - export type PersistentPtyHandoff = { directory: string; instanceID: string; ticket: string; expiresAt: number } export type ReferenceGitSource = { type: "git"; repository: string; branch?: string } @@ -2859,6 +2859,10 @@ export type McpServerNotFoundError = { export const isMcpServerNotFoundError = (value: unknown): value is McpServerNotFoundError => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "McpServerNotFoundError" +export type ForbiddenError = { readonly _tag: "ForbiddenError"; readonly message: string } +export const isForbiddenError = (value: unknown): value is ForbiddenError => + typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ForbiddenError" + export type ProjectNotFoundError = { readonly _tag: "ProjectNotFoundError" readonly projectID: string @@ -2909,10 +2913,6 @@ export type PtyNotFoundError = { readonly _tag: "PtyNotFoundError"; readonly pty export const isPtyNotFoundError = (value: unknown): value is PtyNotFoundError => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "PtyNotFoundError" -export type ForbiddenError = { readonly _tag: "ForbiddenError"; readonly message: string } -export const isForbiddenError = (value: unknown): value is ForbiddenError => - typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ForbiddenError" - export type ShellNotFoundError = { readonly _tag: "ShellNotFoundError"; readonly id: string; readonly message: string } export const isShellNotFoundError = (value: unknown): value is ShellNotFoundError => typeof value === "object" && value !== null && "_tag" in value && value["_tag"] === "ShellNotFoundError" @@ -5236,6 +5236,20 @@ export type McpResourceCatalogInput = { export type McpResourceCatalogOutput = { location: LocationPublicRef; data: McpResourceCatalog } +export type McpClientTokenInput = { + readonly location?: { + readonly location?: { readonly directory?: string | undefined } | undefined + readonly name: string + }["location"] + readonly name: { + readonly location?: { readonly directory?: string | undefined } | undefined + readonly name: string + }["name"] + readonly "x-opencode-ticket"?: { readonly "x-opencode-ticket"?: string | undefined }["x-opencode-ticket"] +} + +export type McpClientTokenOutput = { location: LocationPublicRef; data: PtyTicketConnectToken } + export type CredentialListOutput = { data: Array }["data"] export type CredentialCreateInput = { diff --git a/packages/core/src/pty/ticket.ts b/packages/core/src/pty/ticket.ts index 780957b0a99..fbf79a86cf5 100644 --- a/packages/core/src/pty/ticket.ts +++ b/packages/core/src/pty/ticket.ts @@ -11,8 +11,18 @@ const CAPACITY = 10_000 export const ConnectToken = PtyTicket.ConnectToken -export type Scope = { - readonly ptyID: Pty.ID +// A ticket authorizes one upgrade to one target: a PTY, or a client MCP connection by client name. +export type Target = + | { readonly ptyID: Pty.ID; readonly mcpClient?: never } + | { readonly mcpClient: string; readonly ptyID?: never } + +export type Scope = Target & { + readonly directory?: string + readonly workspaceID?: Workspace.ID +} + +type Stored = { + readonly target: string readonly directory?: string readonly workspaceID?: Workspace.ID } @@ -24,9 +34,17 @@ export interface Interface { export class Service extends Context.Service()("@opencode/PtyTicket") {} -function matches(record: Scope, input: Scope) { +function stored(scope: Scope): Stored { + return { + target: scope.ptyID !== undefined ? `pty:${scope.ptyID}` : `mcp:${scope.mcpClient}`, + directory: scope.directory, + workspaceID: scope.workspaceID, + } +} + +function matches(record: Stored, input: Stored) { return ( - record.ptyID === input.ptyID && record.directory === input.directory && record.workspaceID === input.workspaceID + record.target === input.target && record.directory === input.directory && record.workspaceID === input.workspaceID ) } @@ -37,16 +55,16 @@ const noLookup = () => Effect.die(new Error("PtyTicket cache must be used via se // Visible for tests so the TTL can be shortened. Production uses `layer` with the default TTL. export const make = (ttl: Duration.Input = DEFAULT_TTL) => Effect.gen(function* () { - const cache = yield* Cache.make({ capacity: CAPACITY, lookup: noLookup, timeToLive: ttl }) + const cache = yield* Cache.make({ capacity: CAPACITY, lookup: noLookup, timeToLive: ttl }) const expiresIn = Math.max(1, Math.round(Duration.toSeconds(Duration.fromInputUnsafe(ttl)))) return Service.of({ issue: Effect.fn("PtyTicket.issue")(function* (input) { const ticket = crypto.randomUUID() - yield* Cache.set(cache, ticket, input) + yield* Cache.set(cache, ticket, stored(input)) return { ticket, expires_in: expiresIn } }), consume: Effect.fn("PtyTicket.consume")(function* (input) { - return yield* Cache.invalidateWhen(cache, input.ticket, (stored) => matches(stored, input)) + return yield* Cache.invalidateWhen(cache, input.ticket, (record) => matches(record, stored(input))) }), }) }) diff --git a/packages/core/test/pty/ticket.test.ts b/packages/core/test/pty/ticket.test.ts index 92afc5091c1..437e39520bd 100644 --- a/packages/core/test/pty/ticket.test.ts +++ b/packages/core/test/pty/ticket.test.ts @@ -61,4 +61,16 @@ describe("PTY websocket tickets", () => { expect(yield* tickets.consume({ ptyID, workspaceID, ticket: issued.ticket })).toBe(true) }), ) + + it.live("keeps PTY and client MCP targets apart", () => + Effect.gen(function* () { + const tickets = yield* PtyTicket.Service + const pty = yield* tickets.issue({ ptyID: Pty.ID.ascending(), directory: "/tmp/a" }) + const mcp = yield* tickets.issue({ mcpClient: "tui", directory: "/tmp/a" }) + + expect(yield* tickets.consume({ mcpClient: "tui", directory: "/tmp/a", ticket: pty.ticket })).toBe(false) + expect(yield* tickets.consume({ mcpClient: "web", directory: "/tmp/a", ticket: mcp.ticket })).toBe(false) + expect(yield* tickets.consume({ mcpClient: "tui", directory: "/tmp/a", ticket: mcp.ticket })).toBe(true) + }), + ) }) diff --git a/packages/protocol/src/api.ts b/packages/protocol/src/api.ts index d509a8df8f6..4a7d793a02d 100644 --- a/packages/protocol/src/api.ts +++ b/packages/protocol/src/api.ts @@ -27,7 +27,7 @@ import { Authorization } from "./middleware/authorization.js" import { makeLocationGroup } from "./groups/location.js" import { IntegrationGroup } from "./groups/integration.js" import { WebSearchGroup } from "./groups/websearch.js" -import { McpGroup } from "./groups/mcp.js" +import { makeMcpGroup } from "./groups/mcp.js" import { CredentialGroup } from "./groups/credential.js" import { ProjectGroup } from "./groups/project.js" import { WorktreeGroup } from "./groups/worktree.js" @@ -42,7 +42,6 @@ type LocationGroups = | HttpApiGroup.AddMiddleware | HttpApiGroup.AddMiddleware | HttpApiGroup.AddMiddleware - | HttpApiGroup.AddMiddleware | HttpApiGroup.AddMiddleware | HttpApiGroup.AddMiddleware | HttpApiGroup.AddMiddleware @@ -57,6 +56,10 @@ type PtyGroups = Re typeof makePtyGroup > +type McpGroups = ReturnType< + typeof makeMcpGroup +> + type SessionGroups< SessionLocationId extends HttpApiMiddleware.AnyId, SessionLocationService, @@ -101,6 +104,7 @@ type ApiGroups< | LocationGroups | LocationGroup | PtyGroups + | McpGroups | FormGroups | SessionGroups | MixedMiddlewareGroups @@ -170,7 +174,7 @@ const makeApiFromGroup = < .add(VoiceGroup) .add(ProviderGroup.middleware(locationMiddleware)) .add(IntegrationGroup.middleware(locationMiddleware)) - .add(McpGroup.middleware(locationMiddleware)) + .add(makeMcpGroup(locationMiddleware)) .add(CredentialGroup) .add(ProjectGroup.middleware(locationMiddleware)) .add(makeFormGroup(locationMiddleware)) diff --git a/packages/protocol/src/client.ts b/packages/protocol/src/client.ts index ea860b14972..a428ec758e9 100644 --- a/packages/protocol/src/client.ts +++ b/packages/protocol/src/client.ts @@ -67,5 +67,11 @@ export const groupNames = { "server.config": "config", } as const -export const promiseOmitEndpoints = new Set(["pty.connect", "persistentPty.connect"]) -export const effectOmitEndpoints = new Set(["fs.read", "fs.write", "pty.connect", "persistentPty.connect"]) +export const promiseOmitEndpoints = new Set(["pty.connect", "persistentPty.connect", "mcp.client"]) +export const effectOmitEndpoints = new Set([ + "fs.read", + "fs.write", + "pty.connect", + "persistentPty.connect", + "mcp.client", +]) diff --git a/packages/protocol/src/groups/mcp.ts b/packages/protocol/src/groups/mcp.ts index 639466e7244..d32c57e9a70 100644 --- a/packages/protocol/src/groups/mcp.ts +++ b/packages/protocol/src/groups/mcp.ts @@ -1,103 +1,155 @@ import { Mcp } from "@opencode/schema/mcp" import { Location } from "@opencode/schema/location" -import { Schema } from "effect" -import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/http-api" -import { McpServerNotFoundError } from "../errors.js" +import { PtyTicket } from "@opencode/schema/pty-ticket" +import { Context, Schema } from "effect" +import { HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, HttpApiSchema, OpenApi } from "effect/http-api" +import { ForbiddenError, LocationNotFoundError, McpServerNotFoundError } from "../errors.js" import { LocationQuery, locationQueryOpenApi } from "./location.js" +import { PTY_CONNECT_TICKET_QUERY, PTY_CONNECT_TOKEN_HEADER } from "./pty.js" -export const McpGroup = HttpApiGroup.make("server.mcp") - .add( - HttpApiEndpoint.get("mcp.list", "/api/mcp", { - query: LocationQuery, - success: Location.response(Schema.Array(Mcp.Server)), - }) - .annotateMerge(locationQueryOpenApi) - .annotateMerge( - OpenApi.annotations({ - identifier: "mcp.list", - summary: "List MCP servers", - description: "Retrieve configured MCP servers and their connection status.", - }), - ), - ) - .add( - HttpApiEndpoint.put("mcp.add", "/api/experimental/mcp/:server", { - params: { server: Schema.String }, - query: LocationQuery, - // Wrapped in a struct because the client codegen flattens payload fields and cannot - // represent a top-level union payload. - payload: Schema.Struct({ config: Mcp.ServerConfig }), - success: HttpApiSchema.NoContent, - }) - .annotateMerge(locationQueryOpenApi) - .annotateMerge( - OpenApi.annotations({ - identifier: "experimental.mcp.add", - summary: "Add MCP server", - description: "Add an MCP server at runtime or replace an existing one, connecting it immediately.", - }), - ), - ) - .add( - HttpApiEndpoint.delete("mcp.remove", "/api/experimental/mcp/:server", { - params: { server: Schema.String }, - query: LocationQuery, - success: HttpApiSchema.NoContent, - error: McpServerNotFoundError, - }) - .annotateMerge(locationQueryOpenApi) - .annotateMerge( - OpenApi.annotations({ - identifier: "experimental.mcp.remove", - summary: "Remove MCP server", - description: "Stop an MCP server and remove it from the runtime set until restart.", - }), - ), - ) - .add( - HttpApiEndpoint.post("mcp.connect", "/api/experimental/mcp/:server/connect", { - params: { server: Schema.String }, - query: LocationQuery, - success: HttpApiSchema.NoContent, - error: McpServerNotFoundError, - }) - .annotateMerge(locationQueryOpenApi) - .annotateMerge( - OpenApi.annotations({ - identifier: "experimental.mcp.connect", - summary: "Connect MCP server", - description: "Connect an MCP server at runtime, overriding a disabled configuration until restart.", - }), - ), - ) - .add( - HttpApiEndpoint.post("mcp.disconnect", "/api/experimental/mcp/:server/disconnect", { - params: { server: Schema.String }, - query: LocationQuery, - success: HttpApiSchema.NoContent, - error: McpServerNotFoundError, - }) - .annotateMerge(locationQueryOpenApi) - .annotateMerge( - OpenApi.annotations({ - identifier: "experimental.mcp.disconnect", - summary: "Disconnect MCP server", - description: "Disconnect an MCP server at runtime, removing its tools until reconnected.", - }), - ), - ) - .add( - HttpApiEndpoint.get("mcp.resource.catalog", "/api/mcp/resource", { - query: LocationQuery, - success: Location.response(Mcp.ResourceCatalog), - }) - .annotateMerge(locationQueryOpenApi) - .annotateMerge( - OpenApi.annotations({ - identifier: "mcp.resource.catalog", - summary: "List MCP resources", - description: "Retrieve resources and resource templates from connected MCP servers.", - }), - ), - ) - .annotateMerge(OpenApi.annotations({ title: "mcp", description: "MCP server and resource routes." })) +export const MCP_CLIENT_PATH = "/api/experimental/client-mcp" + +export function hasMcpClientTicketURL(url: URL) { + return url.pathname === MCP_CLIENT_PATH && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY) +} + +const McpClientQuery = Schema.Struct({ + ...LocationQuery.fields, + name: Schema.String.check(Schema.isPattern(/^[a-zA-Z0-9_-]+$/)), +}) + +export const makeMcpGroup = ( + locationMiddleware: Context.Key, +) => + HttpApiGroup.make("server.mcp") + .add( + HttpApiEndpoint.get("mcp.list", "/api/mcp", { + query: LocationQuery, + success: Location.response(Schema.Array(Mcp.Server)), + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "mcp.list", + summary: "List MCP servers", + description: "Retrieve configured MCP servers and their connection status.", + }), + ), + ) + .add( + HttpApiEndpoint.put("mcp.add", "/api/experimental/mcp/:server", { + params: { server: Schema.String }, + query: LocationQuery, + // Wrapped in a struct because the client codegen flattens payload fields and cannot + // represent a top-level union payload. + payload: Schema.Struct({ config: Mcp.ServerConfig }), + success: HttpApiSchema.NoContent, + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "experimental.mcp.add", + summary: "Add MCP server", + description: "Add an MCP server at runtime or replace an existing one, connecting it immediately.", + }), + ), + ) + .add( + HttpApiEndpoint.delete("mcp.remove", "/api/experimental/mcp/:server", { + params: { server: Schema.String }, + query: LocationQuery, + success: HttpApiSchema.NoContent, + error: McpServerNotFoundError, + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "experimental.mcp.remove", + summary: "Remove MCP server", + description: "Stop an MCP server and remove it from the runtime set until restart.", + }), + ), + ) + .add( + HttpApiEndpoint.post("mcp.connect", "/api/experimental/mcp/:server/connect", { + params: { server: Schema.String }, + query: LocationQuery, + success: HttpApiSchema.NoContent, + error: McpServerNotFoundError, + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "experimental.mcp.connect", + summary: "Connect MCP server", + description: "Connect an MCP server at runtime, overriding a disabled configuration until restart.", + }), + ), + ) + .add( + HttpApiEndpoint.post("mcp.disconnect", "/api/experimental/mcp/:server/disconnect", { + params: { server: Schema.String }, + query: LocationQuery, + success: HttpApiSchema.NoContent, + error: McpServerNotFoundError, + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "experimental.mcp.disconnect", + summary: "Disconnect MCP server", + description: "Disconnect an MCP server at runtime, removing its tools until reconnected.", + }), + ), + ) + .add( + HttpApiEndpoint.get("mcp.resource.catalog", "/api/mcp/resource", { + query: LocationQuery, + success: Location.response(Mcp.ResourceCatalog), + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "mcp.resource.catalog", + summary: "List MCP resources", + description: "Retrieve resources and resource templates from connected MCP servers.", + }), + ), + ) + .add( + HttpApiEndpoint.post("mcp.clientToken", `${MCP_CLIENT_PATH}/token`, { + query: McpClientQuery, + headers: Schema.Struct({ [PTY_CONNECT_TOKEN_HEADER]: Schema.optional(Schema.String) }), + success: Location.response(PtyTicket.ConnectToken), + error: ForbiddenError, + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "experimental.mcp.client.token", + summary: "Create client MCP WebSocket token", + description: + "Create a short-lived single-use ticket for opening a client MCP WebSocket connection from a browser.", + }), + ), + ) + // The client handler checks origin and ticket before it boots the location itself. + .middleware(locationMiddleware) + .add( + HttpApiEndpoint.get("mcp.client", MCP_CLIENT_PATH, { + query: Schema.Struct({ ...McpClientQuery.fields, [PTY_CONNECT_TICKET_QUERY]: Schema.optional(Schema.String) }), + success: Schema.Boolean, + error: [ForbiddenError, LocationNotFoundError], + }) + .annotateMerge(locationQueryOpenApi) + .annotateMerge( + OpenApi.annotations({ + identifier: "experimental.mcp.client", + summary: "Attach client MCP server", + description: + "Upgrade to a WebSocket over which the client hosts an MCP server named after `name`; its tools stay available while the socket is open. One JSON-RPC message per text frame. Experimental: may change without compatibility guarantees.", + transform: (operation) => ({ ...operation, "x-websocket": true }), + }), + ), + ) + .annotateMerge(OpenApi.annotations({ title: "mcp", description: "MCP server and resource routes." })) diff --git a/packages/server/src/handlers/mcp.ts b/packages/server/src/handlers/mcp.ts index ce98c860279..a758253b5aa 100644 --- a/packages/server/src/handlers/mcp.ts +++ b/packages/server/src/handlers/mcp.ts @@ -1,15 +1,27 @@ +import { Location } from "@opencode/core/location" +import { LocationServiceMap } from "@opencode/core/location-service-map" import { Mcp } from "@opencode/core/mcp/index" -import { McpServerNotFoundError } from "@opencode/protocol/errors" -import { Effect } from "effect" +import { PtyTicket } from "@opencode/core/pty/ticket" +import { ForbiddenError, McpServerNotFoundError } from "@opencode/protocol/errors" +import { PTY_CONNECT_TOKEN_HEADER, PTY_CONNECT_TOKEN_HEADER_VALUE } from "@opencode/protocol/groups/pty" +import { Effect, Queue } from "effect" +import { HttpServerResponse } from "effect/http" import { HttpApiBuilder, HttpApiSchema } from "effect/http-api" +import { Socket } from "effect/socket" import { Api } from "../api" -import { response } from "../location" +import { CorsConfig, isAllowedRequestOrigin } from "../cors" +import { locationErrors, requestRef, response } from "../location" +import { type Outbound, runPtySocket } from "./pty-socket" const notFound = (effect: Effect.Effect) => effect.pipe(Effect.mapError((error) => new McpServerNotFoundError({ server: error.server, message: error.message }))) export const McpHandler = HttpApiBuilder.group(Api, "server.mcp", (handlers) => Effect.gen(function* () { + const locations = yield* LocationServiceMap.Service + const cors = yield* CorsConfig + const tickets = yield* PtyTicket.Service + return handlers .handle( "mcp.list", @@ -57,5 +69,91 @@ export const McpHandler = HttpApiBuilder.group(Api, "server.mcp", (handlers) => return yield* response(service.resourceCatalog()) }), ) + .handle( + "mcp.clientToken", + Effect.fn(function* (ctx) { + // The custom header forces a CORS preflight, so cross-origin pages cannot mint tickets. + if ( + ctx.headers[PTY_CONNECT_TOKEN_HEADER] !== PTY_CONNECT_TOKEN_HEADER_VALUE || + !isAllowedRequestOrigin(ctx.request.headers.origin, ctx.request.headers.host, cors) + ) + return yield* new ForbiddenError({ message: "Invalid client MCP connect token request" }) + const location = yield* Location.Service + return yield* response( + tickets.issue({ + mcpClient: ctx.query.name, + directory: location.directory, + workspaceID: location.workspaceID, + }), + ) + }), + ) + .handleRaw( + "mcp.client", + Effect.fn("McpHandler.client")(function* (ctx) { + if (!isAllowedRequestOrigin(ctx.request.headers.origin, ctx.request.headers.host, cors)) + return HttpServerResponse.empty({ status: 403 }) + + const name = ctx.query.name + const ref = LocationServiceMap.canonical(requestRef(ctx.request)) + if ( + ctx.query.ticket && + !(yield* tickets.consume({ + ticket: ctx.query.ticket, + mcpClient: name, + directory: ref.directory, + workspaceID: ref.workspaceID, + })) + ) + return HttpServerResponse.empty({ status: 403 }) + + return yield* Effect.gen(function* () { + const mcp = yield* Mcp.Service + const { McpSocketClient } = yield* Effect.promise(() => import("@opencode/core/mcp/socket-client")) + const socket = yield* Effect.orDie(ctx.request.upgrade) + const outbox = yield* Queue.unbounded() + const state = { attached: false, disconnected: false } + const transport = McpSocketClient.make({ + send: (text) => Queue.offerUnsafe(outbox, text), + // A failed attach closes the transport before reporting the error; ignore that close so the + // socket closes with 1011 below instead of a normal 1000. + close: (code, reason) => { + if (state.attached) Queue.offerUnsafe(outbox, new Socket.CloseEvent(code, reason)) + }, + }) + const decoder = new TextDecoder() + // The attachment lives in this scope, so it ends with the socket. + yield* mcp.attach(name, transport).pipe( + Effect.tap(() => + Effect.sync(() => { + state.attached = true + }), + ), + Effect.catch((error) => + state.disconnected + ? Effect.logInfo("client MCP disconnected during initialize", { name, error: error.message }) + : Effect.logError("client MCP attach failed", { name, error: error.message }).pipe( + Effect.andThen( + Effect.sync(() => Queue.offerUnsafe(outbox, new Socket.CloseEvent(1011, "attach failed"))), + ), + ), + ), + Effect.forkScoped, + ) + yield* runPtySocket({ + socket, + outbox, + // Frames should be text, but binary frames are accepted and decoded as UTF-8. + onMessage: (message) => + Effect.sync(() => transport.deliver(typeof message === "string" ? message : decoder.decode(message))), + detach: () => { + state.disconnected = true + transport.ended() + }, + }) + return HttpServerResponse.empty() + }).pipe(Effect.scoped, Effect.provide(locations.get(ref)), locationErrors) + }), + ) }), ) diff --git a/packages/server/src/middleware/authorization.ts b/packages/server/src/middleware/authorization.ts index fee1f49abff..67dbd994781 100644 --- a/packages/server/src/middleware/authorization.ts +++ b/packages/server/src/middleware/authorization.ts @@ -4,6 +4,7 @@ import { Authorization } from "@opencode/protocol/middleware/authorization" export { Authorization } from "@opencode/protocol/middleware/authorization" import { PTY_CONNECT_PATH, PTY_CONNECT_TICKET_QUERY } from "@opencode/protocol/groups/pty" import { PERSISTENT_PTY_CONNECT_PATH } from "@opencode/protocol/groups/persistent-pty" +import { MCP_CLIENT_PATH } from "@opencode/protocol/groups/mcp" import { PAIRING_CONNECT_PATH } from "@opencode/protocol/groups/server" import { Effect, Layer, Redacted } from "effect" import { Base64 } from "effect/encoding" @@ -79,12 +80,14 @@ export const authorizationLayer = Layer.effect( Effect.gen(function* () { const request = yield* HttpServerRequest.HttpServerRequest const route = yield* HttpRouter.RouteContext - // Ticketed PTY connects (browsers cannot set headers on WebSocket upgrades) and pairing links + // Ticketed PTY and client MCP connects (browsers cannot set headers on WebSocket upgrades) and pairing links // skip credential checks here; their handlers consume and validate the ticket or code. Use the // route selected by Effect so authorization and dispatch cannot disagree about the request path. const url = new URL(request.url, "http://localhost") if ( - ((route.route.path === PTY_CONNECT_PATH || route.route.path === PERSISTENT_PTY_CONNECT_PATH) && + ((route.route.path === PTY_CONNECT_PATH || + route.route.path === PERSISTENT_PTY_CONNECT_PATH || + route.route.path === MCP_CLIENT_PATH) && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY)) || route.route.path === PAIRING_CONNECT_PATH ) diff --git a/packages/server/src/process.ts b/packages/server/src/process.ts index d7f79a7e655..3abd8b81524 100644 --- a/packages/server/src/process.ts +++ b/packages/server/src/process.ts @@ -6,6 +6,7 @@ import { SessionRestart } from "@opencode/core/session/execution/restart" import { InstallationEvent } from "@opencode/schema/installation-event" import { hasPtyConnectTicketURL } from "@opencode/protocol/groups/pty" import { hasPersistentPtyConnectTicketURL } from "@opencode/protocol/groups/persistent-pty" +import { hasMcpClientTicketURL } from "@opencode/protocol/groups/mcp" import { isPairingConnectURL } from "@opencode/protocol/groups/server" import { Global } from "@opencode/util/global" import { Cause, Context, Effect, Exit, Latch, Layer, Option, Ref, Scope } from "effect" @@ -191,7 +192,8 @@ function dispatch( } if ( !isPairingConnectURL(url) && - (!ready || (!hasPtyConnectTicketURL(url) && !hasPersistentPtyConnectTicketURL(url))) && + (!ready || + (!hasPtyConnectTicketURL(url) && !hasPersistentPtyConnectTicketURL(url) && !hasMcpClientTicketURL(url))) && !(yield* authorizedRequest(request, auth)) ) return unauthorizedResponse(request) diff --git a/packages/server/test/client-mcp.test.ts b/packages/server/test/client-mcp.test.ts new file mode 100644 index 00000000000..5d3d122c078 --- /dev/null +++ b/packages/server/test/client-mcp.test.ts @@ -0,0 +1,305 @@ +import { expect } from "bun:test" +import { NodeHttpServer } from "@effect/platform-node" +import { Location } from "@opencode/core/location" +import { LocationServiceMap } from "@opencode/core/location-service-map" +import { Mcp } from "@opencode/core/mcp/index" +import { Session } from "@opencode/core/session" +import { Tool } from "@opencode/core/tool" +import { McpTool } from "@opencode/core/tool/mcp" +import { Context, Effect, Exit, Layer, Schedule, Scope } from "effect" +import { HttpRouter, HttpServer } from "effect/http" +import { createServer } from "node:http" +import path from "node:path" +import { tmpdirScoped } from "../../core/test/fixture/tmpdir" +import { it } from "../../core/test/lib/effect" +import { ServerProcess } from "../src/process" +import { createRoutes } from "../src/routes" + +// The DOM lib hides Bun's WebSocket constructor overload that accepts upgrade request headers. +declare const WebSocket: { + new (url: string | URL, options?: Bun.WebSocketOptions): globalThis.WebSocket +} + +const authorization = `Basic ${btoa("opencode:secret")}` + +const serve = Effect.fnUntraced(function* () { + const directory = (yield* tmpdirScoped("opencode-client-mcp-")).path + const context = yield* Layer.build( + createRoutes({ + password: "secret", + app: { version: "test-version" }, + database: { path: ":memory:" }, + models: { fetch: false }, + config: { directory, project: false, content: "{}" }, + fs: { filewatcher: false }, + }).pipe(Layer.provideMerge(NodeHttpServer.layerHttpServices)), + ) + const server = createServer() + const http = yield* NodeHttpServer.make(() => server, { port: 0, host: "127.0.0.1" }) + yield* Effect.addFinalizer(() => Effect.sync(() => server.closeAllConnections())) + yield* http + .serve(Context.get(context, HttpRouter.HttpRouter).asHttpEffect()) + .pipe(Effect.provide(NodeHttpServer.layerHttpServices)) + const base = HttpServer.formatAddress(http.address) + const location = LocationServiceMap.Service.get( + LocationServiceMap.canonical(Location.Ref.make({ directory: directory as Location.Ref["directory"] })), + ) + return { + base, + directory, + url: (query: Record) => { + const url = new URL("/api/experimental/client-mcp", base) + url.protocol = "ws:" + url.searchParams.set("location[directory]", directory) + for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value) + return url + }, + inLocation: (effect: Effect.Effect) => + effect.pipe(Effect.provide(location), Effect.provideContext(context)), + } +}) + +/** Hosts an MCP server over a WebSocket opened to the endpoint, recording each call's session. */ +const connectClient = (url: URL, headers?: Record) => + Effect.acquireRelease( + Effect.promise(async () => { + const socket = new WebSocket(url, { headers }) + const state = { open: false, initialized: false, closed: false, code: 0 } + const sessions: unknown[] = [] + const reply = (id: unknown, result: unknown) => socket.send(JSON.stringify({ jsonrpc: "2.0", id, result })) + socket.addEventListener("open", () => { + state.open = true + }) + socket.addEventListener("message", (event) => { + const message = JSON.parse(String(event.data)) + if (message.method === "initialize") + return reply(message.id, { + protocolVersion: message.params.protocolVersion, + capabilities: { tools: {} }, + serverInfo: { name: "test-client", version: "1.0.0" }, + }) + if (message.method === "notifications/initialized") { + state.initialized = true + return + } + if (message.method === "tools/list") + return reply(message.id, { + tools: [{ name: "open_terminal", description: "Open a terminal", inputSchema: { type: "object" } }], + }) + if (message.method === "tools/call") { + sessions.push(message.params._meta?.["ai.opencode/sessionID"]) + return reply(message.id, { content: [{ type: "text", text: "opened" }] }) + } + if (message.id !== undefined && message.method) reply(message.id, {}) + }) + socket.addEventListener("close", (event) => { + state.closed = true + state.code = event.code + }) + return { socket, state, sessions } + }), + (client) => Effect.sync(() => client.socket.close()), + ) + +const until = (check: () => boolean | Promise) => + Effect.promise(async () => check()).pipe( + Effect.flatMap((done) => (done ? Effect.void : Effect.fail("pending"))), + Effect.retry({ times: 500, schedule: Schedule.spaced("10 millis") }), + Effect.orDie, + ) + +const registryIDs = Effect.gen(function* () { + const registration = yield* McpTool.Service + yield* registration.flush + const registry = yield* Tool.Service + return (yield* registry.list()).map((tool) => tool.id) +}) + +it.live( + "attaches a client MCP server for the lifetime of its socket", + () => + Effect.gen(function* () { + const server = yield* serve() + const client = yield* connectClient(server.url({ name: "tui" }), { authorization }) + const tools = () => Effect.runPromise(server.inLocation(Mcp.Service.use((mcp) => mcp.tools()))) + + yield* until(async () => (await tools()).length > 0) + expect((yield* Effect.promise(tools)).map((tool) => [tool.server, tool.name])).toEqual([["tui", "open_terminal"]]) + yield* until(() => + Effect.runPromise(server.inLocation(registryIDs)).then((ids) => ids.includes("tui_open_terminal")), + ) + + const call = (sessionID: string) => + Effect.runPromise( + server.inLocation( + Mcp.Service.use((mcp) => + mcp.callTool({ server: "tui", name: "open_terminal", sessionID: Session.ID.make(sessionID) }), + ), + ), + ) + const result = yield* Effect.promise(() => call("ses_client_mcp")) + expect(result.content).toEqual([{ type: "text", text: "opened" }]) + expect(client.sessions).toEqual(["ses_client_mcp"]) + + // A second client with the same name stacks on top: it takes the calls while the first stays open. + const newer = yield* connectClient(server.url({ name: "tui" }), { authorization }) + yield* until(() => call("ses_newer").then(() => newer.sessions.length > 0)) + expect(newer.sessions.every((session) => session === "ses_newer")).toBeTrue() + expect(client.state.closed).toBeFalse() + + // Once the newest closes, calls fall back to the earlier client. + const before = client.sessions.length + newer.socket.close() + yield* until(() => newer.state.closed) + yield* until(() => + call("ses_fallback").then( + () => client.sessions.length > before, + () => false, + ), + ) + expect(client.sessions.at(-1)).toBe("ses_fallback") + + client.socket.close() + yield* until(async () => (await tools()).length === 0) + yield* until(() => + Effect.runPromise(server.inLocation(registryIDs)).then((ids) => !ids.includes("tui_open_terminal")), + ) + }), + 20_000, +) + +it.live( + "accepts a single-use ticket instead of credentials", + () => + Effect.gen(function* () { + const server = yield* serve() + const requestToken = (name: string, headers: Record) => { + const url = new URL("/api/experimental/client-mcp/token", server.base) + url.searchParams.set("location[directory]", server.directory) + url.searchParams.set("name", name) + return fetch(url, { method: "POST", headers }) + } + const token = (name: string) => + Effect.promise(async () => { + const response = await requestToken(name, { authorization, "x-opencode-ticket": "1" }) + expect(response.status).toBe(200) + return ((await response.json()) as { data: { ticket: string } }).data.ticket + }) + + // Without the preflight-forcing header, a ticket cannot be minted even with credentials. + expect((yield* Effect.promise(() => requestToken("web", { authorization }))).status).toBe(403) + + const unauthenticated = yield* connectClient(server.url({ name: "web" })) + yield* until(() => unauthenticated.state.closed) + expect(unauthenticated.state.open).toBeFalse() + + const ticket = yield* token("web") + const mismatched = yield* connectClient(server.url({ name: "other", ticket })) + yield* until(() => mismatched.state.closed) + expect(mismatched.state.open).toBeFalse() + + const otherDirectory = server.url({ name: "web", ticket: yield* token("web") }) + otherDirectory.protocol = "http:" + otherDirectory.searchParams.set("location[directory]", path.join(server.directory, "other")) + expect((yield* Effect.promise(() => fetch(otherDirectory))).status).toBe(403) + + const fresh = yield* token("web") + const client = yield* connectClient(server.url({ name: "web", ticket: fresh })) + yield* until(() => + Effect.runPromise(server.inLocation(Mcp.Service.use((mcp) => mcp.tools()))).then((tools) => + tools.some((tool) => tool.server === "web"), + ), + ) + expect(client.state.open).toBeTrue() + + const reused = yield* connectClient(server.url({ name: "web", ticket: fresh })) + yield* until(() => reused.state.closed) + expect(reused.state.open).toBeFalse() + + // The server's end of an accepted socket lives in the serving scope until the client disconnects. + client.socket.close() + yield* until(() => client.state.closed) + }), + 20_000, +) + +it.live( + "rejects an invalid client name", + () => + Effect.gen(function* () { + const server = yield* serve() + const url = server.url({ name: "bad name!" }) + url.protocol = "http:" + const response = yield* Effect.promise(() => fetch(url, { headers: { authorization } })) + expect(response.status).toBe(400) + + const client = yield* connectClient(server.url({ name: "bad.name" }), { authorization }) + yield* until(() => client.state.closed) + expect(client.state.open).toBeFalse() + }), + 20_000, +) + +it.live( + "closes with 1011 when the client rejects initialize", + () => + Effect.gen(function* () { + const server = yield* serve() + const state = yield* Effect.acquireRelease( + Effect.sync(() => { + const socket = new WebSocket(server.url({ name: "tui" }), { headers: { authorization } }) + const state = { socket, closed: false, code: 0 } + socket.addEventListener("message", (event) => { + const message = JSON.parse(String(event.data)) + if (message.method !== "initialize") return + socket.send( + JSON.stringify({ jsonrpc: "2.0", id: message.id, error: { code: -32603, message: "not today" } }), + ) + }) + socket.addEventListener("close", (event) => { + state.closed = true + state.code = event.code + }) + return state + }), + (state) => Effect.sync(() => state.socket.close()), + ) + yield* until(() => state.closed) + expect(state.code).toBe(1011) + }), + 20_000, +) + +it.live( + "shuts the server down while a client is attached", + () => + Effect.gen(function* () { + const directory = (yield* tmpdirScoped("opencode-client-mcp-")).path + // Released before the directory so the server lets go of it first; closing twice is a no-op. + const scope = yield* Effect.acquireRelease(Scope.make(), (scope) => Scope.close(scope, Exit.void)) + const server = yield* ServerProcess.start( + { + hostname: "127.0.0.1", + port: 0, + password: "secret", + app: { version: "test-version" }, + database: { path: ":memory:" }, + models: { fetch: false }, + config: { directory, project: false, content: "{}" }, + fs: { filewatcher: false }, + }, + { onListen: () => Effect.succeed(Effect.void) }, + ).pipe(Scope.provide(scope)) + const url = new URL("/api/experimental/client-mcp", HttpServer.formatAddress(server.address)) + url.protocol = "ws:" + url.searchParams.set("location[directory]", directory) + url.searchParams.set("name", "tui") + const client = yield* connectClient(url, { authorization }) + yield* until(() => client.state.initialized) + + const closed = yield* Scope.close(scope, Exit.void).pipe(Effect.timeoutOption("5 seconds")) + expect(closed._tag).toBe("Some") + yield* until(() => client.state.closed) + }), + 20_000, +) diff --git a/packages/server/test/fetch.test.ts b/packages/server/test/fetch.test.ts index 59f2429b722..c2be48131ed 100644 --- a/packages/server/test/fetch.test.ts +++ b/packages/server/test/fetch.test.ts @@ -259,6 +259,18 @@ it.live("applies custom CORS origins to HTTP responses and PTY ticket checks", ( ) expect(invalidTicket.status).toBe(403) + const invalidMcpTicket = yield* Effect.promise(() => + handler( + new Request( + "http://opencode.local/api/experimental/client-mcp?ticket=invalid&location[directory]=/tmp&name=tui", + { + headers: { origin }, + }, + ), + ), + ) + expect(invalidMcpTicket.status).toBe(403) + const connect = yield* Effect.promise(() => handler( new Request("http://opencode.local/api/pty/pty_missing/connect", {