@brightbeamai/chap-coordinator-mcp 0.3.4 → 0.3.5

package/dist/index.d.cts

@@ -1,8 +1,9 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
-import { Coordinator, Envelope } from '@brightbeamai/chap-coordinator';
+import { Envelope, Coordinator } from '@brightbeamai/chap-coordinator';
 export { JsonSchema, SCHEMAS, TOOL_NAMES, coerceToolArgs, methodForTool, schemaFor } from './schemas.cjs';
-export { TOOL_ANNOTATIONS, TOOL_DESCRIPTIONS, ToolAnnotations } from './tools.cjs';
+export { AGENT_MCP_TOOLS, TOOL_ANNOTATIONS, TOOL_DESCRIPTIONS, ToolAnnotations } from './tools.cjs';
 
 /**
  * Per-request protocol envelope (MCP 2026-07-28).
@@ -101,10 +102,12 @@ declare function classifyEnvelope(params: unknown): ProtocolEra;
  *   import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
  *
  *   const coord = new Coordinator({ ... });
- *   const server = makeChapMcpServer(coord, { name: "chap", version: "0.3.4" });
+ *   const server = makeChapMcpServer(coord, { name: "chap", version: "0.3.5" });
  *   await server.connect(new StdioServerTransport());
  *
- * Usage (Streamable HTTP): see reference/mcp-server-ts/server.ts.
+ * Usage (HTTP): chapMcpHttpHandler(coord, options) answers a Node `http`
+ * request on an MCP endpoint, in both protocol eras, and refuses a request
+ * under a foreign Host or from a foreign Origin.
  *
  * Architecture notes:
  *
@@ -117,6 +120,11 @@ declare function classifyEnvelope(params: unknown): ProtocolEra;
  * - Tool naming follows "chap.<method>" so the prefix avoids
  *   collisions with other MCP servers a client might load.
  *
+ * - A server that is one participant's connection, such as an
+ *   agent's, takes `participant`: every call is made as that member,
+ *   and a call naming another `from` is refused. AGENT_MCP_TOOLS is
+ *   the tool set such a connection offers an agent.
+ *
  * - 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
@@ -144,21 +152,32 @@ declare const ServerDiscoverRequestSchema: z.ZodObject<{
         _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$loose>>;
 }, z.core.$strip>;
+/**
+ * What the server dispatches each call through: a Coordinator, or anything
+ * with the same `dispatch`, such as a client that forwards the envelope to a
+ * running server. The answer may be returned or promised.
+ */
+interface ChapDispatcher {
+    dispatch(envelope: Envelope): Envelope | Promise<Envelope>;
+}
 interface ChapMcpOptions {
     /** Server name advertised to MCP clients. Default: "chap". */
     name?: string;
-    /** Server version. Default: "0.3.4". */
+    /** Server version. Default: "0.3.5". */
     version?: string;
     /**
-     * Restrict the CHAP methods this server offers. Default: all 39. A tool the
-     * filter excludes is left out of the list and refused when called.
+     * Restrict the CHAP methods this server offers. Default: all of them. A
+     * tool the filter excludes is left out of the list and refused when called.
      */
     toolFilter?: (toolName: string) => boolean;
     /**
      * Make every call as this participant. `from` is filled in on each call,
      * and a call that names another `from` is refused. Use it where the server
      * is one participant's connection, such as an agent's, so the connection
-     * cannot act in anyone else's name. Default: each call names its own `from`.
+     * cannot act in anyone else's name. The tools then list `from` as optional,
+     * with this URI in its description. A `human:` URI is refused: a person
+     * decides in a desk, never through a connection made for an agent.
+     * Default: each call names its own `from`.
      */
     participant?: string;
     /** Optional id generator for the envelopes emitted by tool calls. */
@@ -170,12 +189,67 @@ interface ChapMcpOptions {
  * CHAP method; pass it to a transport (stdio, Streamable HTTP) to
  * start serving.
  */
-declare function makeChapMcpServer(coord: Coordinator, options?: ChapMcpOptions): Server;
+declare function makeChapMcpServer(coord: ChapDispatcher, 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;
+interface ChapMcpHttpOptions extends ChapMcpOptions {
+    /**
+     * The largest request body read, when the caller has not read it. Default
+     * 1,114,112 bytes: the coordinator's default envelope limit of 1 MiB, and
+     * 64 KiB for the MCP request around it.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Names the server also answers to, each as a Host header carries it:
+     * `mcp.internal:8792`, or a bare name behind a proxy on the default port.
+     * Its loopback names on the port it was reached on, 127.0.0.1, localhost
+     * and [::1], are always allowed. A request under any other name is refused
+     * with 421, so a page that rebinds its own name to the server's address
+     * gets nothing.
+     */
+    allowedHosts?: string[];
+    /**
+     * Origins a browser page may call from, each as an Origin header carries
+     * it, such as `http://localhost:6274`. A page served under one of the
+     * server's own names is always allowed, and a client that is not a
+     * browser sends no Origin. A request from any other origin is refused with
+     * 403. The handler sends no CORS headers: a page on another origin needs
+     * them from the server the handler is mounted in, as Express's cors
+     * middleware sends them.
+     */
+    allowedOrigins?: string[];
+    /**
+     * How long a request waits for the server's answer, in milliseconds. One
+     * with no answer by then is answered with an internal error, -32603: with
+     * HTTP 500, or on the event stream where a handshake-era answer has begun.
+     * Default 45,000.
+     */
+    timeoutMs?: number;
+}
+/** Answers one HTTP request on the MCP endpoint. Pass `parsedBody` when the server has read and parsed the body already. */
+type ChapMcpHttpHandler = (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void>;
+/**
+ * Serve MCP over HTTP: a handler for a Node `http` request and response,
+ * for an endpoint such as `/mcp`, with the version handling of the stdio
+ * server. A request with no MCP-Protocol-Version header, or a handshake-era
+ * one, is answered by the SDK's Streamable HTTP transport, statelessly; a
+ * 2026-07-28 request is answered as that revision's single exchange, one
+ * JSON-RPC request and one JSON answer. `options` are those of
+ * makeChapMcpServer, so `participant` and `toolFilter` hold over HTTP as on
+ * stdio.
+ *
+ * It answers only under the server's own names, refuses a browser request
+ * from another origin, and takes POST only; `allowedHosts` and
+ * `allowedOrigins` add names and origins. A request with no answer within
+ * `timeoutMs` is answered with an internal error.
+ *
+ *   const mcp = chapMcpHttpHandler(coord, { participant: "agent:assistant", toolFilter: (n) => AGENT_MCP_TOOLS.has(n) });
+ *   createServer((req, res) => (req.url === "/mcp" ? mcp(req, res) : notFound(res)));
+ */
+declare function chapMcpHttpHandler(coord: ChapDispatcher, options?: ChapMcpHttpOptions): ChapMcpHttpHandler;
 
-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 };
+export { type ChapDispatcher, type ChapMcpHttpHandler, type ChapMcpHttpOptions, 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, chapMcpHttpHandler, classifyEnvelope, dispatchToolCall, makeChapMcpServer };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
-import { Coordinator, Envelope } from '@brightbeamai/chap-coordinator';
+import { Envelope, Coordinator } from '@brightbeamai/chap-coordinator';
 export { JsonSchema, SCHEMAS, TOOL_NAMES, coerceToolArgs, methodForTool, schemaFor } from './schemas.js';
-export { TOOL_ANNOTATIONS, TOOL_DESCRIPTIONS, ToolAnnotations } from './tools.js';
+export { AGENT_MCP_TOOLS, TOOL_ANNOTATIONS, TOOL_DESCRIPTIONS, ToolAnnotations } from './tools.js';
 
 /**
  * Per-request protocol envelope (MCP 2026-07-28).
@@ -101,10 +102,12 @@ declare function classifyEnvelope(params: unknown): ProtocolEra;
  *   import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
  *
  *   const coord = new Coordinator({ ... });
- *   const server = makeChapMcpServer(coord, { name: "chap", version: "0.3.4" });
+ *   const server = makeChapMcpServer(coord, { name: "chap", version: "0.3.5" });
  *   await server.connect(new StdioServerTransport());
  *
- * Usage (Streamable HTTP): see reference/mcp-server-ts/server.ts.
+ * Usage (HTTP): chapMcpHttpHandler(coord, options) answers a Node `http`
+ * request on an MCP endpoint, in both protocol eras, and refuses a request
+ * under a foreign Host or from a foreign Origin.
  *
  * Architecture notes:
  *
@@ -117,6 +120,11 @@ declare function classifyEnvelope(params: unknown): ProtocolEra;
  * - Tool naming follows "chap.<method>" so the prefix avoids
  *   collisions with other MCP servers a client might load.
  *
+ * - A server that is one participant's connection, such as an
+ *   agent's, takes `participant`: every call is made as that member,
+ *   and a call naming another `from` is refused. AGENT_MCP_TOOLS is
+ *   the tool set such a connection offers an agent.
+ *
  * - 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
@@ -144,21 +152,32 @@ declare const ServerDiscoverRequestSchema: z.ZodObject<{
         _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$loose>>;
 }, z.core.$strip>;
+/**
+ * What the server dispatches each call through: a Coordinator, or anything
+ * with the same `dispatch`, such as a client that forwards the envelope to a
+ * running server. The answer may be returned or promised.
+ */
+interface ChapDispatcher {
+    dispatch(envelope: Envelope): Envelope | Promise<Envelope>;
+}
 interface ChapMcpOptions {
     /** Server name advertised to MCP clients. Default: "chap". */
     name?: string;
-    /** Server version. Default: "0.3.4". */
+    /** Server version. Default: "0.3.5". */
     version?: string;
     /**
-     * Restrict the CHAP methods this server offers. Default: all 39. A tool the
-     * filter excludes is left out of the list and refused when called.
+     * Restrict the CHAP methods this server offers. Default: all of them. A
+     * tool the filter excludes is left out of the list and refused when called.
      */
     toolFilter?: (toolName: string) => boolean;
     /**
      * Make every call as this participant. `from` is filled in on each call,
      * and a call that names another `from` is refused. Use it where the server
      * is one participant's connection, such as an agent's, so the connection
-     * cannot act in anyone else's name. Default: each call names its own `from`.
+     * cannot act in anyone else's name. The tools then list `from` as optional,
+     * with this URI in its description. A `human:` URI is refused: a person
+     * decides in a desk, never through a connection made for an agent.
+     * Default: each call names its own `from`.
      */
     participant?: string;
     /** Optional id generator for the envelopes emitted by tool calls. */
@@ -170,12 +189,67 @@ interface ChapMcpOptions {
  * CHAP method; pass it to a transport (stdio, Streamable HTTP) to
  * start serving.
  */
-declare function makeChapMcpServer(coord: Coordinator, options?: ChapMcpOptions): Server;
+declare function makeChapMcpServer(coord: ChapDispatcher, 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;
+interface ChapMcpHttpOptions extends ChapMcpOptions {
+    /**
+     * The largest request body read, when the caller has not read it. Default
+     * 1,114,112 bytes: the coordinator's default envelope limit of 1 MiB, and
+     * 64 KiB for the MCP request around it.
+     */
+    maxBodyBytes?: number;
+    /**
+     * Names the server also answers to, each as a Host header carries it:
+     * `mcp.internal:8792`, or a bare name behind a proxy on the default port.
+     * Its loopback names on the port it was reached on, 127.0.0.1, localhost
+     * and [::1], are always allowed. A request under any other name is refused
+     * with 421, so a page that rebinds its own name to the server's address
+     * gets nothing.
+     */
+    allowedHosts?: string[];
+    /**
+     * Origins a browser page may call from, each as an Origin header carries
+     * it, such as `http://localhost:6274`. A page served under one of the
+     * server's own names is always allowed, and a client that is not a
+     * browser sends no Origin. A request from any other origin is refused with
+     * 403. The handler sends no CORS headers: a page on another origin needs
+     * them from the server the handler is mounted in, as Express's cors
+     * middleware sends them.
+     */
+    allowedOrigins?: string[];
+    /**
+     * How long a request waits for the server's answer, in milliseconds. One
+     * with no answer by then is answered with an internal error, -32603: with
+     * HTTP 500, or on the event stream where a handshake-era answer has begun.
+     * Default 45,000.
+     */
+    timeoutMs?: number;
+}
+/** Answers one HTTP request on the MCP endpoint. Pass `parsedBody` when the server has read and parsed the body already. */
+type ChapMcpHttpHandler = (req: IncomingMessage, res: ServerResponse, parsedBody?: unknown) => Promise<void>;
+/**
+ * Serve MCP over HTTP: a handler for a Node `http` request and response,
+ * for an endpoint such as `/mcp`, with the version handling of the stdio
+ * server. A request with no MCP-Protocol-Version header, or a handshake-era
+ * one, is answered by the SDK's Streamable HTTP transport, statelessly; a
+ * 2026-07-28 request is answered as that revision's single exchange, one
+ * JSON-RPC request and one JSON answer. `options` are those of
+ * makeChapMcpServer, so `participant` and `toolFilter` hold over HTTP as on
+ * stdio.
+ *
+ * It answers only under the server's own names, refuses a browser request
+ * from another origin, and takes POST only; `allowedHosts` and
+ * `allowedOrigins` add names and origins. A request with no answer within
+ * `timeoutMs` is answered with an internal error.
+ *
+ *   const mcp = chapMcpHttpHandler(coord, { participant: "agent:assistant", toolFilter: (n) => AGENT_MCP_TOOLS.has(n) });
+ *   createServer((req, res) => (req.url === "/mcp" ? mcp(req, res) : notFound(res)));
+ */
+declare function chapMcpHttpHandler(coord: ChapDispatcher, options?: ChapMcpHttpOptions): ChapMcpHttpHandler;
 
-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 };
+export { type ChapDispatcher, type ChapMcpHttpHandler, type ChapMcpHttpOptions, 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, chapMcpHttpHandler, classifyEnvelope, dispatchToolCall, makeChapMcpServer };