@zmdb/mcp 1.0.0-beta.1

package/src/client.ts

@@ -0,0 +1,183 @@
+// Transport-neutral MCP client owned by @zmdb/mcp.
+import { MCP_PROTOCOL_VERSION } from './server.js';
+
+const PROTOCOL_VERSION_KEY = 'io.modelcontextprotocol/protocolVersion';
+const CLIENT_INFO_KEY = 'io.modelcontextprotocol/clientInfo';
+const CLIENT_CAPABILITIES_KEY = 'io.modelcontextprotocol/clientCapabilities';
+
+const DEFAULT_MAX_CALLS = 64;
+const DEFAULT_MAX_RESPONSE_BYTES = 1024 * 1024;
+
+type RequestId = string | number;
+
+export interface RemoteTool {
+  readonly name: string;
+  readonly description?: string;
+  readonly inputSchema: Readonly<Record<string, unknown>>;
+}
+
+export interface RemoteToolResult {
+  readonly content: readonly { readonly type: string; readonly text?: string }[];
+  readonly isError: boolean;
+}
+
+export interface McpClient {
+  listTools(): Promise<readonly RemoteTool[]>;
+  callTool(name: string, args: unknown): Promise<RemoteToolResult>;
+}
+
+export interface McpClientOptions {
+  readonly maxCalls?: number;
+  readonly maxResponseBytes?: number;
+  readonly clientInfo?: { readonly name: string; readonly version: string };
+  readonly clientCapabilities?: Readonly<Record<string, unknown>>;
+}
+
+export class McpProtocolError extends Error {
+  readonly code: number;
+  readonly data: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = 'McpProtocolError';
+    this.code = code;
+    this.data = data;
+  }
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const field = (value: Readonly<Record<string, unknown>>, key: string): unknown => Reflect.get(value, key);
+
+const positiveSafeInteger = (value: number, name: string): number => {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`${name} must be a positive safe integer`);
+  return value;
+};
+
+const boundedResponse = (value: unknown, maxResponseBytes: number): unknown => {
+  const serialised = typeof value === 'string' ? value : JSON.stringify(value);
+  if (serialised === undefined) throw new TypeError('MCP transport returned a non-JSON value');
+  if (new TextEncoder().encode(serialised).byteLength > maxResponseBytes) {
+    throw new RangeError(`MCP response exceeds maxResponseBytes (${String(maxResponseBytes)})`);
+  }
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new TypeError('MCP transport returned invalid JSON');
+  }
+};
+
+const responseResult = (
+  response: unknown,
+  id: RequestId,
+  maxResponseBytes: number,
+): Readonly<Record<string, unknown>> => {
+  const bounded = boundedResponse(response, maxResponseBytes);
+  if (!isRecord(bounded) || field(bounded, 'jsonrpc') !== '2.0' || field(bounded, 'id') !== id) {
+    throw new TypeError('invalid MCP response envelope');
+  }
+
+  const rawError = field(bounded, 'error');
+  if (rawError !== undefined) {
+    if (!isRecord(rawError)) throw new TypeError('invalid MCP error response');
+    const code = field(rawError, 'code');
+    const message = field(rawError, 'message');
+    if (typeof code !== 'number' || !Number.isInteger(code) || typeof message !== 'string') {
+      throw new TypeError('invalid MCP error response');
+    }
+    throw new McpProtocolError(code, message, field(rawError, 'data'));
+  }
+
+  const result = field(bounded, 'result');
+  if (!isRecord(result)) throw new TypeError('invalid MCP result response');
+  const resultType = field(result, 'resultType');
+  if (resultType !== undefined && resultType !== 'complete') {
+    throw new TypeError(`unsupported MCP resultType ${String(resultType)}`);
+  }
+  return result;
+};
+
+const remoteToolOf = (value: unknown): RemoteTool => {
+  if (!isRecord(value)) throw new TypeError('invalid remote MCP tool');
+  const name = field(value, 'name');
+  const description = field(value, 'description');
+  const inputSchema = field(value, 'inputSchema');
+  if (
+    typeof name !== 'string' ||
+    (description !== undefined && typeof description !== 'string') ||
+    !isRecord(inputSchema)
+  ) {
+    throw new TypeError('invalid remote MCP tool');
+  }
+  return description === undefined ? { name, inputSchema } : { name, description, inputSchema };
+};
+
+const contentBlockOf = (value: unknown): { readonly type: string; readonly text?: string } => {
+  if (!isRecord(value)) throw new TypeError('invalid remote MCP content block');
+  const type = field(value, 'type');
+  const text = field(value, 'text');
+  if (typeof type !== 'string' || (text !== undefined && typeof text !== 'string')) {
+    throw new TypeError('invalid remote MCP content block');
+  }
+  return text === undefined ? { ...value, type } : { ...value, type, text };
+};
+
+export function createMcpClient(send: (message: unknown) => Promise<unknown>, opts: McpClientOptions = {}): McpClient {
+  const maxCalls = positiveSafeInteger(opts.maxCalls ?? DEFAULT_MAX_CALLS, 'maxCalls');
+  const maxResponseBytes = positiveSafeInteger(opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES, 'maxResponseBytes');
+  const clientCapabilities = opts.clientCapabilities ?? {};
+  let nextId = 1;
+  let calls = 0;
+
+  const request = async (
+    method: string,
+    params: Readonly<Record<string, unknown>>,
+  ): Promise<Readonly<Record<string, unknown>>> => {
+    if (calls >= maxCalls) throw new RangeError(`MCP client call budget exhausted (${String(maxCalls)})`);
+    calls += 1;
+    const id = nextId;
+    nextId += 1;
+    const meta =
+      opts.clientInfo === undefined
+        ? {
+            [PROTOCOL_VERSION_KEY]: MCP_PROTOCOL_VERSION,
+            [CLIENT_CAPABILITIES_KEY]: clientCapabilities,
+          }
+        : {
+            [PROTOCOL_VERSION_KEY]: MCP_PROTOCOL_VERSION,
+            [CLIENT_INFO_KEY]: opts.clientInfo,
+            [CLIENT_CAPABILITIES_KEY]: clientCapabilities,
+          };
+    const response = await send({
+      jsonrpc: '2.0',
+      id,
+      method,
+      params: { ...params, _meta: meta },
+    });
+    return responseResult(response, id, maxResponseBytes);
+  };
+
+  return {
+    async listTools(): Promise<readonly RemoteTool[]> {
+      const result = await request('tools/list', {});
+      const tools = field(result, 'tools');
+      if (!Array.isArray(tools)) throw new TypeError('invalid MCP tools/list result');
+      return tools.map(remoteToolOf);
+    },
+
+    async callTool(name: string, args: unknown): Promise<RemoteToolResult> {
+      const result = await request('tools/call', { name, arguments: args });
+      const content = field(result, 'content');
+      const isError = field(result, 'isError');
+      if (!Array.isArray(content) || (isError !== undefined && typeof isError !== 'boolean')) {
+        throw new TypeError('invalid MCP tools/call result');
+      }
+      return {
+        content: content.map(contentBlockOf),
+        isError: isError ?? false,
+      };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// The complete public surface of @zmdb/mcp.
+export { MCP_PROTOCOL_VERSION, createMcpServer, type McpServer, type McpServerOptions } from './server.js';
+export {
+  McpProtocolError,
+  createMcpClient,
+  type McpClient,
+  type McpClientOptions,
+  type RemoteTool,
+  type RemoteToolResult,
+} from './client.js';

package/src/server.ts

@@ -0,0 +1,246 @@
+import type { ToolRegistry } from '@zmdb/ai/chat';
+import { invokeTool } from '@zmdb/ai/tool-runtime';
+
+export const MCP_PROTOCOL_VERSION = '2026-07-28';
+
+const PARSE_ERROR = -32_700;
+const INVALID_REQUEST = -32_600;
+const METHOD_NOT_FOUND = -32_601;
+const INVALID_PARAMS = -32_602;
+const UNSUPPORTED_PROTOCOL_VERSION = -32_022;
+
+const PROTOCOL_VERSION_KEY = 'io.modelcontextprotocol/protocolVersion';
+const CLIENT_CAPABILITIES_KEY = 'io.modelcontextprotocol/clientCapabilities';
+const SERVER_INFO_KEY = 'io.modelcontextprotocol/serverInfo';
+
+type RequestId = string | number;
+
+const toolErrorId = (): string =>
+  [...globalThis.crypto.getRandomValues(new Uint8Array(4))].map(byte => byte.toString(16).padStart(2, '0')).join('');
+
+interface ParsedRequest {
+  readonly kind: 'request';
+  readonly id: RequestId;
+  readonly method: string;
+  readonly params: Readonly<Record<string, unknown>>;
+}
+
+interface ParsedNotification {
+  readonly kind: 'notification';
+}
+
+interface InvalidMessage {
+  readonly kind: 'invalid';
+  readonly id: RequestId | null;
+  readonly code: number;
+  readonly message: string;
+}
+
+type ParsedMessage = ParsedRequest | ParsedNotification | InvalidMessage;
+
+export interface McpServer {
+  handle(message: unknown, transport: unknown): Promise<unknown | undefined>;
+}
+
+export interface McpServerOptions {
+  readonly serverInfo: { readonly name: string; readonly version: string };
+  readonly identify: (transport: unknown) => Promise<unknown>;
+}
+
+type McpToolHandler = {
+  bivarianceHack(input: unknown, identity?: unknown): unknown | PromiseLike<unknown>;
+}['bivarianceHack'];
+
+interface McpToolEntry {
+  readonly spec: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: unknown;
+  };
+  readonly validate: (args: unknown) => unknown;
+  readonly handler: McpToolHandler;
+  readonly effectful?: boolean;
+}
+
+type McpToolRegistry = Readonly<Record<string, McpToolEntry>>;
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const field = (value: Readonly<Record<string, unknown>>, key: string): unknown => Reflect.get(value, key);
+
+const requestIdOf = (value: unknown): RequestId | null => {
+  if (typeof value === 'string') return value;
+  return typeof value === 'number' && Number.isSafeInteger(value) ? value : null;
+};
+
+const parseMessage = (message: unknown): ParsedMessage => {
+  let value: unknown = message;
+  if (typeof message === 'string') {
+    try {
+      value = JSON.parse(message);
+    } catch {
+      return { kind: 'invalid', id: null, code: PARSE_ERROR, message: 'Parse error' };
+    }
+  }
+
+  if (!isRecord(value)) {
+    return { kind: 'invalid', id: null, code: INVALID_REQUEST, message: 'Invalid Request' };
+  }
+
+  const rawId = field(value, 'id');
+  const id = requestIdOf(rawId);
+  if (field(value, 'jsonrpc') !== '2.0' || typeof field(value, 'method') !== 'string') {
+    return { kind: 'invalid', id, code: INVALID_REQUEST, message: 'Invalid Request' };
+  }
+
+  if (!Object.hasOwn(value, 'id')) return { kind: 'notification' };
+  if (id === null) return { kind: 'invalid', id: null, code: INVALID_REQUEST, message: 'Invalid Request' };
+
+  const method = field(value, 'method');
+  const rawParams = field(value, 'params');
+  if (rawParams !== undefined && !isRecord(rawParams)) {
+    return { kind: 'invalid', id, code: INVALID_PARAMS, message: 'Invalid params' };
+  }
+
+  return {
+    kind: 'request',
+    id,
+    method: typeof method === 'string' ? method : '',
+    params: rawParams ?? {},
+  };
+};
+
+const errorResponse = (
+  id: RequestId | null,
+  code: number,
+  message: string,
+  data?: unknown,
+): Readonly<Record<string, unknown>> => ({
+  jsonrpc: '2.0',
+  id,
+  error: data === undefined ? { code, message } : { code, message, data },
+});
+
+const responseMeta = (
+  serverInfo: McpServerOptions['serverInfo'],
+): Readonly<Record<string, Readonly<Record<string, string>>>> => ({
+  [SERVER_INFO_KEY]: serverInfo,
+});
+
+const resultResponse = (
+  id: RequestId,
+  serverInfo: McpServerOptions['serverInfo'],
+  result: Readonly<Record<string, unknown>>,
+): Readonly<Record<string, unknown>> => ({
+  jsonrpc: '2.0',
+  id,
+  result: {
+    ...result,
+    resultType: 'complete',
+    _meta: responseMeta(serverInfo),
+  },
+});
+
+const protocolVersionOf = (params: Readonly<Record<string, unknown>>): string | undefined => {
+  const meta = field(params, '_meta');
+  if (!isRecord(meta)) return undefined;
+  const version = field(meta, PROTOCOL_VERSION_KEY);
+  const capabilities = field(meta, CLIENT_CAPABILITIES_KEY);
+  return typeof version === 'string' && isRecord(capabilities) ? version : undefined;
+};
+
+const toolCallOf = (
+  params: Readonly<Record<string, unknown>>,
+): { readonly name: string; readonly args: unknown } | undefined => {
+  const name = field(params, 'name');
+  if (typeof name !== 'string') return undefined;
+  return { name, args: field(params, 'arguments') ?? {} };
+};
+
+const contentResult = (
+  id: RequestId,
+  serverInfo: McpServerOptions['serverInfo'],
+  text: string,
+  isError: boolean,
+): Readonly<Record<string, unknown>> =>
+  resultResponse(id, serverInfo, {
+    content: [{ type: 'text', text }],
+    isError,
+  });
+
+// The public declaration uses the structural subset MCP consumes so the
+// provider-neutral @zmdb/ai/chat implementation cannot leak a provider SDK type.
+// The implementation signature still proves compatibility with AI's ToolRegistry.
+export function createMcpServer(tools: McpToolRegistry, opts: McpServerOptions): McpServer;
+export function createMcpServer(tools: McpToolRegistry | ToolRegistry, opts: McpServerOptions): McpServer {
+  const entries = Object.entries(tools);
+  for (const [key, entry] of entries) {
+    if (entry.spec.name !== key) {
+      throw new Error(`tool registry key ${key} does not match spec name ${entry.spec.name}`);
+    }
+  }
+  const entriesByName = new Map(entries);
+
+  return {
+    async handle(message: unknown, transport: unknown): Promise<unknown | undefined> {
+      const identity = await opts.identify(transport);
+      const parsed = parseMessage(message);
+      if (parsed.kind === 'notification') return undefined;
+      if (parsed.kind === 'invalid') {
+        return errorResponse(parsed.id, parsed.code, parsed.message);
+      }
+
+      const protocolVersion = protocolVersionOf(parsed.params);
+      if (protocolVersion === undefined) {
+        return errorResponse(parsed.id, INVALID_PARAMS, 'Missing required MCP request metadata');
+      }
+      if (protocolVersion !== MCP_PROTOCOL_VERSION) {
+        return errorResponse(parsed.id, UNSUPPORTED_PROTOCOL_VERSION, 'Unsupported protocol version', {
+          supported: [MCP_PROTOCOL_VERSION],
+          requested: protocolVersion,
+        });
+      }
+
+      if (parsed.method === 'server/discover') {
+        return resultResponse(parsed.id, opts.serverInfo, {
+          supportedVersions: [MCP_PROTOCOL_VERSION],
+          capabilities: { tools: {} },
+        });
+      }
+
+      if (parsed.method === 'tools/list') {
+        return resultResponse(parsed.id, opts.serverInfo, {
+          tools: entries.map(([, entry]) =>
+            entry.spec.description === undefined
+              ? { name: entry.spec.name, inputSchema: entry.spec.parameters }
+              : {
+                  name: entry.spec.name,
+                  description: entry.spec.description,
+                  inputSchema: entry.spec.parameters,
+                },
+          ),
+        });
+      }
+
+      if (parsed.method !== 'tools/call') {
+        return errorResponse(parsed.id, METHOD_NOT_FOUND, 'Method not found');
+      }
+
+      const call = toolCallOf(parsed.params);
+      if (call === undefined) return errorResponse(parsed.id, INVALID_PARAMS, 'Invalid tool call');
+      const entry = entriesByName.get(call.name);
+      if (entry === undefined) return errorResponse(parsed.id, INVALID_PARAMS, `unknown tool ${call.name}`);
+
+      const invocation = await invokeTool(entry, call.args, identity);
+      if (invocation.kind === 'success') {
+        return contentResult(parsed.id, opts.serverInfo, invocation.content, false);
+      }
+      if (invocation.kind === 'validation-error' && invocation.content !== undefined) {
+        return contentResult(parsed.id, opts.serverInfo, invocation.content, true);
+      }
+      const id = toolErrorId();
+      return contentResult(parsed.id, opts.serverInfo, `tool ${call.name} failed (${id})`, true);
+    },
+  };
+}