@effect-uai/mcp 0.12.1

package/src/internal/rpc.ts

@@ -0,0 +1,189 @@
+/**
+ * Era-blind JSON-RPC 2.0 correlation core over a `Transport` (cdp.ts model):
+ * pending-`Deferred` map keyed by id, reader fiber that fails every pending
+ * request on transport close. Era behavior layers on top in era.ts.
+ */
+import { Cause, Deferred, Effect, HashMap, Option, Ref, type Scope, Stream } from "effect"
+import * as JSONL from "@effect-uai/core/JSONL"
+import { type McpError, McpProtocolError, McpTransportClosed } from "../McpError.js"
+import {
+  decodeInboundMessage,
+  type InboundMessage,
+  type JsonRpcId,
+  errorFrame,
+  notificationFrame,
+  requestFrame,
+  resultFrame,
+} from "./schema.js"
+
+/** Per-request transport hints (era headers on HTTP; stdio ignores them). */
+export type SendMeta = {
+  readonly headers?: Record<string, string>
+}
+
+/** The transport seam: one framed JSON message per `send` / `messages` element. */
+export type Transport = {
+  readonly send: (frame: string, meta?: SendMeta) => Effect.Effect<void, McpError>
+  readonly messages: Stream.Stream<string, McpError>
+}
+
+/** A server-initiated request (has `id`) or notification (no `id`). */
+export type Inbound = {
+  readonly id: Option.Option<JsonRpcId>
+  readonly method: string
+  readonly params: unknown
+}
+
+export type McpConnection = {
+  readonly request: (
+    method: string,
+    params?: unknown,
+    meta?: SendMeta,
+  ) => Effect.Effect<unknown, McpError>
+  readonly notify: (
+    method: string,
+    params?: unknown,
+    meta?: SendMeta,
+  ) => Effect.Effect<void, McpError>
+  /** Answer a server-initiated request (legacy era only). */
+  readonly respond: (id: JsonRpcId, result: unknown) => Effect.Effect<void, McpError>
+  readonly respondError: (
+    id: JsonRpcId,
+    code: number,
+    message: string,
+  ) => Effect.Effect<void, McpError>
+}
+
+type Pending = {
+  readonly method: string
+  readonly deferred: Deferred.Deferred<unknown, McpError>
+}
+
+const replyError = (method: string, error: NonNullable<InboundMessage["error"]>): McpError =>
+  new McpProtocolError({
+    method,
+    code: error.code,
+    ...(error.message !== undefined ? { reason: error.message } : {}),
+    raw: error,
+  })
+
+/**
+ * Open a scoped connection over an already-open transport. `onInbound`
+ * receives server-initiated frames; era.ts answers them via `transport.send`.
+ */
+export const open = (
+  transport: Transport,
+  onInbound: (inbound: Inbound) => Effect.Effect<void>,
+): Effect.Effect<McpConnection, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const pending = yield* Ref.make(HashMap.empty<JsonRpcId, Pending>())
+    const counter = yield* Ref.make(0)
+    const closeCause = yield* Ref.make<unknown>(undefined)
+
+    // Fail every in-flight request with one error. Shared by transport close
+    // and by unattributable server errors: a caller must never be left
+    // awaiting a reply that cannot arrive.
+    const failAllPending = (toError: (method: string) => McpError): Effect.Effect<void> =>
+      Ref.getAndSet(pending, HashMap.empty()).pipe(
+        Effect.flatMap((taken) =>
+          Effect.forEach(HashMap.values(taken), ({ deferred, method }) =>
+            Deferred.fail(deferred, toError(method)),
+          ),
+        ),
+        Effect.asVoid,
+      )
+
+    // An error no pending request can claim: a null id (JSON-RPC raises one
+    // before the request could be attributed) or an id we never issued. It
+    // correlates to nothing, so everything in flight takes it rather than
+    // waiting for a reply that cannot arrive. A *result* nobody claims is a
+    // late or duplicate reply, and is simply dropped.
+    const unattributable = (error: InboundMessage["error"]): Effect.Effect<void> =>
+      error === undefined ? Effect.void : failAllPending((method) => replyError(method, error))
+
+    const settle = ({ deferred, method }: Pending, message: InboundMessage): Effect.Effect<void> =>
+      Effect.asVoid(
+        message.error === undefined
+          ? Deferred.succeed(deferred, message.result ?? {})
+          : Deferred.fail(deferred, replyError(method, message.error)),
+      )
+
+    const reply = (id: JsonRpcId, message: InboundMessage): Effect.Effect<void> =>
+      Ref.modify(pending, (m) => [HashMap.get(m, id), HashMap.remove(m, id)]).pipe(
+        Effect.flatMap(
+          Option.match({
+            onNone: () => unattributable(message.error),
+            onSome: (entry) => settle(entry, message),
+          }),
+        ),
+      )
+
+    // A frame carrying a `method` is server-initiated; anything else is a
+    // reply, correlated by id.
+    const route = (message: InboundMessage): Effect.Effect<void> =>
+      Option.match(Option.fromNullishOr(message.method), {
+        onNone: () =>
+          Option.match(Option.fromNullishOr(message.id), {
+            onNone: () => unattributable(message.error),
+            onSome: (id) => reply(id, message),
+          }),
+        onSome: (method) =>
+          onInbound({ id: Option.fromNullishOr(message.id), method, params: message.params }),
+      })
+
+    // Unparseable and undecodable frames are dropped: one bad frame must not
+    // end an otherwise healthy connection.
+    const dispatch = (raw: string): Effect.Effect<void> =>
+      JSONL.parseSafe(raw).pipe(
+        Effect.flatMap((json) => Effect.option(decodeInboundMessage(json))),
+        Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: route })),
+      )
+
+    // Fail every still-pending request on transport close so callers never hang.
+    const failPending = Effect.gen(function* () {
+      const raw = yield* Ref.get(closeCause)
+      yield* failAllPending(
+        (method) => new McpTransportClosed({ method, reason: "connection closed", raw }),
+      )
+    })
+    yield* transport.messages.pipe(
+      Stream.runForEach(dispatch),
+      Effect.tapCause((cause) => Ref.set(closeCause, Cause.squash(cause))),
+      Effect.ensuring(failPending),
+      Effect.forkScoped,
+    )
+
+    const request = (
+      method: string,
+      params?: unknown,
+      meta?: SendMeta,
+    ): Effect.Effect<unknown, McpError> =>
+      Effect.gen(function* () {
+        const id: JsonRpcId = yield* Ref.updateAndGet(counter, (n) => n + 1)
+        const deferred = yield* Deferred.make<unknown, McpError>()
+        yield* Ref.update(pending, (m) => HashMap.set(m, id, { method, deferred }))
+        // `ensuring` reclaims the entry on send failure and interruption; on
+        // success dispatch has already removed it.
+        return yield* transport.send(requestFrame(id, method, params), meta).pipe(
+          Effect.flatMap(() => Deferred.await(deferred)),
+          Effect.ensuring(Ref.update(pending, (m) => HashMap.remove(m, id))),
+        )
+      })
+
+    const notify = (
+      method: string,
+      params?: unknown,
+      meta?: SendMeta,
+    ): Effect.Effect<void, McpError> => transport.send(notificationFrame(method, params), meta)
+
+    const respond = (id: JsonRpcId, result: unknown): Effect.Effect<void, McpError> =>
+      transport.send(resultFrame(id, result))
+
+    const respondError = (
+      id: JsonRpcId,
+      code: number,
+      message: string,
+    ): Effect.Effect<void, McpError> => transport.send(errorFrame(id, code, message))
+
+    return { request, notify, respond, respondError }
+  })

package/src/internal/schema.ts

@@ -0,0 +1,223 @@
+/**
+ * Self-contained MCP wire schemas, both protocol eras. The single source of
+ * truth for the wire format; nothing MCP-shaped is imported from effect.
+ * Decodes are deliberately loose (unknown extra fields pass through) so
+ * spec-compliant servers with richer payloads never fail the client.
+ */
+import { Option, Schema } from "effect"
+
+// ---------------------------------------------------------------------------
+// Protocol versions
+// ---------------------------------------------------------------------------
+
+/** Every protocol version this client can speak. */
+export const ProtocolVersion = Schema.Literals(["2026-07-28", "2025-11-25", "2025-06-18"])
+export type ProtocolVersion = typeof ProtocolVersion.Type
+
+/** Newest version we speak: the stateless protocol, and what the probe tries first. */
+export const LATEST_VERSION = "2026-07-28" satisfies ProtocolVersion
+
+/** The legacy handshake era we negotiate; 2025-11-25 is wire-compatible. */
+export const LEGACY_VERSION = "2025-06-18" satisfies ProtocolVersion
+
+const isProtocolVersion = Schema.is(ProtocolVersion)
+
+/** Narrow a server-offered version string to one we support. */
+export const asProtocolVersion = (raw: string): Option.Option<ProtocolVersion> =>
+  isProtocolVersion(raw) ? Option.some(raw) : Option.none()
+
+/**
+ * The JSON-RPC methods this client issues. Not to be confused with an HTTP
+ * method: on Streamable HTTP every one of these travels as a POST, and the
+ * name is mirrored into the `Mcp-Method` header.
+ */
+export const McpMethod = Schema.Literals([
+  "server/discover",
+  "initialize",
+  "tools/list",
+  "tools/call",
+])
+export type McpMethod = typeof McpMethod.Type
+
+/** Modern `_meta` keys (SEP-2575): every request self-describes its protocol. */
+export const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion"
+export const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo"
+export const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities"
+/** Servers identify themselves in each *result's* `_meta`, not at the top level. */
+export const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+
+export const CLIENT_INFO = { name: "@effect-uai/mcp", version: "0.12.1" }
+
+/** Modern JSON-RPC error codes. */
+export const CODE_HEADER_MISMATCH = -32020
+export const CODE_MISSING_CLIENT_CAPABILITY = -32021
+export const CODE_UNSUPPORTED_PROTOCOL_VERSION = -32022
+export const CODE_METHOD_NOT_FOUND = -32601
+
+/**
+ * A reply carrying one of these proves the server speaks a modern version, so
+ * era detection corrects and retries instead of falling back to `initialize`.
+ */
+export const MODERN_ERROR_CODES: ReadonlySet<number> = new Set([
+  CODE_HEADER_MISMATCH,
+  CODE_MISSING_CLIENT_CAPABILITY,
+  CODE_UNSUPPORTED_PROTOCOL_VERSION,
+])
+
+// ---------------------------------------------------------------------------
+// JSON-RPC envelope
+// ---------------------------------------------------------------------------
+
+export const JsonRpcId = Schema.Union([Schema.Number, Schema.String])
+export type JsonRpcId = typeof JsonRpcId.Type
+
+export const JsonRpcErrorObject = Schema.Struct({
+  code: Schema.Number,
+  message: Schema.optional(Schema.String),
+  data: Schema.optional(Schema.Unknown),
+})
+export type JsonRpcErrorObject = typeof JsonRpcErrorObject.Type
+
+/**
+ * Any inbound frame: a reply (`id` + `result`/`error`), a server-initiated
+ * request (`method` + `id`), or a notification (`method`, no `id`). One
+ * loose struct so the reader can classify without a union decode.
+ */
+export const InboundMessage = Schema.Struct({
+  // Null is legal and meaningful: JSON-RPC uses it for errors raised before a
+  // request could be attributed. Rejecting it would drop the frame entirely.
+  id: Schema.optional(Schema.NullOr(JsonRpcId)),
+  result: Schema.optional(Schema.Unknown),
+  error: Schema.optional(JsonRpcErrorObject),
+  method: Schema.optional(Schema.String),
+  params: Schema.optional(Schema.Unknown),
+})
+export type InboundMessage = typeof InboundMessage.Type
+
+export const decodeInboundMessage = Schema.decodeUnknownEffect(InboundMessage)
+
+// --- outbound frame builders -----------------------------------------------
+
+export const requestFrame = (id: JsonRpcId, method: string, params: unknown): string =>
+  JSON.stringify({ jsonrpc: "2.0", id, method, params: params ?? {} })
+
+export const notificationFrame = (method: string, params?: unknown): string =>
+  JSON.stringify(
+    params === undefined ? { jsonrpc: "2.0", method } : { jsonrpc: "2.0", method, params },
+  )
+
+export const resultFrame = (id: JsonRpcId, result: unknown): string =>
+  JSON.stringify({ jsonrpc: "2.0", id, result })
+
+export const errorFrame = (id: JsonRpcId, code: number, message: string): string =>
+  JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })
+
+// ---------------------------------------------------------------------------
+// Shared: tools
+// ---------------------------------------------------------------------------
+
+export const ToolInfo = Schema.Struct({
+  name: Schema.String,
+  description: Schema.optional(Schema.String),
+  inputSchema: Schema.Record(Schema.String, Schema.Unknown),
+})
+export type ToolInfo = typeof ToolInfo.Type
+
+/**
+ * Modern list results may carry cache metadata (`ttlMs` / `cacheScope`);
+ * v1 reads but does not act on them (input for a later refresh feature).
+ */
+export const ListToolsResult = Schema.Struct({
+  tools: Schema.Array(ToolInfo),
+  nextCursor: Schema.optional(Schema.String),
+  ttlMs: Schema.optional(Schema.Number),
+  cacheScope: Schema.optional(Schema.String),
+})
+export type ListToolsResult = typeof ListToolsResult.Type
+
+export const decodeListToolsResult = Schema.decodeUnknownEffect(ListToolsResult)
+
+// --- content blocks ---------------------------------------------------------
+
+export const TextContent = Schema.Struct({
+  type: Schema.Literal("text"),
+  text: Schema.String,
+})
+export type TextContent = typeof TextContent.Type
+
+/** Non-text blocks (image / audio / resource) are placeholder-summarized in v1. */
+export const OtherContent = Schema.Struct({
+  type: Schema.String,
+})
+
+export const ContentBlock = Schema.Union([TextContent, OtherContent])
+export type ContentBlock = typeof ContentBlock.Type
+
+export const isTextContent = Schema.is(TextContent)
+
+export const CallToolResult = Schema.Struct({
+  content: Schema.optionalKey(Schema.Array(ContentBlock)),
+  isError: Schema.optional(Schema.Boolean),
+  structuredContent: Schema.optional(Schema.Unknown),
+  // Required on modern results; absent on legacy ones.
+  resultType: Schema.optional(Schema.String),
+})
+export type CallToolResult = typeof CallToolResult.Type
+
+export const decodeCallToolResult = Schema.decodeUnknownEffect(CallToolResult)
+
+// ---------------------------------------------------------------------------
+// Modern era (2026-07-28)
+// ---------------------------------------------------------------------------
+
+export const ServerInfo = Schema.Struct({
+  name: Schema.String,
+  version: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+})
+export type ServerInfo = typeof ServerInfo.Type
+
+/** The subset of a result's `_meta` we read. */
+export const ResultMeta = Schema.Struct({
+  [META_SERVER_INFO]: Schema.optional(ServerInfo),
+})
+export type ResultMeta = typeof ResultMeta.Type
+
+export const DiscoverResult = Schema.Struct({
+  supportedVersions: Schema.Array(Schema.String),
+  capabilities: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  // Spec-conformant servers put identity in `_meta`; a top-level `serverInfo`
+  // is accepted too, since that is where the legacy handshake carries it.
+  _meta: Schema.optional(ResultMeta),
+  serverInfo: Schema.optional(ServerInfo),
+  instructions: Schema.optional(Schema.String),
+})
+export type DiscoverResult = typeof DiscoverResult.Type
+
+export const decodeDiscoverResult = Schema.decodeUnknownEffect(DiscoverResult)
+
+/**
+ * `data` of a `-32022` UnsupportedProtocolVersionError reply. Decoded, not
+ * hand-parsed: the shape is server-controlled and may carry extra fields.
+ */
+export const UnsupportedVersionData = Schema.Struct({
+  supported: Schema.optional(Schema.Array(Schema.String)),
+  requested: Schema.optional(Schema.NullOr(Schema.String)),
+})
+export type UnsupportedVersionData = typeof UnsupportedVersionData.Type
+
+export const decodeUnsupportedVersionData = Schema.decodeUnknownOption(UnsupportedVersionData)
+
+// ---------------------------------------------------------------------------
+// Legacy era (2025-06-18 / 2025-11-25)
+// ---------------------------------------------------------------------------
+
+export const InitializeResult = Schema.Struct({
+  protocolVersion: Schema.String,
+  capabilities: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
+  serverInfo: Schema.optional(ServerInfo),
+  instructions: Schema.optional(Schema.String),
+})
+export type InitializeResult = typeof InitializeResult.Type
+
+export const decodeInitializeResult = Schema.decodeUnknownEffect(InitializeResult)

package/src/internal/stdioTransport.ts

@@ -0,0 +1,63 @@
+/**
+ * stdio `Transport`: spawn the server, frame stdout as JSONL (one JSON message
+ * per line). Scoped, so the child is killed on scope close. Era-blind; the
+ * `meta.headers` a caller passes are HTTP-only and ignored here.
+ */
+import { Cause, Effect, Queue, type Scope, Stream } from "effect"
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process"
+import * as JSONL from "@effect-uai/core/JSONL"
+import { McpConnectFailed, type McpError, McpTransportClosed } from "../McpError.js"
+import type { Transport } from "./rpc.js"
+
+export type StdioConfig = {
+  readonly command: string
+  readonly args?: ReadonlyArray<string>
+  readonly env?: Record<string, string>
+  readonly cwd?: string
+}
+
+const encoder = new TextEncoder()
+
+export const make = (
+  config: StdioConfig,
+): Effect.Effect<Transport, McpError, Scope.Scope | ChildProcessSpawner.ChildProcessSpawner> =>
+  Effect.gen(function* () {
+    // Outbound frames go through a queue rendered as the child's stdin stream;
+    // `Queue.end` on scope close lets the child see a clean EOF.
+    const outbound = yield* Queue.make<Uint8Array, Cause.Done>()
+    const stdin = Stream.fromQueue(outbound)
+
+    const handle = yield* ChildProcess.make(config.command, [...(config.args ?? [])], {
+      ...(config.cwd !== undefined ? { cwd: config.cwd } : {}),
+      ...(config.env !== undefined ? { env: config.env } : {}),
+      stdin: { stream: stdin, endOnDone: true },
+      stdout: "pipe",
+      stderr: "pipe",
+      killSignal: "SIGTERM",
+      forceKillAfter: "2 seconds",
+    }).pipe(
+      Effect.mapError(
+        (cause) =>
+          new McpConnectFailed({ reason: `could not spawn ${config.command}`, raw: cause }),
+      ),
+    )
+    yield* Effect.addFinalizer(() => Queue.end(outbound))
+
+    const send = (frame: string): Effect.Effect<void, McpError> =>
+      Queue.offer(outbound, encoder.encode(`${frame}\n`)).pipe(
+        Effect.mapError(
+          (cause) =>
+            new McpTransportClosed({ reason: "server stdin closed", raw: cause }) as McpError,
+        ),
+        Effect.asVoid,
+      )
+
+    const messages = handle.stdout.pipe(
+      JSONL.fromBytes,
+      Stream.mapError(
+        (cause) => new McpTransportClosed({ reason: "server stdout closed", raw: cause }),
+      ),
+    )
+
+    return { send, messages } satisfies Transport
+  })