feat(server): add client MCP websocket endpoint (experimental) (#57505)

This commit is contained in:
James Long
2026-10-22 15:56:44 -04:00
committed by GitHub
Unverified
parent 561b273fba
commit 4a6dacec5e
14 changed files with 687 additions and 124 deletions
+10 -1
View File
@@ -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<E = never> = (
input?: McpResourceCatalogInput,
) => Effect.Effect<McpResourceCatalogOutput, E>
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<E = never> = (input: McpClientTokenInput) => Effect.Effect<McpClientTokenOutput, E>
export interface McpApi<E = never> {
readonly list: McpListOperation<E>
readonly add: McpAddOperation<E>
@@ -1676,6 +1684,7 @@ export interface McpApi<E = never> {
readonly connect: McpConnectOperation<E>
readonly disconnect: McpDisconnectOperation<E>
readonly resource: { readonly catalog: McpResourceCatalogOperation<E> }
readonly client: { readonly token: McpClientTokenOperation<E> }
}
export type CredentialListOutput = ReadonlyArray<Credential.Entry>
@@ -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<McpClientTokenOutput>()(
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"]) => () =>
@@ -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<McpClientTokenOutput>(
{
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) =>
+20 -6
View File
@@ -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<CredentialEntry> }["data"]
export type CredentialCreateInput = {
+25 -7
View File
@@ -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<Service, Interface>()("@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<string, Scope>({ capacity: CAPACITY, lookup: noLookup, timeToLive: ttl })
const cache = yield* Cache.make<string, Stored>({ 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)))
}),
})
})
+12
View File
@@ -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)
}),
)
})
+7 -3
View File
@@ -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<LocationId extends HttpApiMiddleware.AnyId> =
| HttpApiGroup.AddMiddleware<typeof ProviderGroup, LocationId>
| HttpApiGroup.AddMiddleware<typeof IntegrationGroup, LocationId>
| HttpApiGroup.AddMiddleware<typeof WebSearchGroup, LocationId>
| HttpApiGroup.AddMiddleware<typeof McpGroup, LocationId>
| HttpApiGroup.AddMiddleware<typeof ProjectGroup, LocationId>
| HttpApiGroup.AddMiddleware<typeof FileSystemGroup, LocationId>
| HttpApiGroup.AddMiddleware<typeof CommandGroup, LocationId>
@@ -57,6 +56,10 @@ type PtyGroups<LocationId extends HttpApiMiddleware.AnyId, LocationService> = Re
typeof makePtyGroup<LocationId, LocationService>
>
type McpGroups<LocationId extends HttpApiMiddleware.AnyId, LocationService> = ReturnType<
typeof makeMcpGroup<LocationId, LocationService>
>
type SessionGroups<
SessionLocationId extends HttpApiMiddleware.AnyId,
SessionLocationService,
@@ -101,6 +104,7 @@ type ApiGroups<
| LocationGroups<LocationId>
| LocationGroup<LocationId, LocationService>
| PtyGroups<LocationId, LocationService>
| McpGroups<LocationId, LocationService>
| FormGroups<LocationId, LocationService>
| SessionGroups<SessionLocationId, SessionLocationService, FormLocationId, FormLocationService>
| MixedMiddlewareGroups<LocationId, LocationService, SessionLocationId, SessionLocationService>
@@ -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))
+8 -2
View File
@@ -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",
])
+151 -99
View File
@@ -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 = <LocationId extends HttpApiMiddleware.AnyId, LocationService>(
locationMiddleware: Context.Key<LocationId, LocationService>,
) =>
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." }))
+101 -3
View File
@@ -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 = <A, R>(effect: Effect.Effect<A, Mcp.NotFoundError, R>) =>
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<Outbound>()
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)
}),
)
}),
)
@@ -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
)
+3 -1
View File
@@ -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)
+305
View File
@@ -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<string, string>) => {
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: <A, E>(effect: Effect.Effect<A, E, Mcp.Service | Tool.Service | McpTool.Service>) =>
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<string, string>) =>
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<boolean>) =>
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<string, string>) => {
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<never, never>(
{
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,
)
+12
View File
@@ -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", {