@kya-os/mcp-i-cloudflare 1.1.0 → 1.2.0

package/README.md

@@ -1,25 +1,41 @@
 # @kya-os/mcp-i-cloudflare
 
+> **⚠️ DEPRECATED**: This adapter does not support MCP protocol transports (SSE/HTTP streaming).
+>
+> **Use [McpAgent from agents/mcp](https://developers.cloudflare.com/agents/model-context-protocol/) instead.**
+>
+> See the [migration guide](../../CLOUDFLARE_DEPLOYMENT.md) for updated implementation patterns.
+
+---
+
 Cloudflare Workers runtime for MCP-I (Model Context Protocol with Identity). Deploy cryptographically-signed MCP servers to Cloudflare's edge network with full identity support.
 
-## Features
+## Status
+
+This package provides the MCP-I runtime layer for Cloudflare Workers but **does not** include MCP protocol transport support. For a complete MCP server implementation on Cloudflare Workers with SSE and HTTP streaming support, use the [Cloudflare Agents SDK](https://developers.cloudflare.com/agents/model-context-protocol/) with `agents/mcp`.
+
+### What This Package Provides
 
-- ✅ **Full MCP-I Support**: Cryptographic signing of all tool responses
-- ✅ **Edge-Native**: Built for Cloudflare Workers with Web Crypto API
-- ✅ **SSE Streaming**: Support for Server-Sent Events and Streamable HTTP (v1.1.0+)
-- ✅ **Claude Desktop Compatible**: Works with mcp-remote proxy via SSE endpoints
 - ✅ **Identity Management**: DID-based identity with Ed25519 keys
+- ✅ **Cryptographic Proofs**: Sign tool responses with detached proofs
 - ✅ **Session Management**: Stateless sessions with nonce protection
 - ✅ **KV Storage**: Use Workers KV for nonce cache and identity
-- ✅ **Secrets Management**: Store private keys securely with Wrangler secrets
-- ✅ **Progressive Verification**: Optimized for edge performance
+- ✅ **Audit Logging**: Track all operations with configurable logging
+
+### What This Package Does NOT Provide
 
-## Quick Start
+- ❌ **MCP Protocol Transports**: No SSE or HTTP streaming support
+- ❌ **MCP Client Compatibility**: Cannot connect to Claude Desktop or MCP Inspector
+- ❌ **Durable Objects**: No built-in state management for sessions
+
+For a complete MCP server that works with Claude Desktop and other MCP clients, use `agents/mcp` with the runtime from this package for optional proof generation.
+
+## Quick Start with McpAgent
 
 ### 1. Create a new project
 
 ```bash
-npx @kya-os/create-mcpi-app my-agent --platform cloudflare --mode mcp-i
+npx @kya-os/create-mcpi-app my-agent --platform cloudflare
 cd my-agent
 ```
 
@@ -38,130 +54,85 @@ npm run kv:create
 # Copy the ID from output and update wrangler.toml
 ```
 
-### 4. Set Identity Secrets
-
-```bash
-# Generate identity locally (for development)
-npx mcpi init
-
-# Set secrets for production
-wrangler secret put MCP_IDENTITY_PRIVATE_KEY
-wrangler secret put MCP_IDENTITY_PUBLIC_KEY
-wrangler secret put MCP_IDENTITY_DID
-```
-
-### 5. Deploy
+### 4. Deploy
 
 ```bash
 npm run deploy
 ```
 
-## Manual Setup
-
-### Installation
+## Using MCP-I Runtime for Proof Generation
 
-```bash
-npm install @kya-os/mcp-i-cloudflare @modelcontextprotocol/sdk hono zod
-```
-
-### Worker Implementation
+While the full adapter is deprecated, you can still use the MCP-I runtime with McpAgent for cryptographic proof generation:
 
 ```typescript
-// src/index.ts
-import { Hono } from 'hono';
-import { cors } from 'hono/cors';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { createMCPIServer, MCPICloudflareEnv } from '@kya-os/mcp-i-cloudflare';
-import { z } from 'zod';
-
-interface Env extends MCPICloudflareEnv {
-  NONCE_CACHE: KVNamespace;
-  // Optional for development
-  IDENTITY_KV?: KVNamespace;
-}
-
-const app = new Hono<{ Bindings: Env }>();
-
-// Enable CORS
-app.use('/*', cors({
-  origin: '*',
-  allowMethods: ['GET', 'POST', 'OPTIONS'],
-  allowHeaders: ['Content-Type', 'Authorization'],
-}));
+import { McpAgent } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createCloudflareRuntime, type CloudflareEnv } from "@kya-os/mcp-i-cloudflare";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+export class MyMCP extends McpAgent {
+  server = new McpServer({
+    name: "my-server",
+    version: "1.0.0"
+  });
 
-// Initialize MCP-I runtime
-let mcpiRuntime: ReturnType<typeof createMCPIServer> | null = null;
-let mcpServer: McpServer | null = null;
+  private mcpiRuntime?: any;
 
-const initialize = async (env: Env) => {
-  if (!mcpiRuntime) {
-    // Create MCP-I runtime
-    mcpiRuntime = createMCPIServer(env);
-    await mcpiRuntime.initialize();
+  constructor(state: DurableObjectState, env: CloudflareEnv) {
+    super(state, env);
 
-    // Create MCP server
-    mcpServer = new McpServer({
-      name: 'my-agent',
-      version: '1.0.0'
+    // Optional: Initialize MCP-I runtime for proof generation
+    this.mcpiRuntime = createCloudflareRuntime({
+      env: env,
+      audit: {
+        enabled: true,
+        logFunction: (r) => console.log('[MCP-I]', r)
+      }
     });
+  }
 
-    // Register tools with automatic signing
-    mcpServer.tool(
-      'greet',
-      'Greet a user',
-      z.object({ name: z.string() }),
-      async (args: any) => {
-        // Get session (in production, from request headers)
-        const session = await mcpiRuntime!.getCurrentSession();
-
-        // Process with automatic proof generation
-        return mcpiRuntime!.processToolCall(
-          'greet',
-          args,
-          async ({ name }) => ({
-            content: [{
-              type: 'text',
-              text: `Hello, ${name}!`
-            }]
-          }),
-          session
-        );
+  async init() {
+    await this.mcpiRuntime?.initialize();
+
+    this.server.tool(
+      "greet",
+      "Greet a user",
+      { name: z.string() },
+      async ({ name }) => {
+        const result = {
+          content: [{ type: "text" as const, text: `Hello, ${name}!` }]
+        };
+
+        // Optional: Generate cryptographic proof
+        if (this.mcpiRuntime) {
+          const { proof } = await this.mcpiRuntime.processToolCall(
+            "greet",
+            { name },
+            async () => result,
+            null
+          );
+          console.log('[PROOF]', { did: proof.did, signature: proof.signature.substring(0, 20) });
+        }
+
+        return result;
       }
     );
   }
-  return { mcpiRuntime, mcpServer };
-};
-
-// Health check
-app.get('/health', (c) => {
-  return c.json({
-    status: 'healthy',
-    timestamp: new Date().toISOString()
-  });
-});
-
-// Identity endpoint
-app.get('/.well-known/mcp-identity', async (c) => {
-  const { mcpiRuntime } = await initialize(c.env);
-  const identity = await mcpiRuntime!.getIdentity();
-
-  return c.json({
-    did: identity.did,
-    keyId: identity.keyId,
-    publicKey: identity.publicKey
-  });
-});
+}
 
-// MCP endpoint
-app.post('/mcp', async (c) => {
-  const { mcpServer } = await initialize(c.env);
-  const request = await c.req.json();
+const app = new Hono();
 
-  // Process MCP request
-  const response = await mcpServer!.handleRequest(request);
+app.use("/*", cors({
+  origin: "*",
+  allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+  allowHeaders: ["Content-Type", "Authorization", "mcp-session-id", "mcp-protocol-version"],
+  exposeHeaders: ["mcp-session-id"],
+}));
 
-  return c.json(response);
-});
+app.get("/health", (c) => c.json({ status: 'healthy' }));
+app.mount("/sse", MyMCP.serveSSE("/sse").fetch, { replaceRequest: false });
+app.mount("/mcp", MyMCP.serve("/mcp").fetch, { replaceRequest: false });
 
 export default app;
 ```
@@ -199,265 +170,116 @@ Dedicated SSE endpoint for Claude Desktop compatibility:
 ### `/.well-known/mcp-identity/*`
 Identity verification endpoints for cryptographic proof validation.
 
-## Claude Desktop Integration
+## Response Format
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+MCP-I extends standard MCP responses with detached cryptographic proofs. Understanding the response structure is important for integration.
+
+### Standard Tool Response
 
 ```json
 {
-  "mcpServers": {
-    "my-agent": {
-      "command": "npx",
-      "args": ["mcp-remote", "https://my-agent.workers.dev/sse"]
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "result": {
+      "content": [
+        {
+          "type": "text",
+          "text": "Hello, World!"
+        }
+      ]
+    },
+    "proof": {
+      "timestamp": 1704067200000,
+      "nonce": "abc123...",
+      "did": "did:key:z6Mkh...",
+      "signature": "base64...",
+      "algorithm": "Ed25519",
+      "sessionId": "session-123"
     }
   }
 }
 ```
 
-**Note:** Both `/mcp` and `/sse` work with Claude Desktop. We recommend `/sse` for explicit SSE mode.
-The `/mcp` endpoint auto-detects transport based on Accept headers.
-
-### wrangler.toml Configuration
-
-```toml
-name = "my-mcp-agent"
-main = "src/index.ts"
-compatibility_date = "2025-01-01"
-compatibility_flags = ["nodejs_compat"]
-
-# KV Namespace for nonce cache (required)
-[[kv_namespaces]]
-binding = "NONCE_CACHE"
-id = "your-kv-namespace-id"
-
-# Optional: KV for identity storage (development)
-# [[kv_namespaces]]
-# binding = "IDENTITY_KV"
-# id = "your-identity-kv-id"
+### Why `result.result`?
 
-# Environment variables
-[vars]
-XMCP_I_TS_SKEW_SEC = "120"
-XMCP_I_SESSION_TTL = "1800"
+The nested structure exists because:
+- **Outer `result`**: Required by JSON-RPC 2.0 specification
+- **Inner `result`**: Contains the actual MCP tool response
+- **`proof`**: Detached cryptographic proof (MCP-I extension)
 
-# Production environment
-[env.production]
-name = "my-mcp-agent-production"
+This structure maintains **backward compatibility** - standard MCP clients can extract `result.result` and ignore proofs.
 
-[[env.production.kv_namespaces]]
-binding = "NONCE_CACHE"
-id = "your-production-kv-id"
-```
-
-## Identity Management
+### LLM Visibility
 
-### Development
+**Important:** Language models (LLMs) DO NOT see cryptographic proofs.
 
-For development, you can store identity in KV:
+The proof is extracted by the MCP client (like mcp-remote) and sent to a verifier service. The LLM only receives the business data from `result.result.content`.
 
-```typescript
-// Identity stored in IDENTITY_KV namespace
-const env = {
-  IDENTITY_KV: kvNamespace,
-  NONCE_CACHE: nonceNamespace
-};
+**Data flow:**
 ```
-
-### Production
-
-For production, use Wrangler secrets:
-
-```bash
-# Generate identity locally
-npx mcpi init
-
-# Copy values from .mcpi/identity.json
-wrangler secret put MCP_IDENTITY_PRIVATE_KEY
-wrangler secret put MCP_IDENTITY_PUBLIC_KEY
-wrangler secret put MCP_IDENTITY_DID
-wrangler secret put MCP_IDENTITY_KEY_ID
+MCP Server → [result + proof]
+             ├─→ proof → Agent Bouncer Service (verification)
+             └─→ result.result.content → LLM
 ```
 
-## Tool Development
-
-Tools have the same format as Node.js MCP-I:
+This "transparent security" design keeps authentication at the protocol layer, invisible to AI.
 
-```typescript
-// src/tools/weather.ts
-import { z } from 'zod';
-
-export const weatherTool = {
-  name: 'get_weather',
-  description: 'Get weather for a location',
-  inputSchema: z.object({
-    location: z.string(),
-    units: z.enum(['celsius', 'fahrenheit']).optional()
-  }),
-  handler: async ({ location, units = 'celsius' }) => {
-    // Tool implementation
-    const weather = await fetchWeather(location, units);
-
-    return {
-      content: [{
-        type: 'text',
-        text: `Weather in ${location}: ${weather.temp}°${units[0].toUpperCase()}`
-      }]
-    };
-  }
-};
-```
+### Proof Fields
 
-## Verification Endpoints
+| Field | Description |
+|-------|-------------|
+| `timestamp` | Unix timestamp (ms) when proof was created |
+| `nonce` | Unique random value to prevent replay attacks (5-min lifetime) |
+| `did` | Decentralized Identifier of the signing agent |
+| `signature` | Ed25519 signature (base64) over proof metadata |
+| `sessionId` | Session identifier for request/response correlation |
 
-The runtime provides built-in verification endpoints:
+**See [MCP_I_RESPONSE_SPEC.md](../../MCP_I_RESPONSE_SPEC.md) for complete documentation.**
 
-### Identity Verification
-```bash
-GET /.well-known/mcp-identity
-
-Response:
-{
-  "did": "did:key:z6MkhaXgBZD...",
-  "keyId": "did:key:z6MkhaXgBZD...#key-1",
-  "publicKey": "base64..."
-}
-```
-
-### Proof Verification
-```bash
-POST /verify
+## Claude Desktop Integration
 
-Request:
-{
-  "data": { ... },
-  "proof": { ... }
-}
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
-Response:
+```json
 {
-  "valid": true,
-  "metadata": { ... }
-}
-```
-
-## Performance Optimization
-
-### Edge Caching
-
-Use KV with TTL for efficient caching:
-
-```typescript
-// Cache DID documents
-await env.CACHE_KV.put(
-  `did:${did}`,
-  JSON.stringify(document),
-  { expirationTtl: 3600 } // 1 hour
-);
-```
-
-### Progressive Verification
-
-The runtime supports progressive verification for optimal edge performance:
-
-```typescript
-// Stage-1: Quick offline checks (no network)
-const quickCheck = await runtime.verifyOffline(data);
-
-// Stage-2: Full verification (may use network)
-if (quickCheck.valid) {
-  const fullCheck = await runtime.verifyOnline(data);
-}
-```
-
-## Monitoring
-
-### Metrics
-
-Track MCP-I operations:
-
-```typescript
-// In your worker
-app.use('*', async (c, next) => {
-  const start = Date.now();
-  await next();
-
-  // Log to Analytics Engine or Workers Analytics
-  c.env.ANALYTICS.writeDataPoint({
-    endpoint: c.req.path,
-    duration: Date.now() - start,
-    status: c.res.status
-  });
-});
-```
-
-### Audit Logging
-
-Enable audit logging for security:
-
-```typescript
-const runtime = createMCPIServer({
-  ...env,
-  audit: {
-    enabled: true,
-    logFunction: (record) => {
-      // Send to Logflare, Datadog, etc.
-      env.LOGGER.log(record);
+  "mcpServers": {
+    "my-agent": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://my-agent.workers.dev/sse"]
     }
   }
-});
+}
 ```
 
-## Deployment
-
-### Local Development
+**Note:** Both `/mcp` and `/sse` work with Claude Desktop. We recommend `/sse` for explicit SSE mode.
+The `/mcp` endpoint auto-detects transport based on Accept headers.
 
-```bash
-# Start local dev server
-npm run dev
+### wrangler.toml Configuration
 
-# Test endpoints
-curl http://localhost:8787/health
-curl http://localhost:8787/.well-known/mcp-identity
-```
+```toml
+name = "my-mcp-agent"
+main = "src/index.ts"
+compatibility_date = "2025-06-18"
+compatibility_flags = ["nodejs_compat"]
 
-### Production Deployment
+[[durable_objects.bindings]]
+name = "MCP_OBJECT"
+class_name = "MyMCP"
 
-```bash
-# Deploy to Cloudflare
-npm run deploy
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["MyMCP"]
 
-# Deploy to specific environment
-npm run deploy -- --env production
+[[kv_namespaces]]
+binding = "NONCE_CACHE"
+id = "your-kv-namespace-id"
 
-# Check deployment
-wrangler tail
+[vars]
+XMCP_I_TS_SKEW_SEC = "120"
+XMCP_I_SESSION_TTL = "1800"
 ```
 
-## Security Best Practices
-
-1. **Never commit private keys** - Use Wrangler secrets
-2. **Rotate keys regularly** - Use `mcpi rotate` command
-3. **Limit KV access** - Use least privilege bindings
-4. **Enable audit logging** - Track all operations
-5. **Use CORS properly** - Restrict origins in production
-6. **Monitor rate limits** - Implement request throttling
-
-## Troubleshooting
-
-### Common Issues
-
-**Error: No identity found**
-- Ensure secrets are set: `wrangler secret list`
-- Check KV binding in wrangler.toml
-
-**Error: Nonce already used**
-- Check KV namespace is configured
-- Verify TTL settings
-
-**Error: Timestamp outside window**
-- Check clock skew settings
-- Ensure client/server time sync
-
 ## API Reference
 
 ### MCPICloudflareRuntime
@@ -502,10 +324,10 @@ interface MCPICloudflareEnv {
 }
 ```
 
-## Examples
+## Migration Guide
 
-See the [examples](../../examples/cloudflare-mcpi) directory for complete working examples.
+See [CLOUDFLARE_DEPLOYMENT.md](../../CLOUDFLARE_DEPLOYMENT.md) for complete migration instructions and working examples.
 
 ## License
 
-MIT
+MIT

package/dist/adapter.d.ts

@@ -10,6 +10,7 @@
  */
 import type { MCPICloudflareConfig } from './index';
 import type { MCPIRuntimeBase } from '@kya-os/mcp-i-core';
+import { KVProofArchive } from './storage/kv-proof-archive';
 export interface ToolDefinition {
     name: string;
     description: string;
@@ -30,10 +31,11 @@ declare class CloudflareMCPServer {
     private runtime;
     private serverInfo;
     private tools;
+    private proofArchive?;
     constructor(runtime: MCPIRuntimeBase, serverInfo: {
         name: string;
         version: string;
-    }, tools?: ToolDefinition[]);
+    }, tools?: ToolDefinition[], proofArchive?: KVProofArchive);
     /**
      * Handle JSON-RPC request
      */
@@ -42,6 +44,10 @@ declare class CloudflareMCPServer {
 /**
  * Create a complete MCP-I handler for Cloudflare Workers
  * with full MCP protocol support and identity features
+ *
+ * @deprecated This adapter does not support MCP transports (SSE/HTTP streaming).
+ * Use McpAgent from 'agents/mcp' instead.
+ * See: https://developers.cloudflare.com/agents/model-context-protocol/
  */
 export declare function createMCPICloudflareAdapter(config: MCPICloudflareAdapterConfig): {
     server: CloudflareMCPServer;

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,GAAG,CAAC;IACjB,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,cAAM,mBAAmB;IACvB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,KAAK,CAA8B;gBAGzC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAC7C,KAAK,GAAE,cAAc,EAAO;IAO9B;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;CAsFhD;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,2BAA2B;;;mBAkBtD,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EA0JnD"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAiB,MAAM,SAAS,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,GAAG,CAAC;IACjB,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,2BAA4B,SAAQ,oBAAoB;IACvE,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,cAAM,mBAAmB;IACvB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,YAAY,CAAC,CAAiB;gBAGpC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAC7C,KAAK,GAAE,cAAc,EAAO,EAC5B,YAAY,CAAC,EAAE,cAAc;IAQ/B;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;CA+GhD;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,2BAA2B;;;mBAuBtD,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;EAiTnD"}