@brightbeamai/chap-coordinator-mcp 0.2.9

package/dist/index.d.cts

@@ -0,0 +1,171 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import { Coordinator, Envelope } from '@brightbeamai/chap-coordinator';
+export { JsonSchema, SCHEMAS, TOOL_NAMES, coerceToolArgs, methodForTool, schemaFor } from './schemas.cjs';
+export { TOOL_DESCRIPTIONS } from './tools.cjs';
+
+/**
+ * Per-request protocol envelope (MCP 2026-07-28).
+ *
+ * The 2026 revision is stateless: instead of negotiating once through an
+ * `initialize` handshake, every request declares its protocol version and
+ * client capabilities in `_meta`, and the server accepts or rejects each
+ * request on its own. This module implements that classification so the
+ * TypeScript adapter behaves the same way the Python `mcp` 2.x SDK does,
+ * which enforces the same rules natively.
+ *
+ * Two version sets, deliberately different:
+ *
+ * - `MODERN_PROTOCOL_VERSIONS` is what may be declared per request. Only
+ *   revisions that use per-request metadata qualify, so `2025-11-25` is
+ *   not a legal per-request declaration: it is negotiated by handshake.
+ *   This is the set named in an `UnsupportedProtocolVersionError`, so a
+ *   client retrying from that list always retries with something usable.
+ *
+ * - `SUPPORTED_PROTOCOL_VERSIONS` is what `server/discover` advertises. It
+ *   spans both eras because CHAP serves both: a modern client uses
+ *   `2026-07-28` per request, a handshake-era client negotiates
+ *   `2025-11-25` through `initialize`.
+ */
+/**
+ * A JSON-RPC error carrying a spec-exact `message`.
+ *
+ * The SDK's own `McpError` rewrites the message to `MCP error <code>: <text>`
+ * and the protocol layer puts that rewritten string on the wire, which would
+ * make CHAP answer `MCP error -32022: Unsupported protocol version` where the
+ * specification, and the Python implementation, both say `Unsupported
+ * protocol version`. The protocol layer reads `code`, `message` and `data`
+ * off whatever is thrown, so a plain `Error` carrying those fields
+ * serialises exactly as written.
+ */
+declare class ProtocolError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** `_meta` key carrying the protocol version of a single request. */
+declare const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+/** `_meta` key carrying client identity. Optional per the specification. */
+declare const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+/** `_meta` key carrying client capabilities. Required on a modern request. */
+declare const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/**
+ * `UnsupportedProtocolVersionError`. The specification reserves -32020 to
+ * -32099 for its own codes; -32022 is the one it assigns to a version the
+ * server does not implement.
+ */
+declare const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** Revisions that may be declared in a per-request `_meta` envelope. */
+declare const MODERN_PROTOCOL_VERSIONS: readonly ["2026-07-28"];
+/**
+ * Revisions advertised by `server/discover`, newest first. The tool surface
+ * is identical across both: CHAP exposes plain tools with JSON Schema
+ * inputs, which the 2026-07-28 stateless core carries unchanged.
+ */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25"];
+/**
+ * Which era a single request belongs to. `modern` means it carried a valid
+ * per-request envelope; `legacy` means it carried no protocol version at
+ * all and therefore belongs to a handshake-negotiated session.
+ */
+type ProtocolEra = "modern" | "legacy";
+/**
+ * Classify one request by its `_meta` envelope, rejecting a malformed or
+ * unsupported one.
+ *
+ * The rejection ladder matches the Python SDK's, rung for rung, so the two
+ * implementations answer an identical probe identically:
+ *
+ * 1. no `_meta`, or no protocol version in it, is a handshake-era request
+ * 2. a declared version with no `clientCapabilities` is malformed: -32602
+ * 3. a non-string version is malformed: -32602
+ * 4. a version outside `MODERN_PROTOCOL_VERSIONS`: -32022
+ *
+ * @throws ProtocolError on a malformed or unsupported envelope.
+ */
+declare function classifyEnvelope(params: unknown): ProtocolEra;
+
+/**
+ * @brightbeamai/chap-coordinator-mcp
+ *
+ * MCP server adapter for a CHAP Coordinator. Wraps a Coordinator
+ * instance and exposes every CHAP method as an MCP tool.
+ *
+ * Spec target: MCP 2026-07-28 (current), serving MCP 2025-11-25
+ * clients as well. CHAP 0.2.
+ *
+ * Usage (stdio):
+ *
+ *   import { Coordinator } from "@brightbeamai/chap-coordinator";
+ *   import { makeChapMcpServer } from "@brightbeamai/chap-coordinator-mcp";
+ *   import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ *
+ *   const coord = new Coordinator({ ... });
+ *   const server = makeChapMcpServer(coord, { name: "chap", version: "0.2.9" });
+ *   await server.connect(new StdioServerTransport());
+ *
+ * Usage (Streamable HTTP): see reference/mcp-server-ts/server.ts.
+ *
+ * Architecture notes:
+ *
+ * - One Coordinator -> one MCP server. Multi-workspace is handled
+ *   inside the Coordinator (workspaces are addressable by id).
+ *
+ * - The adapter holds no state. Every tool call translates to a
+ *   JSON-RPC envelope and dispatches through coord.dispatch().
+ *
+ * - Tool naming follows "chap.<method>" so the prefix avoids
+ *   collisions with other MCP servers a client might load.
+ *
+ * - Tool inputs are described by JSON Schemas (not Zod) and are
+ *   passed through to the Coordinator without re-validating at the
+ *   MCP layer. The Coordinator's own dispatch validates params and
+ *   returns spec-correct JSON-RPC error codes, which we surface as
+ *   MCP tool errors. This keeps the schema definitions single-sourced.
+ *
+ * - Authentication is intentionally out of scope at this layer.
+ *   Apply OAuth 2.1 / Streamable HTTP auth at the transport layer
+ *   per MCP's auth model.
+ */
+
+/** `_meta` key carrying server identity (MCP 2026-07-28, SEP-2575). */
+declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/**
+ * Request schema for `server/discover` (MCP 2026-07-28, SEP-2575).
+ *
+ * Hand-written because the pinned SDK major predates the 2026 era. The
+ * shape is permissive on `params` so a probe carrying `_meta`
+ * (protocolVersion, clientInfo, clientCapabilities) validates, and a
+ * bare probe with no params validates too.
+ */
+declare const ServerDiscoverRequestSchema: z.ZodObject<{
+    method: z.ZodLiteral<"server/discover">;
+    params: z.ZodOptional<z.ZodObject<{
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+interface ChapMcpOptions {
+    /** Server name advertised to MCP clients. Default: "chap". */
+    name?: string;
+    /** Server version. Default: "0.2.9". */
+    version?: string;
+    /** Override the list of CHAP methods to expose. Default: all 39. */
+    toolFilter?: (toolName: string) => boolean;
+    /** Optional id generator for the envelopes emitted by tool calls. */
+    envelopeIdFactory?: () => string | number;
+}
+/**
+ * Wrap a CHAP Coordinator as an MCP server. The returned ``Server``
+ * has ``tools/list`` and ``tools/call`` handlers registered for every
+ * CHAP method; pass it to a transport (stdio, Streamable HTTP) to
+ * start serving.
+ */
+declare function makeChapMcpServer(coord: Coordinator, options?: ChapMcpOptions): Server;
+/**
+ * Lower-level helper: translate a tool call to a CHAP envelope and
+ * back. Useful for tests and for embedding the adapter inside a
+ * larger MCP server that registers its own additional tools.
+ */
+declare function dispatchToolCall(coord: Coordinator, toolName: string, args: Record<string, unknown>, envelopeId?: string | number): Envelope;
+
+export { type ChapMcpOptions, META_CLIENT_CAPABILITIES, META_CLIENT_INFO, META_PROTOCOL_VERSION, META_SERVER_INFO, MODERN_PROTOCOL_VERSIONS, type ProtocolEra, ProtocolError, SUPPORTED_PROTOCOL_VERSIONS, ServerDiscoverRequestSchema, UNSUPPORTED_PROTOCOL_VERSION, classifyEnvelope, dispatchToolCall, makeChapMcpServer };

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import { Coordinator, Envelope } from '@brightbeamai/chap-coordinator';
+export { JsonSchema, SCHEMAS, TOOL_NAMES, coerceToolArgs, methodForTool, schemaFor } from './schemas.js';
+export { TOOL_DESCRIPTIONS } from './tools.js';
+
+/**
+ * Per-request protocol envelope (MCP 2026-07-28).
+ *
+ * The 2026 revision is stateless: instead of negotiating once through an
+ * `initialize` handshake, every request declares its protocol version and
+ * client capabilities in `_meta`, and the server accepts or rejects each
+ * request on its own. This module implements that classification so the
+ * TypeScript adapter behaves the same way the Python `mcp` 2.x SDK does,
+ * which enforces the same rules natively.
+ *
+ * Two version sets, deliberately different:
+ *
+ * - `MODERN_PROTOCOL_VERSIONS` is what may be declared per request. Only
+ *   revisions that use per-request metadata qualify, so `2025-11-25` is
+ *   not a legal per-request declaration: it is negotiated by handshake.
+ *   This is the set named in an `UnsupportedProtocolVersionError`, so a
+ *   client retrying from that list always retries with something usable.
+ *
+ * - `SUPPORTED_PROTOCOL_VERSIONS` is what `server/discover` advertises. It
+ *   spans both eras because CHAP serves both: a modern client uses
+ *   `2026-07-28` per request, a handshake-era client negotiates
+ *   `2025-11-25` through `initialize`.
+ */
+/**
+ * A JSON-RPC error carrying a spec-exact `message`.
+ *
+ * The SDK's own `McpError` rewrites the message to `MCP error <code>: <text>`
+ * and the protocol layer puts that rewritten string on the wire, which would
+ * make CHAP answer `MCP error -32022: Unsupported protocol version` where the
+ * specification, and the Python implementation, both say `Unsupported
+ * protocol version`. The protocol layer reads `code`, `message` and `data`
+ * off whatever is thrown, so a plain `Error` carrying those fields
+ * serialises exactly as written.
+ */
+declare class ProtocolError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** `_meta` key carrying the protocol version of a single request. */
+declare const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+/** `_meta` key carrying client identity. Optional per the specification. */
+declare const META_CLIENT_INFO = "io.modelcontextprotocol/clientInfo";
+/** `_meta` key carrying client capabilities. Required on a modern request. */
+declare const META_CLIENT_CAPABILITIES = "io.modelcontextprotocol/clientCapabilities";
+/**
+ * `UnsupportedProtocolVersionError`. The specification reserves -32020 to
+ * -32099 for its own codes; -32022 is the one it assigns to a version the
+ * server does not implement.
+ */
+declare const UNSUPPORTED_PROTOCOL_VERSION = -32022;
+/** Revisions that may be declared in a per-request `_meta` envelope. */
+declare const MODERN_PROTOCOL_VERSIONS: readonly ["2026-07-28"];
+/**
+ * Revisions advertised by `server/discover`, newest first. The tool surface
+ * is identical across both: CHAP exposes plain tools with JSON Schema
+ * inputs, which the 2026-07-28 stateless core carries unchanged.
+ */
+declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25"];
+/**
+ * Which era a single request belongs to. `modern` means it carried a valid
+ * per-request envelope; `legacy` means it carried no protocol version at
+ * all and therefore belongs to a handshake-negotiated session.
+ */
+type ProtocolEra = "modern" | "legacy";
+/**
+ * Classify one request by its `_meta` envelope, rejecting a malformed or
+ * unsupported one.
+ *
+ * The rejection ladder matches the Python SDK's, rung for rung, so the two
+ * implementations answer an identical probe identically:
+ *
+ * 1. no `_meta`, or no protocol version in it, is a handshake-era request
+ * 2. a declared version with no `clientCapabilities` is malformed: -32602
+ * 3. a non-string version is malformed: -32602
+ * 4. a version outside `MODERN_PROTOCOL_VERSIONS`: -32022
+ *
+ * @throws ProtocolError on a malformed or unsupported envelope.
+ */
+declare function classifyEnvelope(params: unknown): ProtocolEra;
+
+/**
+ * @brightbeamai/chap-coordinator-mcp
+ *
+ * MCP server adapter for a CHAP Coordinator. Wraps a Coordinator
+ * instance and exposes every CHAP method as an MCP tool.
+ *
+ * Spec target: MCP 2026-07-28 (current), serving MCP 2025-11-25
+ * clients as well. CHAP 0.2.
+ *
+ * Usage (stdio):
+ *
+ *   import { Coordinator } from "@brightbeamai/chap-coordinator";
+ *   import { makeChapMcpServer } from "@brightbeamai/chap-coordinator-mcp";
+ *   import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+ *
+ *   const coord = new Coordinator({ ... });
+ *   const server = makeChapMcpServer(coord, { name: "chap", version: "0.2.9" });
+ *   await server.connect(new StdioServerTransport());
+ *
+ * Usage (Streamable HTTP): see reference/mcp-server-ts/server.ts.
+ *
+ * Architecture notes:
+ *
+ * - One Coordinator -> one MCP server. Multi-workspace is handled
+ *   inside the Coordinator (workspaces are addressable by id).
+ *
+ * - The adapter holds no state. Every tool call translates to a
+ *   JSON-RPC envelope and dispatches through coord.dispatch().
+ *
+ * - Tool naming follows "chap.<method>" so the prefix avoids
+ *   collisions with other MCP servers a client might load.
+ *
+ * - Tool inputs are described by JSON Schemas (not Zod) and are
+ *   passed through to the Coordinator without re-validating at the
+ *   MCP layer. The Coordinator's own dispatch validates params and
+ *   returns spec-correct JSON-RPC error codes, which we surface as
+ *   MCP tool errors. This keeps the schema definitions single-sourced.
+ *
+ * - Authentication is intentionally out of scope at this layer.
+ *   Apply OAuth 2.1 / Streamable HTTP auth at the transport layer
+ *   per MCP's auth model.
+ */
+
+/** `_meta` key carrying server identity (MCP 2026-07-28, SEP-2575). */
+declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/**
+ * Request schema for `server/discover` (MCP 2026-07-28, SEP-2575).
+ *
+ * Hand-written because the pinned SDK major predates the 2026 era. The
+ * shape is permissive on `params` so a probe carrying `_meta`
+ * (protocolVersion, clientInfo, clientCapabilities) validates, and a
+ * bare probe with no params validates too.
+ */
+declare const ServerDiscoverRequestSchema: z.ZodObject<{
+    method: z.ZodLiteral<"server/discover">;
+    params: z.ZodOptional<z.ZodObject<{
+        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>>;
+}, z.core.$strip>;
+interface ChapMcpOptions {
+    /** Server name advertised to MCP clients. Default: "chap". */
+    name?: string;
+    /** Server version. Default: "0.2.9". */
+    version?: string;
+    /** Override the list of CHAP methods to expose. Default: all 39. */
+    toolFilter?: (toolName: string) => boolean;
+    /** Optional id generator for the envelopes emitted by tool calls. */
+    envelopeIdFactory?: () => string | number;
+}
+/**
+ * Wrap a CHAP Coordinator as an MCP server. The returned ``Server``
+ * has ``tools/list`` and ``tools/call`` handlers registered for every
+ * CHAP method; pass it to a transport (stdio, Streamable HTTP) to
+ * start serving.
+ */
+declare function makeChapMcpServer(coord: Coordinator, options?: ChapMcpOptions): Server;
+/**
+ * Lower-level helper: translate a tool call to a CHAP envelope and
+ * back. Useful for tests and for embedding the adapter inside a
+ * larger MCP server that registers its own additional tools.
+ */
+declare function dispatchToolCall(coord: Coordinator, toolName: string, args: Record<string, unknown>, envelopeId?: string | number): Envelope;
+
+export { type ChapMcpOptions, META_CLIENT_CAPABILITIES, META_CLIENT_INFO, META_PROTOCOL_VERSION, META_SERVER_INFO, MODERN_PROTOCOL_VERSIONS, type ProtocolEra, ProtocolError, SUPPORTED_PROTOCOL_VERSIONS, ServerDiscoverRequestSchema, UNSUPPORTED_PROTOCOL_VERSION, classifyEnvelope, dispatchToolCall, makeChapMcpServer };