@procedures/mcp

Core types and utilities for MCP (Model Context Protocol) integration. Converts Zod schemas and procedures to MCP-compatible formats.

Table of Contents

• Overview
• Installation
• Architecture
• Quick Start
• API Reference
  • zodToJsonSchema
  • procedureToMcpTool
  • proceduresToMcpTools
• Tool Filtering
• Integration
• Requirements
• License

Overview

mcp provides the foundation for MCP integration:

• Schema Conversion - Convert Zod schemas to JSON Schema format
• Procedure Mapping - Transform procedures to MCP tool definitions
• Filtering - Control which procedures become MCP tools
• Type Definitions - TypeScript types for MCP tools and filters

Installation

npm install @procedures/mcp

Architecture

Conversion Pipeline

graph LR
    subgraph "Input"
        Proc[Procedure]
        Zod[Zod Schema]
    end

    subgraph "mcp Package"
        Z2J[zodToJsonSchema]
        P2T[procedureToMcpTool]
    end

    subgraph "Output"
        JSON[JSON Schema]
        Tool[MCP Tool]
    end

    Zod --> Z2J
    Z2J --> JSON
    Proc --> P2T
    JSON --> P2T
    P2T --> Tool

Procedure to MCP Tool Mapping

graph TB
    subgraph "Procedure"
        Path[path: string[]]
        Meta[metadata.description]
        Input[input: ZodSchema]
        Handler[handler: Function]
    end

    subgraph "MCP Tool"
        Name[name: string]
        Desc[description: string]
        Schema[inputSchema: JSONSchema]
    end

    Path -->|"join('.')"| Name
    Meta --> Desc
    Input -->|zodToJsonSchema| Schema

System Integration

graph TB
    subgraph "Procedure Registry"
        R1[fs.read]
        R2[git.commit]
        R3[shell.run]
        R4[...]
    end

    subgraph "mcp"
        Convert[proceduresToMcpTools]
        Filter[McpToolFilter]
    end

    subgraph "client-mcp"
        Transport[McpServerTransport]
    end

    subgraph "Claude"
        Tools[MCP Tools]
    end

    R1 --> Convert
    R2 --> Convert
    R3 --> Convert
    R4 --> Convert
    Filter --> Convert
    Convert --> Transport
    Transport --> Tools

Quick Start

import { proceduresToMcpTools, zodToJsonSchema } from "@procedures/mcp";
import { PROCEDURE_REGISTRY } from "@procedures/client";

// Convert all registered procedures to MCP tools
const tools = proceduresToMcpTools(PROCEDURE_REGISTRY.getAll());

// Convert a Zod schema to JSON Schema
const jsonSchema = zodToJsonSchema(myZodSchema);

API Reference

zodToJsonSchema

Converts a Zod schema to JSON Schema format for MCP tool input definitions.

function zodToJsonSchema(schema: ZodType): JsonSchema;

Supported Zod Types:

| Zod Type | JSON Schema | |----------|-------------| | z.string() | { type: "string" } | | z.number() | { type: "number" } | | z.boolean() | { type: "boolean" } | | z.array() | { type: "array", items: ... } | | z.object() | { type: "object", properties: ... } | | z.enum() | { type: "string", enum: [...] } | | z.optional() | Removes from required | | z.default() | Adds default value | | z.describe() | Adds description |

Example:

import { z } from "zod";
import { zodToJsonSchema } from "@procedures/mcp";

const schema = z.object({
  path: z.string().describe("File path"),
  encoding: z.enum(["utf8", "base64"]).default("utf8"),
});

const jsonSchema = zodToJsonSchema(schema);
// {
//   type: "object",
//   properties: {
//     path: { type: "string", description: "File path" },
//     encoding: { type: "string", enum: ["utf8", "base64"], default: "utf8" }
//   },
//   required: ["path"]
// }

procedureToMcpTool

Converts a single procedure to an MCP tool definition.

function procedureToMcpTool(procedure: Procedure): McpTool;

interface McpTool {
  name: string;           // Dot-joined path: "fs.read"
  description: string;    // From procedure metadata
  inputSchema: JsonSchema; // Converted from Zod
}

Example:

const tool = procedureToMcpTool(fsReadProcedure);
// {
//   name: "fs.read",
//   description: "Read file contents",
//   inputSchema: { type: "object", properties: { path: ... } }
// }

proceduresToMcpTools

Converts multiple procedures to MCP tools with optional filtering.

function proceduresToMcpTools(
  procedures: Procedure[],
  filter?: McpToolFilter
): McpTool[];

Example:

// Convert all procedures
const allTools = proceduresToMcpTools(PROCEDURE_REGISTRY.getAll());

// Convert with filtering
const filteredTools = proceduresToMcpTools(procedures, {
  includeTags: ["fs", "git"],
  excludeInternal: true,
});

Tool Filtering

Control which procedures are exposed as MCP tools:

interface McpToolFilter {
  includeTags?: string[];      // Only include procedures with these tags
  excludeTags?: string[];      // Exclude procedures with these tags
  excludeInternal?: boolean;   // Exclude procedures starting with _
  pathPrefix?: string[];       // Only include procedures with this path prefix
  include?: (path: string[]) => boolean;  // Only the procedures for which it gives true
}

Filter Examples

graph TB
    subgraph "Original (10 procedures)"
        All[fs.read, fs.write, git.commit,<br/>_internal.debug, api.users, ...]
    end

    subgraph "excludeInternal: true"
        NoInt[fs.read, fs.write, git.commit,<br/>api.users, ...]
    end

    subgraph "pathPrefix: ['fs']"
        FSOnly[fs.read, fs.write]
    end

    subgraph "includeTags: ['public']"
        Public[Tagged as public only]
    end

    All --> NoInt
    All --> FSOnly
    All --> Public

Usage:

import { proceduresToMcpTools, type McpToolFilter } from "@procedures/mcp";

const filter: McpToolFilter = {
  includeTags: ["fs", "git"],      // Only the procedures with these tags
  excludeTags: ["internal"],       // Exclude internal
  excludeInternal: true,           // Exclude _prefixed
  pathPrefix: ["fs"],              // Only fs.* procedures
};

const tools = proceduresToMcpTools(procedures, filter);

Integration

With client-mcp

import { McpServerTransport } from "@procedures/mcp-server";
import { proceduresToMcpTools } from "@procedures/mcp";

// client-mcp uses mcp internally
const transport = new McpServerTransport(server, {
  transport: "stdio",
  // Filter uses McpToolFilter from mcp package
  filter: {
    excludeInternal: true,
  },
});

Package Hierarchy

graph BT
    subgraph "Implementation"
        Impl[impl-mcp-dev]
    end

    subgraph "Transport"
        ClientMCP[client-mcp]
    end

    subgraph "Core"
        MCP[mcp]
        Client[client]
    end

    subgraph "External"
        SDK[@modelcontextprotocol/sdk]
    end

    Impl --> ClientMCP
    ClientMCP --> MCP
    ClientMCP --> Client
    MCP --> Client
    ClientMCP --> SDK

Requirements

• Node.js >= 22
• Dependencies:
  • @procedures/client
  • zod

License

MIT