@procedures/mcp 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# @procedures/mcp
+
+## 0.2.0
+
+### Minor Changes
+
+- 0cf4bea: **Invocation capabilities** (packages/documentation/CAPABILITIES-2026-10.md, the guide is client/docs/CAPABILITIES.md). Each call operates with a capability: a clearance, permitted effects and a deadline. A nested call gets the same capability or a narrower one.
+  
+  - Procedures declare `metadata.effects` (`reads`, `writes`, `destructive`, `idempotent`). Each procedure of these packages declares them.
+  - `hostPolicy({ capability, readOnly, clearanceOrder, resources, admitItem })`, and `new Client({ capability })`. A refused call gives `FORBIDDEN` (HTTP 403) with a reason.
+  - `ctx.capability` and `ctx.resources` are new required fields of `ProcedureContext`. A test that makes a context by hand adds `capability: {}` and `resources: {}`.
+  - An application gives its clearance and resource types by augmenting `Register`.
+  - The timeout interceptor sets the deadline of the capability, and a remote call sends the remaining time.
+  - The MCP tools have hints (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) from the effects. `mark mcp --read-only` (or `MCP_READ_ONLY=1`) serves only the tools that change nothing.
+  - **Breaking:** `git.remote` only reads the URL. `git.remote.set` sets it (before: `git.remote` with `url`).
+
+### Patch Changes
+
+- Updated dependencies [0cf4bea]
+- Updated dependencies [44d3e30]
+- Updated dependencies [76d0d64]
+  - @procedures/client@0.2.0
+
+## 0.1.0
+
+The first release on npm. The packages of the client monorepo have one version together.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,360 @@
-# Temporary Holding Version
+# @procedures/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@procedures/mcp?color=2346c4&label=npm)](https://www.npmjs.com/package/@procedures/mcp)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green.svg)](https://nodejs.org/)
+[![MCP](https://img.shields.io/badge/MCP-Protocol-purple.svg)](https://modelcontextprotocol.io/)
+
+> Core types and utilities for MCP (Model Context Protocol) integration. Converts Zod schemas and procedures to MCP-compatible formats.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [zodToJsonSchema](#zodtojsonschema)
+  - [procedureToMcpTool](#proceduretomcptool)
+  - [proceduresToMcpTools](#procedurestomcptools)
+- [Tool Filtering](#tool-filtering)
+- [Integration](#integration)
+- [Requirements](#requirements)
+- [License](#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
+
+```bash
+npm install @procedures/mcp
+```
+
+---
+
+## Architecture
+
+### Conversion Pipeline
+
+```mermaid
+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
+
+```mermaid
+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
+
+```mermaid
+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
+
+```typescript
+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.
+
+```typescript
+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:**
+```typescript
+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.
+
+```typescript
+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:**
+```typescript
+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.
+
+```typescript
+function proceduresToMcpTools(
+  procedures: Procedure[],
+  filter?: McpToolFilter
+): McpTool[];
+```
+
+**Example:**
+```typescript
+// 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:
+
+```typescript
+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
+
+```mermaid
+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:**
+```typescript
+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
+
+```typescript
+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
+
+```mermaid
+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