@procedures/mcp 0.0.0-stage → 0.1.0

package/dist/schema/zod-to-json-schema.js

@@ -0,0 +1,79 @@
+/**
+ * Zod to JSON Schema Converter
+ *
+ * Converts Zod schemas to JSON Schema format for MCP tool inputSchema.
+ * Uses zod-to-json-schema with caching for performance.
+ */
+import { zodToJsonSchema as zodConvert } from "zod-to-json-schema";
+/**
+ * Convert a schema to JSON Schema.
+ *
+ * Uses zod-to-json-schema library for actual Zod schemas,
+ * with safe fallbacks for non-Zod implementations.
+ *
+ * @param schema - Schema to convert (Zod or ZodLike)
+ * @param options - Conversion options
+ * @returns JSON Schema representation
+ */
+export function zodToJsonSchema(schema, options) {
+    // Check if it's actually a Zod schema (has _def property)
+    if (schema && typeof schema === "object" && "_def" in schema) {
+        try {
+            const result = zodConvert(schema, {
+                name: options?.name,
+                $refStrategy: "none", // Inline all refs for MCP compatibility
+                errorMessages: false,
+            });
+            // The library returns { $schema, ...rest } or just the schema
+            // We want to strip $schema for MCP
+            if (typeof result === "object" && result !== null) {
+                const { $schema: _, ...rest } = result;
+                return rest;
+            }
+            return result;
+        }
+        catch {
+            // Fallback to permissive schema on conversion error
+            return { type: "object", additionalProperties: true };
+        }
+    }
+    // For non-Zod schemas (our ZodLike interface), return permissive schema
+    return { type: "object", additionalProperties: true };
+}
+// Schema cache for performance, keyed by the schema object: a procedure that is registered
+// again with a different schema gets the new JSON Schema (BUGS-2026-07 L30: the cache was keyed
+// by the procedure path and returned the old schema)
+const schemaCache = new Map();
+/**
+ * Convert a schema to JSON Schema with caching.
+ *
+ * @param schema - Schema to convert (Zod or ZodLike)
+ * @param _cacheKey - Not used any more (kept for compatibility): the schema object is the key
+ * @returns Cached or freshly converted JSON Schema
+ */
+export function cachedZodToJsonSchema(schema, _cacheKey) {
+    if (!schema || typeof schema !== "object") {
+        return zodToJsonSchema(schema);
+    }
+    const cached = schemaCache.get(schema);
+    if (cached) {
+        return cached;
+    }
+    const jsonSchema = zodToJsonSchema(schema);
+    schemaCache.set(schema, jsonSchema);
+    return jsonSchema;
+}
+/**
+ * Clear the schema cache.
+ * Useful when procedures are re-registered with different schemas.
+ */
+export function clearSchemaCache() {
+    schemaCache.clear();
+}
+/**
+ * Get the current schema cache size.
+ */
+export function getSchemaCacheSize() {
+    return schemaCache.size;
+}
+//# sourceMappingURL=zod-to-json-schema.js.map

package/dist/schema/zod-to-json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zod-to-json-schema.js","sourceRoot":"","sources":["../../src/schema/zod-to-json-schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAuBnE;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,MAA4B,EAC5B,OAAgC;IAEhC,0DAA0D;IAC1D,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;QAC7D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,UAAU,CAAC,MAA0C,EAAE;gBACpE,IAAI,EAAE,OAAO,EAAE,IAAI;gBACnB,YAAY,EAAE,MAAM,EAAE,wCAAwC;gBAC9D,aAAa,EAAE,KAAK;aACrB,CAAC,CAAC;YAEH,8DAA8D;YAC9D,mCAAmC;YACnC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBAClD,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,MAAiC,CAAC;gBAClE,OAAO,IAAkB,CAAC;YAC5B,CAAC;YAED,OAAO,MAAoB,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,oDAAoD;YACpD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;QACxD,CAAC;IACH,CAAC;IAED,wEAAwE;IACxE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,oBAAoB,EAAE,IAAI,EAAE,CAAC;AACxD,CAAC;AAED,2FAA2F;AAC3F,gGAAgG;AAChG,qDAAqD;AACrD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAsB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA4B,EAC5B,SAAkB;IAElB,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,eAAe,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,UAAU,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC3C,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP Core Types
+ *
+ * Types for MCP (Model Context Protocol) integration with the procedure system.
+ * Extends MCP SDK types with procedure-specific metadata.
+ */
+import type { ProcedurePath } from "@procedures/client";
+/**
+ * JSON Schema type for MCP tool inputSchema.
+ * Simplified representation of JSON Schema 7.
+ */
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema | JsonSchema[];
+    required?: string[];
+    additionalProperties?: boolean | JsonSchema;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    const?: unknown;
+    oneOf?: JsonSchema[];
+    anyOf?: JsonSchema[];
+    allOf?: JsonSchema[];
+    $ref?: string;
+    definitions?: Record<string, JsonSchema>;
+    [key: string]: unknown;
+}
+/**
+ * MCP Tool definition as used in ListToolsRequest response.
+ */
+export interface McpToolDefinition {
+    /** Tool name (procedure path joined with dots) */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** JSON Schema for tool input */
+    inputSchema: JsonSchema;
+    /**
+     * JSON Schema of the result (MCP 2025-06-18 structured output). Only a tool whose output is
+     * an object has it: then each successful result also has `structuredContent`.
+     */
+    outputSchema?: JsonSchema;
+}
+/**
+ * Extended MCP Tool with procedure metadata.
+ * Used internally for mapping and introspection.
+ */
+export interface McpTool extends McpToolDefinition {
+    /** Original procedure path */
+    procedurePath: ProcedurePath;
+    /** Whether the procedure supports streaming output */
+    streaming?: boolean;
+    /** Procedure tags for filtering */
+    tags?: string[];
+}
+/**
+ * MCP tool call result content item.
+ */
+export interface McpContentItem {
+    type: "text" | "image" | "resource";
+    text?: string;
+    data?: string;
+    mimeType?: string;
+}
+/**
+ * MCP tool call result.
+ */
+export interface McpToolResult {
+    content: McpContentItem[];
+    isError?: boolean;
+}
+/**
+ * MCP transport types.
+ */
+export type McpTransportType = "stdio" | "sse";
+/**
+ * MCP server information.
+ */
+export interface McpServerInfo {
+    name: string;
+    version: string;
+}
+/**
+ * MCP tool filter options.
+ */
+export interface McpToolFilter {
+    /** Only include procedures with these tags */
+    includeTags?: string[];
+    /** Exclude procedures with these tags */
+    excludeTags?: string[];
+    /** Exclude procedures marked as internal */
+    excludeInternal?: boolean;
+    /** Only include procedures under this path prefix */
+    pathPrefix?: ProcedurePath;
+    /** Only include the procedures for which this function gives true */
+    include?: (path: ProcedurePath) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,WAAW,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,OAAQ,SAAQ,iBAAiB;IAChD,8BAA8B;IAC9B,aAAa,EAAE,aAAa,CAAC;IAC7B,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,KAAK,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC;CAC5C"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * MCP Core Types
+ *
+ * Types for MCP (Model Context Protocol) integration with the procedure system.
+ * Extends MCP SDK types with procedure-specific metadata.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,66 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Map typed procedures to MCP tools: JSON Schema from Zod, tool names, and input and result conversion for Model Context Protocol servers.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "json-schema",
+    "zod",
+    "tools"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/mcp"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@procedures/client": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3",
+    "@procedures/client": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
 }

package/src/context/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Context exports.
+ */
+
+export {
+  isMcpContext,
+  getMcpContext,
+  type McpCallContext,
+  type McpProcedureContext,
+} from "./mcp-context.js";

package/src/context/mcp-context.ts

@@ -0,0 +1,80 @@
+/**
+ * MCP Context Types
+ *
+ * Extended procedure context types when called via MCP transport.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { McpTransportType } from "../types.js";
+
+/**
+ * MCP-specific context data available when a procedure is called via MCP.
+ */
+export interface McpCallContext {
+  /** MCP request ID */
+  requestId: string;
+
+  /** Transport type used (stdio or sse) */
+  transport: McpTransportType;
+
+  /** Client information from MCP connection (if available) */
+  clientInfo?: {
+    name?: string;
+    version?: string;
+  };
+
+  /** Raw MCP metadata */
+  rawMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Extended procedure context when called via MCP transport.
+ *
+ * Provides access to MCP-specific metadata through the `mcp` property.
+ */
+export interface McpProcedureContext extends ProcedureContext {
+  /** MCP-specific context data */
+  mcp: McpCallContext;
+}
+
+/**
+ * Type guard to check if context is from MCP transport.
+ *
+ * @param context - Procedure context to check
+ * @returns True if context has MCP metadata
+ *
+ * @example
+ * ```typescript
+ * handler: async (input, ctx) => {
+ *   if (isMcpContext(ctx)) {
+ *     console.log(`Called via MCP: ${ctx.mcp.transport}`);
+ *   }
+ *   // ... handle request
+ * }
+ * ```
+ */
+export function isMcpContext(
+  context: ProcedureContext
+): context is McpProcedureContext {
+  return (
+    context !== undefined &&
+    typeof context === "object" &&
+    "mcp" in context &&
+    context.mcp !== undefined
+  );
+}
+
+/**
+ * Get MCP context if available, undefined otherwise.
+ *
+ * @param context - Procedure context to check
+ * @returns MCP context data or undefined
+ */
+export function getMcpContext(
+  context: ProcedureContext
+): McpCallContext | undefined {
+  if (isMcpContext(context)) {
+    return context.mcp;
+  }
+  return undefined;
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+/**
+ * MCP Core Package
+ *
+ * Core types and utilities for MCP (Model Context Protocol) integration
+ * with the procedure system.
+ *
+ * @packageDocumentation
+ */
+
+// Types
+export type {
+  JsonSchema,
+  McpToolDefinition,
+  McpTool,
+  McpContentItem,
+  McpToolResult,
+  McpTransportType,
+  McpServerInfo,
+  McpToolFilter,
+} from "./types.js";
+
+// Schema utilities
+export {
+  toolInputSchema,
+  cachedToolInputSchema,
+  toolOutputSchema,
+  cachedToolOutputSchema,
+  zodToJsonSchema,
+  cachedZodToJsonSchema,
+  clearSchemaCache,
+  getSchemaCacheSize,
+  type ZodToJsonSchemaOptions,
+} from "./schema/index.js";
+
+// Mapping utilities
+export {
+  encodePath,
+  decodePath,
+  isValidPathSegment,
+  isValidPath,
+  sanitizePathSegment,
+  sanitizePath,
+  procedureToMcpTool,
+  proceduresToMcpTools,
+  toToolDefinition,
+  createToolMap,
+  findToolByPath,
+} from "./mapping/index.js";
+
+// Context utilities
+export {
+  isMcpContext,
+  getMcpContext,
+  type McpCallContext,
+  type McpProcedureContext,
+} from "./context/index.js";

package/src/mapping/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Mapping utilities exports.
+ */
+
+export {
+  encodePath,
+  decodePath,
+  isValidPathSegment,
+  isValidPath,
+  sanitizePathSegment,
+  sanitizePath,
+} from "./path-encoder.js";
+
+export {
+  procedureToMcpTool,
+  proceduresToMcpTools,
+  toToolDefinition,
+  createToolMap,
+  findToolByPath,
+} from "./procedure-to-tool.js";

package/src/mapping/path-encoder.ts

@@ -0,0 +1,103 @@
+/**
+ * Path Encoder
+ *
+ * Converts procedure paths to/from MCP tool names.
+ * MCP tool names should be valid identifiers (alphanumeric with dots/underscores).
+ */
+
+import type { ProcedurePath } from "@procedures/client";
+
+/**
+ * Encode a procedure path to an MCP tool name.
+ *
+ * Strategy: Join path segments with dots.
+ * Most procedure paths are already MCP-compatible (lowercase, alphanumeric).
+ *
+ * @param path - Procedure path array
+ * @returns MCP tool name string
+ *
+ * @example
+ * encodePath(["fs", "read"]) // "fs.read"
+ * encodePath(["mongo", "collections", "list"]) // "mongo.collections.list"
+ */
+export function encodePath(path: ProcedurePath): string {
+  return path.join(".");
+}
+
+/**
+ * Decode an MCP tool name back to procedure path.
+ *
+ * @param toolName - MCP tool name string
+ * @returns Procedure path array
+ *
+ * @example
+ * decodePath("fs.read") // ["fs", "read"]
+ * decodePath("mongo.collections.list") // ["mongo", "collections", "list"]
+ */
+export function decodePath(toolName: string): ProcedurePath {
+  return toolName.split(".");
+}
+
+/**
+ * Validate that a path segment is MCP-compatible.
+ *
+ * Valid segments:
+ * - Start with letter or underscore
+ * - Contain only letters, numbers, underscores, hyphens
+ *
+ * @param segment - Path segment to validate
+ * @returns True if segment is valid for MCP tool names
+ */
+export function isValidPathSegment(segment: string): boolean {
+  return /^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(segment);
+}
+
+/**
+ * Validate that an entire path is MCP-compatible.
+ *
+ * @param path - Procedure path to validate
+ * @returns True if all segments are valid
+ */
+export function isValidPath(path: ProcedurePath): boolean {
+  return path.length > 0 && path.every(isValidPathSegment);
+}
+
+/**
+ * Sanitize a path segment for MCP compatibility.
+ *
+ * Replaces invalid characters with underscores.
+ *
+ * @param segment - Path segment to sanitize
+ * @returns Sanitized segment
+ *
+ * @example
+ * sanitizePathSegment("my-func") // "my-func" (valid)
+ * sanitizePathSegment("123abc") // "_123abc" (prefix if starts with number)
+ * sanitizePathSegment("my.func") // "my_func" (replace dots)
+ */
+export function sanitizePathSegment(segment: string): string {
+  // Replace invalid chars with underscores
+  let sanitized = segment.replace(/[^a-zA-Z0-9_-]/g, "_");
+
+  // Prefix if starts with number
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  // Ensure not empty
+  if (!sanitized) {
+    sanitized = "_";
+  }
+
+  return sanitized;
+}
+
+/**
+ * Sanitize an entire path for MCP compatibility.
+ *
+ * @param path - Procedure path to sanitize
+ * @returns Sanitized path
+ */
+export function sanitizePath(path: ProcedurePath): ProcedurePath {
+  return path.map(sanitizePathSegment);
+}