@jaypie/mcp 0.8.151 → 0.8.153

package/README.md

@@ -4,6 +4,40 @@ Model Context Protocol server for Jaypie.
 
 See [jaypie.net](https://jaypie.net) for documentation.
 
+## Usage
+
+### CLI (stdio)
+
+```bash
+npx jaypie-mcp
+```
+
+### Streamable HTTP on Lambda (no MCP SDK)
+
+```typescript
+import express from "express";
+import { createLambdaStreamHandler } from "@jaypie/express";
+import { mcpHttpHandler } from "@jaypie/mcp/http";
+
+const app = express();
+app.use(express.json());
+app.all("/mcp", mcpHttpHandler({ services: ["skill", "version"] }));
+
+export const handler = createLambdaStreamHandler(app);
+```
+
+`mcpHttpHandler` answers JSON or server-sent events by `Accept` header, 202 for notifications, and 405 for GET and DELETE. Pass `suite` to serve any fabric `ServiceSuite`. Lifecycle options (`secrets`, `setup`, `validate`, ...) pass through to `expressHandler`. Requires `@jaypie/express` and `@jaypie/logger` (optional peers, included in `jaypie`).
+
+### Filtering Tools
+
+`createMcpServer`, `mcpExpressHandler`, and `mcpHttpHandler` accept `services`, an allowlist of tool names:
+
+```typescript
+import { createMcpServer } from "@jaypie/mcp";
+
+const server = createMcpServer({ services: ["skill", "version"] });
+```
+
 ## 📜 License
 
 [MIT License](./LICENSE.txt). Published by Finlayson Studio.

package/dist/createMcpServer.d.ts

@@ -1,5 +1,10 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export interface CreateMcpServerOptions {
+    /**
+     * Allowlist of tool names (service aliases) to expose. Omit to expose every
+     * tool; an empty array exposes none.
+     */
+    services?: string[];
     version?: string;
     verbose?: boolean;
 }

package/dist/createMcpServer.js

@@ -15,16 +15,17 @@ import { suite } from './suite.js';
 function createMcpServer(options = {}) {
     // Support legacy signature: createMcpServer(version: string)
     const config = typeof options === "string" ? { version: options } : options;
-    const { version = "0.0.0", verbose = false } = config;
+    const { services, version = "0.0.0", verbose = false } = config;
     if (verbose) {
         console.error("[jaypie-mcp] Creating MCP server instance from suite");
     }
     const server = createMcpServerFromSuite(suite, {
         name: suite.name,
+        services,
         version,
     });
     if (verbose) {
-        console.error(`[jaypie-mcp] Registered ${suite.services.length} tools from suite`);
+        console.error(`[jaypie-mcp] Registered ${server.tools.length} tools from suite`);
         console.error(`[jaypie-mcp] Categories: ${suite.categories.join(", ")}`);
     }
     return server;

package/dist/createMcpServer.js.map

@@ -1 +1 @@
-{"version":3,"file":"createMcpServer.js","sources":["../src/createMcpServer.ts"],"sourcesContent":["/* eslint-disable no-console -- MCP stdio: stderr is the only valid log channel; stdout is reserved for JSON-RPC */\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\n\nimport { createMcpServerFromSuite } from \"@jaypie/fabric/mcp\";\n\nimport { suite } from \"./suite.js\";\n\nexport interface CreateMcpServerOptions {\n  version?: string;\n  verbose?: boolean;\n}\n\n/**\n * Creates and configures an MCP server instance with Jaypie tools\n *\n * Uses ServiceSuite to register all services as MCP tools automatically.\n * Services are defined in suite.ts using fabricService and registered\n * by category. The createMcpServerFromSuite bridge converts them to\n * MCP tools with proper Zod schema validation.\n *\n * @param options - Configuration options (or legacy version string)\n * @returns Configured MCP server instance\n */\nexport function createMcpServer(\n  options: CreateMcpServerOptions | string = {},\n): McpServer {\n  // Support legacy signature: createMcpServer(version: string)\n  const config: CreateMcpServerOptions =\n    typeof options === \"string\" ? { version: options } : options;\n\n  const { version = \"0.0.0\", verbose = false } = config;\n\n  if (verbose) {\n    console.error(\"[jaypie-mcp] Creating MCP server instance from suite\");\n  }\n\n  const server = createMcpServerFromSuite(suite, {\n    name: suite.name,\n    version,\n  });\n\n  if (verbose) {\n    console.error(\n      `[jaypie-mcp] Registered ${suite.services.length} tools from suite`,\n    );\n    console.error(`[jaypie-mcp] Categories: ${suite.categories.join(\", \")}`);\n  }\n\n  return server;\n}\n"],"names":[],"mappings":";;;AAYA;;;;;;;;;;AAUG;AACG,SAAU,eAAe,CAC7B,OAAA,GAA2C,EAAE,EAAA;;AAG7C,IAAA,MAAM,MAAM,GACV,OAAO,OAAO,KAAK,QAAQ,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO;IAE9D,MAAM,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,MAAM;IAErD,IAAI,OAAO,EAAE;AACX,QAAA,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC;IACvE;AAEA,IAAA,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,EAAE;QAC7C,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,OAAO;AACR,KAAA,CAAC;IAEF,IAAI,OAAO,EAAE;QACX,OAAO,CAAC,KAAK,CACX,CAAA,wBAAA,EAA2B,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAA,iBAAA,CAAmB,CACpE;AACD,QAAA,OAAO,CAAC,KAAK,CAAC,CAAA,yBAAA,EAA4B,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAE,CAAC;IAC1E;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}
+{"version":3,"file":"createMcpServer.js","sources":["../src/createMcpServer.ts"],"sourcesContent":["/* eslint-disable no-console -- MCP stdio: stderr is the only valid log channel; stdout is reserved for JSON-RPC */\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\n\nimport { createMcpServerFromSuite } from \"@jaypie/fabric/mcp\";\n\nimport { suite } from \"./suite.js\";\n\nexport interface CreateMcpServerOptions {\n  /**\n   * Allowlist of tool names (service aliases) to expose. Omit to expose every\n   * tool; an empty array exposes none.\n   */\n  services?: string[];\n  version?: string;\n  verbose?: boolean;\n}\n\n/**\n * Creates and configures an MCP server instance with Jaypie tools\n *\n * Uses ServiceSuite to register all services as MCP tools automatically.\n * Services are defined in suite.ts using fabricService and registered\n * by category. The createMcpServerFromSuite bridge converts them to\n * MCP tools with proper Zod schema validation.\n *\n * @param options - Configuration options (or legacy version string)\n * @returns Configured MCP server instance\n */\nexport function createMcpServer(\n  options: CreateMcpServerOptions | string = {},\n): McpServer {\n  // Support legacy signature: createMcpServer(version: string)\n  const config: CreateMcpServerOptions =\n    typeof options === \"string\" ? { version: options } : options;\n\n  const { services, version = \"0.0.0\", verbose = false } = config;\n\n  if (verbose) {\n    console.error(\"[jaypie-mcp] Creating MCP server instance from suite\");\n  }\n\n  const server = createMcpServerFromSuite(suite, {\n    name: suite.name,\n    services,\n    version,\n  });\n\n  if (verbose) {\n    console.error(\n      `[jaypie-mcp] Registered ${server.tools.length} tools from suite`,\n    );\n    console.error(`[jaypie-mcp] Categories: ${suite.categories.join(\", \")}`);\n  }\n\n  return server;\n}\n"],"names":[],"mappings":";;;AAiBA;;;;;;;;;;AAUG;AACG,SAAU,eAAe,CAC7B,OAAA,GAA2C,EAAE,EAAA;;AAG7C,IAAA,MAAM,MAAM,GACV,OAAO,OAAO,KAAK,QAAQ,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO;AAE9D,IAAA,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,GAAG,KAAK,EAAE,GAAG,MAAM;IAE/D,IAAI,OAAO,EAAE;AACX,QAAA,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC;IACvE;AAEA,IAAA,MAAM,MAAM,GAAG,wBAAwB,CAAC,KAAK,EAAE;QAC7C,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,QAAQ;QACR,OAAO;AACR,KAAA,CAAC;IAEF,IAAI,OAAO,EAAE;QACX,OAAO,CAAC,KAAK,CACX,CAAA,wBAAA,EAA2B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAA,iBAAA,CAAmB,CAClE;AACD,QAAA,OAAO,CAAC,KAAK,CAAC,CAAA,yBAAA,EAA4B,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA,CAAE,CAAC;IAC1E;AAEA,IAAA,OAAO,MAAM;AACf;;;;"}

package/dist/http/index.d.ts

@@ -0,0 +1,92 @@
+import { ExpressHandlerOptions } from '@jaypie/express';
+import { Request, Response } from 'express';
+import { ServiceSuite } from '@jaypie/fabric';
+
+declare const JSON_RPC_ERROR: {
+    readonly INTERNAL: -32603;
+    readonly INVALID_PARAMS: -32602;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly PARSE: -32700;
+};
+declare const JSON_RPC_VERSION = "2.0";
+/** Latest protocol version; answered when a client requests an unknown one */
+declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+declare const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+type JsonRpcId = number | string | null;
+interface JsonRpcRequest {
+    id?: JsonRpcId;
+    jsonrpc?: string;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+interface JsonRpcResponse {
+    error?: {
+        code: number;
+        data?: unknown;
+        message: string;
+    };
+    id: JsonRpcId;
+    jsonrpc: typeof JSON_RPC_VERSION;
+    result?: unknown;
+}
+interface McpRpcOptions {
+    /** Server name reported by `initialize`. Defaults to the suite name */
+    name?: string;
+    /** Allowlist of service aliases exposed as tools. Omit to expose all */
+    services?: string[];
+    /** Suite served as tools. Defaults to the Jaypie MCP suite */
+    suite?: ServiceSuite;
+    /** Server version reported by `initialize`. Defaults to the suite version */
+    version?: string;
+}
+/**
+ * Answer one JSON-RPC request against a suite
+ *
+ * Returns `null` for a notification, which the transport answers with 202 and
+ * no body.
+ */
+declare function handleMcpRpc(request: JsonRpcRequest, options?: McpRpcOptions): Promise<JsonRpcResponse | null>;
+/**
+ * Answer a body that may be one request or a batch
+ *
+ * Accepts a parsed body, a JSON string, or a Buffer. Returns `null` when
+ * nothing needs an answer.
+ */
+declare function handleMcpRpcBody(body: unknown, options?: McpRpcOptions): Promise<JsonRpcResponse | JsonRpcResponse[] | null>;
+
+/**
+ * Options for `mcpHttpHandler`
+ *
+ * Lifecycle options (`secrets`, `setup`, `validate`, ...) pass through to
+ * `expressHandler` and `expressStreamHandler`. `name` and `version` describe
+ * the MCP server reported by `initialize`.
+ */
+interface McpHttpHandlerOptions extends Omit<ExpressHandlerOptions, "fabric" | "name">, McpRpcOptions {
+}
+type McpHttpHandler = (req: Request, res: Response, ...params: unknown[]) => Promise<unknown>;
+/**
+ * Serve a fabric `ServiceSuite` as MCP streamable HTTP without the MCP SDK
+ *
+ * Stateless JSON-RPC 2.0 on a single endpoint. A POST answers with one JSON
+ * body, or with server-sent events when the client's `Accept` header prefers
+ * `text/event-stream`. Notifications answer 202 with no body. GET, DELETE, and
+ * other methods answer 405.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { createLambdaStreamHandler } from "@jaypie/express";
+ * import { mcpHttpHandler } from "@jaypie/mcp/http";
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.all("/mcp", mcpHttpHandler({ services: ["skill", "version"] }));
+ *
+ * export const handler = createLambdaStreamHandler(app);
+ * ```
+ */
+declare function mcpHttpHandler(options?: McpHttpHandlerOptions): McpHttpHandler;
+
+export { JSON_RPC_ERROR, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, handleMcpRpc, handleMcpRpcBody, mcpHttpHandler };
+export type { JsonRpcId, JsonRpcRequest, JsonRpcResponse, McpHttpHandler, McpHttpHandlerOptions, McpRpcOptions };

package/dist/http/index.js

@@ -0,0 +1,3 @@
+export { mcpHttpHandler } from './mcpHttpHandler.js';
+export { JSON_RPC_ERROR, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, handleMcpRpc, handleMcpRpcBody } from './rpc.js';
+//# sourceMappingURL=index.js.map

package/dist/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/http/mcpHttpHandler.d.ts

@@ -0,0 +1,35 @@
+import type { ExpressHandlerOptions } from "@jaypie/express";
+import type { Request, Response } from "express";
+import type { McpRpcOptions } from "./rpc.js";
+/**
+ * Options for `mcpHttpHandler`
+ *
+ * Lifecycle options (`secrets`, `setup`, `validate`, ...) pass through to
+ * `expressHandler` and `expressStreamHandler`. `name` and `version` describe
+ * the MCP server reported by `initialize`.
+ */
+export interface McpHttpHandlerOptions extends Omit<ExpressHandlerOptions, "fabric" | "name">, McpRpcOptions {
+}
+export type McpHttpHandler = (req: Request, res: Response, ...params: unknown[]) => Promise<unknown>;
+/**
+ * Serve a fabric `ServiceSuite` as MCP streamable HTTP without the MCP SDK
+ *
+ * Stateless JSON-RPC 2.0 on a single endpoint. A POST answers with one JSON
+ * body, or with server-sent events when the client's `Accept` header prefers
+ * `text/event-stream`. Notifications answer 202 with no body. GET, DELETE, and
+ * other methods answer 405.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { createLambdaStreamHandler } from "@jaypie/express";
+ * import { mcpHttpHandler } from "@jaypie/mcp/http";
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.all("/mcp", mcpHttpHandler({ services: ["skill", "version"] }));
+ *
+ * export const handler = createLambdaStreamHandler(app);
+ * ```
+ */
+export declare function mcpHttpHandler(options?: McpHttpHandlerOptions): McpHttpHandler;

package/dist/http/mcpHttpHandler.js

@@ -0,0 +1,99 @@
+import { MethodNotAllowedError } from '@jaypie/errors';
+import { expressHandler, expressStreamHandler } from '@jaypie/express';
+import { handleMcpRpcBody, expectsResponse } from './rpc.js';
+
+//
+//
+// Constants
+//
+const HANDLER_NAME = {
+    JSON: "mcpHttpHandler",
+    STREAM: "mcpHttpStreamHandler",
+};
+const HEADER_ALLOW = "Allow";
+const HTTP_ACCEPTED = 202;
+const HTTP_METHOD_POST = "POST";
+const MEDIA_TYPE = {
+    EVENT_STREAM: "text/event-stream",
+    JSON: "application/json",
+};
+const MESSAGE_METHOD_NOT_ALLOWED = "This MCP endpoint is stateless and accepts POST only";
+const SSE_EVENT = "message";
+//
+//
+// Helpers
+//
+/** Does the client prefer an event stream over one JSON body? */
+function wantsEventStream(req) {
+    const accept = String(req.headers.accept ?? "");
+    const streamIndex = accept.indexOf(MEDIA_TYPE.EVENT_STREAM);
+    if (streamIndex === -1) {
+        return false;
+    }
+    const jsonIndex = accept.indexOf(MEDIA_TYPE.JSON);
+    return jsonIndex === -1 || streamIndex < jsonIndex;
+}
+function formatSseMessage(response) {
+    return `event: ${SSE_EVENT}\ndata: ${JSON.stringify(response)}\n\n`;
+}
+//
+//
+// Main
+//
+/**
+ * Serve a fabric `ServiceSuite` as MCP streamable HTTP without the MCP SDK
+ *
+ * Stateless JSON-RPC 2.0 on a single endpoint. A POST answers with one JSON
+ * body, or with server-sent events when the client's `Accept` header prefers
+ * `text/event-stream`. Notifications answer 202 with no body. GET, DELETE, and
+ * other methods answer 405.
+ *
+ * @example
+ * ```typescript
+ * import express from "express";
+ * import { createLambdaStreamHandler } from "@jaypie/express";
+ * import { mcpHttpHandler } from "@jaypie/mcp/http";
+ *
+ * const app = express();
+ * app.use(express.json());
+ * app.all("/mcp", mcpHttpHandler({ services: ["skill", "version"] }));
+ *
+ * export const handler = createLambdaStreamHandler(app);
+ * ```
+ */
+function mcpHttpHandler(options = {}) {
+    const { name, services, suite, version, ...lifecycle } = options;
+    const rpcOptions = { name, services, suite, version };
+    const jsonHandler = expressHandler(async (req, res) => {
+        if (req.method !== HTTP_METHOD_POST) {
+            res.setHeader(HEADER_ALLOW, HTTP_METHOD_POST);
+            throw new MethodNotAllowedError(MESSAGE_METHOD_NOT_ALLOWED);
+        }
+        const answer = await handleMcpRpcBody(req.body, rpcOptions);
+        if (answer === null) {
+            // Streamable HTTP requires 202 with no body for notifications;
+            // expressHandler sends an explicit status with no body on empty return
+            res.status(HTTP_ACCEPTED);
+            return undefined;
+        }
+        return answer;
+    }, { ...lifecycle, name: HANDLER_NAME.JSON });
+    const streamHandler = expressStreamHandler(async (req, res) => {
+        const answer = await handleMcpRpcBody(req.body, rpcOptions);
+        const responses = answer === null ? [] : [answer].flat();
+        for (const response of responses) {
+            res.write(formatSseMessage(response));
+        }
+    }, { ...lifecycle, format: "sse", name: HANDLER_NAME.STREAM });
+    return async (req, res, ...params) => {
+        if (req.method === HTTP_METHOD_POST &&
+            wantsEventStream(req) &&
+            expectsResponse(req.body)) {
+            return streamHandler(req, res, ...params);
+        }
+        return jsonHandler(req, res, ...params);
+    };
+}
+
+export { mcpHttpHandler };
+//# sourceMappingURL=mcpHttpHandler.js.map

package/dist/http/mcpHttpHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpHttpHandler.js","sources":["../../src/http/mcpHttpHandler.ts"],"sourcesContent":["import { MethodNotAllowedError } from \"@jaypie/errors\";\nimport { expressHandler, expressStreamHandler } from \"@jaypie/express\";\nimport type { ExpressHandlerOptions } from \"@jaypie/express\";\nimport type { Request, Response } from \"express\";\n\nimport { expectsResponse, handleMcpRpcBody } from \"./rpc.js\";\nimport type { JsonRpcResponse, McpRpcOptions } from \"./rpc.js\";\n\n//\n//\n// Constants\n//\n\nconst HANDLER_NAME = {\n  JSON: \"mcpHttpHandler\",\n  STREAM: \"mcpHttpStreamHandler\",\n} as const;\n\nconst HEADER_ALLOW = \"Allow\";\nconst HTTP_ACCEPTED = 202;\nconst HTTP_METHOD_POST = \"POST\";\n\nconst MEDIA_TYPE = {\n  EVENT_STREAM: \"text/event-stream\",\n  JSON: \"application/json\",\n} as const;\n\nconst MESSAGE_METHOD_NOT_ALLOWED =\n  \"This MCP endpoint is stateless and accepts POST only\";\n\nconst SSE_EVENT = \"message\";\n\n//\n//\n// Types\n//\n\n/**\n * Options for `mcpHttpHandler`\n *\n * Lifecycle options (`secrets`, `setup`, `validate`, ...) pass through to\n * `expressHandler` and `expressStreamHandler`. `name` and `version` describe\n * the MCP server reported by `initialize`.\n */\nexport interface McpHttpHandlerOptions\n  extends Omit<ExpressHandlerOptions, \"fabric\" | \"name\">, McpRpcOptions {}\n\nexport type McpHttpHandler = (\n  req: Request,\n  res: Response,\n  ...params: unknown[]\n) => Promise<unknown>;\n\n//\n//\n// Helpers\n//\n\n/** Does the client prefer an event stream over one JSON body? */\nfunction wantsEventStream(req: Request): boolean {\n  const accept = String(req.headers.accept ?? \"\");\n  const streamIndex = accept.indexOf(MEDIA_TYPE.EVENT_STREAM);\n  if (streamIndex === -1) {\n    return false;\n  }\n  const jsonIndex = accept.indexOf(MEDIA_TYPE.JSON);\n  return jsonIndex === -1 || streamIndex < jsonIndex;\n}\n\nfunction formatSseMessage(response: JsonRpcResponse): string {\n  return `event: ${SSE_EVENT}\\ndata: ${JSON.stringify(response)}\\n\\n`;\n}\n\n//\n//\n// Main\n//\n\n/**\n * Serve a fabric `ServiceSuite` as MCP streamable HTTP without the MCP SDK\n *\n * Stateless JSON-RPC 2.0 on a single endpoint. A POST answers with one JSON\n * body, or with server-sent events when the client's `Accept` header prefers\n * `text/event-stream`. Notifications answer 202 with no body. GET, DELETE, and\n * other methods answer 405.\n *\n * @example\n * ```typescript\n * import express from \"express\";\n * import { createLambdaStreamHandler } from \"@jaypie/express\";\n * import { mcpHttpHandler } from \"@jaypie/mcp/http\";\n *\n * const app = express();\n * app.use(express.json());\n * app.all(\"/mcp\", mcpHttpHandler({ services: [\"skill\", \"version\"] }));\n *\n * export const handler = createLambdaStreamHandler(app);\n * ```\n */\nexport function mcpHttpHandler(\n  options: McpHttpHandlerOptions = {},\n): McpHttpHandler {\n  const { name, services, suite, version, ...lifecycle } = options;\n  const rpcOptions: McpRpcOptions = { name, services, suite, version };\n\n  const jsonHandler = expressHandler(\n    async (req: Request, res: Response) => {\n      if (req.method !== HTTP_METHOD_POST) {\n        res.setHeader(HEADER_ALLOW, HTTP_METHOD_POST);\n        throw new MethodNotAllowedError(MESSAGE_METHOD_NOT_ALLOWED);\n      }\n      const answer = await handleMcpRpcBody(req.body, rpcOptions);\n      if (answer === null) {\n        // Streamable HTTP requires 202 with no body for notifications;\n        // expressHandler sends an explicit status with no body on empty return\n        res.status(HTTP_ACCEPTED);\n        return undefined;\n      }\n      return answer;\n    },\n    { ...lifecycle, name: HANDLER_NAME.JSON },\n  );\n\n  const streamHandler = expressStreamHandler(\n    async (req: Request, res: Response) => {\n      const answer = await handleMcpRpcBody(req.body, rpcOptions);\n      const responses = answer === null ? [] : [answer].flat();\n      for (const response of responses) {\n        res.write(formatSseMessage(response));\n      }\n    },\n    { ...lifecycle, format: \"sse\", name: HANDLER_NAME.STREAM },\n  );\n\n  return async (req: Request, res: Response, ...params: unknown[]) => {\n    if (\n      req.method === HTTP_METHOD_POST &&\n      wantsEventStream(req) &&\n      expectsResponse(req.body)\n    ) {\n      return streamHandler(req, res, ...params);\n    }\n    return jsonHandler(req, res, ...params);\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/http/rpc.d.ts

@@ -0,0 +1,70 @@
+import type { ServiceSuite } from "@jaypie/fabric";
+export declare const JSON_RPC_ERROR: {
+    readonly INTERNAL: -32603;
+    readonly INVALID_PARAMS: -32602;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly PARSE: -32700;
+};
+export declare const JSON_RPC_VERSION = "2.0";
+export declare const MCP_METHOD: {
+    readonly CALL_TOOL: "tools/call";
+    readonly CANCELLED: "notifications/cancelled";
+    readonly INITIALIZE: "initialize";
+    readonly INITIALIZED: "notifications/initialized";
+    readonly LIST_TOOLS: "tools/list";
+    readonly PING: "ping";
+};
+/** Latest protocol version; answered when a client requests an unknown one */
+export declare const MCP_PROTOCOL_VERSION = "2025-06-18";
+export declare const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[];
+export type JsonRpcId = number | string | null;
+export interface JsonRpcRequest {
+    id?: JsonRpcId;
+    jsonrpc?: string;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    error?: {
+        code: number;
+        data?: unknown;
+        message: string;
+    };
+    id: JsonRpcId;
+    jsonrpc: typeof JSON_RPC_VERSION;
+    result?: unknown;
+}
+export interface McpRpcOptions {
+    /** Server name reported by `initialize`. Defaults to the suite name */
+    name?: string;
+    /** Allowlist of service aliases exposed as tools. Omit to expose all */
+    services?: string[];
+    /** Suite served as tools. Defaults to the Jaypie MCP suite */
+    suite?: ServiceSuite;
+    /** Server version reported by `initialize`. Defaults to the suite version */
+    version?: string;
+}
+/** A notification carries no id and expects no response */
+export declare function isNotification(request: unknown): boolean;
+/**
+ * Normalize a raw body: a Buffer or string is parsed as JSON; anything else is
+ * taken as already parsed. Returns `undefined` when there is no parseable body.
+ */
+export declare function parseRpcBody(body: unknown): unknown;
+/** Does the body carry anything that must be answered? */
+export declare function expectsResponse(body: unknown): boolean;
+/**
+ * Answer one JSON-RPC request against a suite
+ *
+ * Returns `null` for a notification, which the transport answers with 202 and
+ * no body.
+ */
+export declare function handleMcpRpc(request: JsonRpcRequest, options?: McpRpcOptions): Promise<JsonRpcResponse | null>;
+/**
+ * Answer a body that may be one request or a batch
+ *
+ * Accepts a parsed body, a JSON string, or a Buffer. Returns `null` when
+ * nothing needs an answer.
+ */
+export declare function handleMcpRpcBody(body: unknown, options?: McpRpcOptions): Promise<JsonRpcResponse | JsonRpcResponse[] | null>;

package/dist/http/rpc.js

@@ -0,0 +1,262 @@
+import { isJaypieError } from '@jaypie/errors';
+import { inputToJsonSchema } from '@jaypie/fabric/llm';
+import { log } from '@jaypie/logger';
+import { selectTools, findTool } from './tools.js';
+
+//
+//
+// Constants
+//
+const JSON_RPC_ERROR = {
+    INTERNAL: -32603,
+    INVALID_PARAMS: -32602,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    PARSE: -32700,
+};
+const JSON_RPC_VERSION = "2.0";
+const MCP_METHOD = {
+    CALL_TOOL: "tools/call",
+    CANCELLED: "notifications/cancelled",
+    INITIALIZE: "initialize",
+    INITIALIZED: "notifications/initialized",
+    LIST_TOOLS: "tools/list",
+    PING: "ping",
+};
+/** Latest protocol version; answered when a client requests an unknown one */
+const MCP_PROTOCOL_VERSION = "2025-06-18";
+const MCP_SUPPORTED_PROTOCOL_VERSIONS = [
+    MCP_PROTOCOL_VERSION,
+    "2025-03-26",
+    "2024-11-05",
+];
+const MESSAGE = {
+    EMPTY_BATCH: "An empty batch is not a request",
+    INVALID_ARGUMENTS: "Tool arguments must be an object",
+    INVALID_REQUEST: "The request is not a JSON-RPC request",
+    PARSE: "The body is not JSON-RPC",
+    TOOL_FAILED: "The tool call failed",
+    UNKNOWN_METHOD: "Unknown method",
+    UNKNOWN_TOOL: "Unknown tool",
+};
+//
+//
+// Helpers
+//
+let defaultSuite;
+/** Load the Jaypie suite only when no suite is supplied */
+function loadDefaultSuite() {
+    if (!defaultSuite) {
+        defaultSuite = import('../suite.js')
+            .then((module) => module.suite)
+            .catch((error) => {
+            defaultSuite = undefined;
+            throw error;
+        });
+    }
+    return defaultSuite;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function jsonRpcError({ code, id = null, message, }) {
+    return { error: { code, message }, id, jsonrpc: JSON_RPC_VERSION };
+}
+function jsonRpcResult({ id, result, }) {
+    return { id, jsonrpc: JSON_RPC_VERSION, result };
+}
+function textContent(value) {
+    let text;
+    if (value === undefined || value === null) {
+        text = "";
+    }
+    else if (typeof value === "string") {
+        text = value;
+    }
+    else {
+        text = JSON.stringify(value, null, 2);
+    }
+    return [{ text, type: "text" }];
+}
+/** A notification carries no id and expects no response */
+function isNotification(request) {
+    return isRecord(request) && (request.id === undefined || request.id === null);
+}
+/**
+ * Normalize a raw body: a Buffer or string is parsed as JSON; anything else is
+ * taken as already parsed. Returns `undefined` when there is no parseable body.
+ */
+function parseRpcBody(body) {
+    const raw = Buffer.isBuffer(body) ? body.toString("utf8") : body;
+    if (typeof raw !== "string") {
+        return raw;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Does the body carry anything that must be answered? */
+function expectsResponse(body) {
+    const parsed = parseRpcBody(body);
+    if (Array.isArray(parsed)) {
+        return (parsed.length === 0 || parsed.some((entry) => !isNotification(entry)));
+    }
+    return !isNotification(parsed);
+}
+async function callTool({ id, params, services, suite, }) {
+    const name = typeof params.name === "string" ? params.name : "";
+    const tool = findTool(name, { services, suite });
+    if (!tool) {
+        return jsonRpcError({
+            code: JSON_RPC_ERROR.INVALID_PARAMS,
+            id,
+            message: `${MESSAGE.UNKNOWN_TOOL}: ${name}`,
+        });
+    }
+    const args = params.arguments ?? {};
+    if (!isRecord(args)) {
+        return jsonRpcError({
+            code: JSON_RPC_ERROR.INVALID_PARAMS,
+            id,
+            message: MESSAGE.INVALID_ARGUMENTS,
+        });
+    }
+    try {
+        const result = await tool(args);
+        log.trace(`[mcp] Tool call complete: ${name}`);
+        return jsonRpcResult({ id, result: { content: textContent(result) } });
+    }
+    catch (error) {
+        let message = MESSAGE.TOOL_FAILED;
+        if (isJaypieError(error) && error instanceof Error) {
+            message = error.message;
+            log.debug(`[mcp] Tool call rejected: ${name}`);
+        }
+        else {
+            log.warn(`[mcp] Tool call failed: ${name}`);
+        }
+        log.var({
+            mcpToolError: {
+                message: error instanceof Error ? error.message : String(error),
+                tool: name,
+            },
+        });
+        return jsonRpcResult({
+            id,
+            result: { content: textContent(message), isError: true },
+        });
+    }
+}
+//
+//
+// Main
+//
+/**
+ * Answer one JSON-RPC request against a suite
+ *
+ * Returns `null` for a notification, which the transport answers with 202 and
+ * no body.
+ */
+async function handleMcpRpc(request, options = {}) {
+    const id = request.id ?? null;
+    const notification = isNotification(request);
+    if (typeof request.method !== "string") {
+        if (notification) {
+            return null;
+        }
+        return jsonRpcError({
+            code: JSON_RPC_ERROR.INVALID_REQUEST,
+            id,
+            message: MESSAGE.INVALID_REQUEST,
+        });
+    }
+    const suite = options.suite ?? (await loadDefaultSuite());
+    const { name = suite.name, services, version = suite.version } = options;
+    const params = isRecord(request.params) ? request.params : {};
+    log.trace(`[mcp] ${request.method}`);
+    switch (request.method) {
+        case MCP_METHOD.INITIALIZE: {
+            const requested = params.protocolVersion;
+            const protocolVersion = typeof requested === "string" &&
+                MCP_SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+                ? requested
+                : MCP_PROTOCOL_VERSION;
+            return jsonRpcResult({
+                id,
+                result: {
+                    capabilities: { tools: {} },
+                    protocolVersion,
+                    serverInfo: { name, version },
+                },
+            });
+        }
+        case MCP_METHOD.CANCELLED:
+        case MCP_METHOD.INITIALIZED:
+            return null;
+        case MCP_METHOD.PING:
+            return jsonRpcResult({ id, result: {} });
+        case MCP_METHOD.LIST_TOOLS:
+            return jsonRpcResult({
+                id,
+                result: {
+                    tools: selectTools({ services, suite }).map((tool) => ({
+                        description: tool.description ?? "",
+                        inputSchema: inputToJsonSchema(tool.input),
+                        name: String(tool.alias),
+                    })),
+                },
+            });
+        case MCP_METHOD.CALL_TOOL:
+            return callTool({ id, params, services, suite });
+        default:
+            if (notification) {
+                return null;
+            }
+            return jsonRpcError({
+                code: JSON_RPC_ERROR.METHOD_NOT_FOUND,
+                id,
+                message: `${MESSAGE.UNKNOWN_METHOD}: ${request.method}`,
+            });
+    }
+}
+/**
+ * Answer a body that may be one request or a batch
+ *
+ * Accepts a parsed body, a JSON string, or a Buffer. Returns `null` when
+ * nothing needs an answer.
+ */
+async function handleMcpRpcBody(body, options = {}) {
+    const parsed = parseRpcBody(body);
+    if (parsed === undefined) {
+        return jsonRpcError({ code: JSON_RPC_ERROR.PARSE, message: MESSAGE.PARSE });
+    }
+    if (Array.isArray(parsed)) {
+        if (parsed.length === 0) {
+            return jsonRpcError({
+                code: JSON_RPC_ERROR.INVALID_REQUEST,
+                message: MESSAGE.EMPTY_BATCH,
+            });
+        }
+        const responses = await Promise.all(parsed.map((entry) => isRecord(entry)
+            ? handleMcpRpc(entry, options)
+            : jsonRpcError({
+                code: JSON_RPC_ERROR.INVALID_REQUEST,
+                message: MESSAGE.INVALID_REQUEST,
+            })));
+        const answered = responses.filter((response) => response !== null);
+        return answered.length > 0 ? answered : null;
+    }
+    if (!isRecord(parsed)) {
+        return jsonRpcError({
+            code: JSON_RPC_ERROR.INVALID_REQUEST,
+            message: MESSAGE.INVALID_REQUEST,
+        });
+    }
+    return handleMcpRpc(parsed, options);
+}
+
+export { JSON_RPC_ERROR, JSON_RPC_VERSION, MCP_METHOD, MCP_PROTOCOL_VERSION, MCP_SUPPORTED_PROTOCOL_VERSIONS, expectsResponse, handleMcpRpc, handleMcpRpcBody, isNotification, parseRpcBody };
+//# sourceMappingURL=rpc.js.map