@kya-os/create-mcpi-app 1.7.17 → 1.7.20

package/src/helpers/fetch-cloudflare-template.ts

@@ -0,0 +1,361 @@
+import fs from "fs-extra";
+import path from "path";
+import chalk from "chalk";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+interface CloudflareTemplateOptions {
+  verifierVersion?: string;
+  packageManager?: string;
+}
+
+/**
+ * Scaffold Cloudflare Worker verifier project
+ * This creates a standalone Worker verifier with KV nonce caching
+ */
+export async function fetchCloudflareTemplate(
+  projectPath: string,
+  options: CloudflareTemplateOptions = {}
+): Promise<void> {
+  const { verifierVersion = "^1.3.0", packageManager = "npm" } = options;
+
+  try {
+    console.log(
+      chalk.blue(`📦 Setting up Cloudflare Worker verifier with @kya-os/verifier@${verifierVersion}...`)
+    );
+
+    // Create package.json for Cloudflare Worker
+    const packageJson = {
+      name: path.basename(projectPath),
+      version: "1.0.0",
+      type: "module",
+      private: true,
+      scripts: {
+        dev: "wrangler dev",
+        deploy: "wrangler deploy",
+        "deploy:production": "wrangler deploy --env production",
+        "kv:create": "wrangler kv namespace create NONCE_CACHE",
+        "kv:create:preview": "wrangler kv namespace create NONCE_CACHE --preview",
+        tail: "wrangler tail",
+        test: "vitest",
+      },
+      dependencies: {
+        "@kya-os/verifier": verifierVersion,
+      },
+      devDependencies: {
+        "@cloudflare/workers-types": "^4.20240925.0",
+        "@cloudflare/vitest-pool-workers": "^0.5.0",
+        typescript: "^5.6.2",
+        vitest: "^2.1.5",
+        wrangler: "^4.42.2",
+      },
+    };
+
+    // Write package.json
+    fs.ensureDirSync(projectPath);
+    fs.writeJsonSync(path.join(projectPath, "package.json"), packageJson, { spaces: 2 });
+
+    // Create src directory
+    const srcDir = path.join(projectPath, "src");
+    fs.ensureDirSync(srcDir);
+
+    // Create Worker implementation
+    const workerContent = `import {
+  verifyWorker,
+  applyVerificationToResponse,
+  createConfigFromEnv,
+  type WorkerEnv,
+} from "@kya-os/verifier/worker";
+
+export default {
+  async fetch(request: Request, env: WorkerEnv): Promise<Response> {
+    const url = new URL(request.url);
+
+    // Health check endpoint
+    if (url.pathname === "/health") {
+      return new Response(
+        JSON.stringify({
+          status: "healthy",
+          timestamp: new Date().toISOString(),
+        }),
+        {
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    // Verification endpoint
+    if (url.pathname === "/verify") {
+      // Create config from environment variables
+      const config = createConfigFromEnv(env, {
+        allowMockData: false,
+      });
+
+      // Verify the proof
+      const result = await verifyWorker(request, config);
+
+      // If verification failed, return error response
+      if (!result.success) {
+        return applyVerificationToResponse(result);
+      }
+
+      // Success - extract agent context
+      const agent = result.agentContext;
+
+      // Check required scopes (example)
+      const requiredScopes = ["cart:add", "checkout"];
+      const hasRequiredScope = requiredScopes.some((scope) =>
+        agent?.scopes?.includes(scope)
+      );
+
+      if (!hasRequiredScope) {
+        return new Response(
+          JSON.stringify({
+            verified: false,
+            error: "Insufficient permissions",
+            requiredScopes,
+            providedScopes: agent?.scopes || [],
+          }),
+          {
+            status: 403,
+            headers: { "Content-Type": "application/json" },
+          }
+        );
+      }
+
+      // Success response with agent context
+      return new Response(
+        JSON.stringify({
+          verified: true,
+          agent: {
+            did: agent?.did,
+            kid: agent?.kid,
+            scopes: agent?.scopes,
+            session: agent?.session,
+          },
+          timestamp: new Date().toISOString(),
+        }),
+        {
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+
+    return new Response("Not Found", { status: 404 });
+  },
+};
+`;
+    fs.writeFileSync(path.join(srcDir, "index.ts"), workerContent);
+
+    // Create wrangler.toml
+    const wranglerContent = `#:schema node_modules/wrangler/config-schema.json
+name = "${path.basename(projectPath)}"
+main = "src/index.ts"
+compatibility_date = "2024-09-25"
+node_compat = true
+
+# KV Namespace for nonce cache
+# Run: wrangler kv:namespace create NONCE_CACHE
+# Then replace the id below with the output
+[[kv_namespaces]]
+binding = "NONCE_CACHE"
+id = "YOUR_KV_NAMESPACE_ID"
+
+# Environment variables (non-sensitive)
+[vars]
+KYA_API_URL = "https://knowthat.ai"
+XMCP_I_TS_SKEW_SEC = "120"
+XMCP_I_SESSION_TTL = "1800"
+
+# Production environment
+[env.production]
+name = "${path.basename(projectPath)}-production"
+vars = { KYA_API_URL = "https://knowthat.ai", XMCP_I_TS_SKEW_SEC = "60" }
+
+[[env.production.kv_namespaces]]
+binding = "NONCE_CACHE"
+id = "YOUR_PRODUCTION_KV_NAMESPACE_ID"
+`;
+    fs.writeFileSync(path.join(projectPath, "wrangler.toml"), wranglerContent);
+
+    // Create tsconfig.json
+    const tsconfigContent = {
+      compilerOptions: {
+        target: "ES2022",
+        module: "ES2022",
+        lib: ["ES2022"],
+        types: ["@cloudflare/workers-types"],
+        moduleResolution: "bundler",
+        resolveJsonModule: true,
+        allowSyntheticDefaultImports: true,
+        esModuleInterop: true,
+        strict: true,
+        skipLibCheck: true,
+        forceConsistentCasingInFileNames: true,
+      },
+      include: ["src/**/*"],
+    };
+    fs.writeJsonSync(path.join(projectPath, "tsconfig.json"), tsconfigContent, { spaces: 2 });
+
+    // Create .gitignore
+    const gitignoreContent = `node_modules/
+dist/
+.wrangler/
+.dev.vars
+.env
+.env.local
+*.log
+`;
+    fs.writeFileSync(path.join(projectPath, ".gitignore"), gitignoreContent);
+
+    // Create README.md
+    const readmeContent = `# ${path.basename(projectPath)}
+
+MCP-I proof verifier deployed on Cloudflare Workers with KV nonce caching.
+
+## Quick Start
+
+### 1. Install Dependencies
+
+\`\`\`bash
+${packageManager} install
+\`\`\`
+
+### 2. Create KV Namespace
+
+\`\`\`bash
+${packageManager === "npm" ? "npm run" : packageManager} kv:create
+\`\`\`
+
+Copy the \`id\` from the output and update \`wrangler.toml\`:
+
+\`\`\`toml
+[[kv_namespaces]]
+binding = "NONCE_CACHE"
+id = "your-kv-namespace-id-here"  # ← Update this
+\`\`\`
+
+### 3. Test Locally
+
+\`\`\`bash
+${packageManager === "npm" ? "npm run" : packageManager} dev
+\`\`\`
+
+Visit http://localhost:8787/health to verify it's running.
+
+### 4. Deploy to Cloudflare
+
+\`\`\`bash
+# Login to Cloudflare (first time only)
+npx wrangler login
+
+# Deploy to development
+${packageManager === "npm" ? "npm run" : packageManager} deploy
+
+# Deploy to production
+${packageManager === "npm" ? "npm run" : packageManager} deploy:production
+\`\`\`
+
+## API Endpoints
+
+### \`GET /health\`
+Health check endpoint.
+
+**Response:**
+\`\`\`json
+{
+  "status": "healthy",
+  "timestamp": "2024-10-09T12:00:00.000Z"
+}
+\`\`\`
+
+### \`POST /verify\`
+Verify MCP-I cryptographic proof.
+
+**Request:**
+\`\`\`json
+{
+  "proof": {
+    "agentDid": "did:web:example.com",
+    "timestamp": 1234567890,
+    "nonce": "abc123",
+    "signature": "...",
+    "publicKey": "..."
+  },
+  "requiredScopes": ["cart:add"]
+}
+\`\`\`
+
+**Response (Success):**
+\`\`\`json
+{
+  "verified": true,
+  "agentDid": "did:web:example.com",
+  "timestamp": "2024-10-09T12:00:00.000Z"
+}
+\`\`\`
+
+**Response (Failed):**
+\`\`\`json
+{
+  "verified": false,
+  "error": "Invalid signature"
+}
+\`\`\`
+
+## Configuration
+
+### Environment Variables (wrangler.toml)
+
+- \`KYA_API_URL\` - KYA API endpoint (default: https://knowthat.ai)
+- \`XMCP_I_TS_SKEW_SEC\` - Clock skew tolerance in seconds (default: 120)
+- \`XMCP_I_SESSION_TTL\` - Session timeout in seconds (default: 1800)
+
+### KV Namespace
+
+The Worker uses Cloudflare KV for distributed nonce caching to prevent replay attacks.
+
+Create separate namespaces for development and production:
+
+\`\`\`bash
+# Development
+${packageManager === "npm" ? "npm run" : packageManager} kv:create
+
+# Production (after deploying once)
+wrangler kv:namespace create NONCE_CACHE --env production
+\`\`\`
+
+## Testing
+
+Send a test request:
+
+\`\`\`bash
+curl -X POST https://your-worker.workers.dev/verify \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "proof": {
+      "agentDid": "did:web:example.com",
+      "timestamp": 1234567890,
+      "nonce": "test123",
+      "signature": "...",
+      "publicKey": "..."
+    }
+  }'
+\`\`\`
+
+## Learn More
+
+- [MCP-I Documentation](https://github.com/kya-os/xmcp-i)
+- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
+- [Cloudflare KV Docs](https://developers.cloudflare.com/kv/)
+`;
+    fs.writeFileSync(path.join(projectPath, "README.md"), readmeContent);
+
+    console.log(chalk.green("✅ Cloudflare Worker verifier structure created"));
+  } catch (error) {
+    console.error(chalk.red("Failed to set up Cloudflare Worker verifier:"), error);
+    throw error;
+  }
+}

package/src/helpers/fetch-mcpi-template.ts

@@ -0,0 +1,236 @@
+import { execSync } from "child_process";
+import fs from "fs-extra";
+import path from "path";
+import os from "os";
+import chalk from "chalk";
+import { generateIdentity } from "./generate-identity.js";
+
+interface ScaffoldTemplateOptions {
+  mcpiVersion?: string;
+  packageManager?: string;
+  skipIdentity?: boolean;
+}
+
+/**
+ * Scaffold MCP-I project using @kya-os/mcp-i package
+ * This creates a standalone MCP server with built-in identity features
+ */
+export async function fetchMCPITemplate(
+  projectPath: string,
+  options: ScaffoldTemplateOptions = {}
+): Promise<void> {
+  const {
+    mcpiVersion = "^1.3.2",
+    packageManager = "npm",
+    skipIdentity = false,
+  } = options;
+
+  try {
+    console.log(
+      chalk.blue(
+        `📦 Setting up MCP-I project with @kya-os/mcp-i@${mcpiVersion}...`
+      )
+    );
+
+    // Create package.json matching our working test-mcpi structure
+    const packageJson = {
+      name: path.basename(projectPath),
+      version: "0.1.0",
+      dependencies: {
+        "@kya-os/cli": "^1.2.7",
+        "@kya-os/mcp-i": mcpiVersion,
+        zod: "^3.24.4",
+      },
+      scripts: {
+        dev: "mcpi dev",
+        build: "mcpi build",
+        start: "mcpi start",
+        init: "mcpi init",
+        register: "mcpi register",
+        "keys:rotate": "mcpi rotate",
+        "identity:clean": "rm -rf .mcpi",
+        status: "mcpi status",
+      },
+      devDependencies: {
+        "@modelcontextprotocol/inspector": "^0.16.6",
+        "swc-loader": "^0.2.6",
+      },
+    };
+
+    // Write package.json
+    fs.ensureDirSync(projectPath);
+    fs.writeJsonSync(path.join(projectPath, "package.json"), packageJson, {
+      spaces: 2,
+    });
+
+    // Create basic MCP-I project structure
+    const srcDir = path.join(projectPath, "src");
+    const toolsDir = path.join(srcDir, "tools");
+
+    // Create required directories
+    fs.ensureDirSync(toolsDir);
+
+    // Optional directories (not created by default - users can add as needed)
+    // These are typically only needed for:
+    // - scenarios/: Demo/testing scenarios (like bouncer-demo)
+    // - lib/: Shared utilities (if project grows complex)
+    // - scripts/: Build/utility scripts (if needed)
+    // - docs/: Documentation (if maintaining separate docs)
+
+    // Create a basic greet tool (MCP-I default)
+    // CRITICAL: Import from @kya-os/mcp-i (not xmcp)
+    const greetToolContent = `import { z } from "zod";
+import { type InferSchema, type ToolMetadata } from "@kya-os/mcp-i";
+
+// Define the schema for tool parameters
+export const schema = {
+  name: z.string().describe("The name of the user to greet"),
+};
+
+// Define tool metadata
+export const metadata: ToolMetadata = {
+  name: "greet",
+  description: "Greet the user",
+};
+
+// Tool implementation
+export default async function greet({ name }: InferSchema<typeof schema>) {
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: \`Hello, \${name}!\`,
+      },
+    ],
+  };
+}
+`;
+
+    fs.writeFileSync(path.join(toolsDir, "greet.ts"), greetToolContent);
+
+    // IMPORTANT: DO NOT create tools/index.ts
+    // This would cause duplicate tool registration in webpack bundling
+
+    // Create xmcp.config.ts with identity features enabled (matching test-mcpi)
+    const configContent = `import type { XmcpConfig } from "@kya-os/mcp-i";
+
+const config: XmcpConfig = {
+  // Point to the tools directory
+  paths: {
+    tools: "./src/tools",
+  },
+
+  // Enable MCP-I identity features
+  identity: {
+    enabled: true,
+    environment: "development",
+    debug: true,
+  },
+
+  // Enable STDIO transport for Claude Desktop
+  stdio: true,
+};
+
+export default config;
+`;
+    fs.writeFileSync(path.join(projectPath, "xmcp.config.ts"), configContent);
+
+    // Create .gitignore
+    const gitignoreContent = `node_modules/
+dist/
+.env
+.env.local
+.mcpi/
+`;
+    fs.writeFileSync(path.join(projectPath, ".gitignore"), gitignoreContent);
+
+    // Create README.md with quick start instructions
+    const readmeContent = `# ${path.basename(projectPath)}
+
+MCP-I server with cryptographic identity built-in.
+
+## Getting Started
+
+1. Install dependencies:
+   \`\`\`bash
+   npm install
+   \`\`\`
+
+2. Initialize identity (generates cryptographic keys):
+   \`\`\`bash
+   npm run init
+   \`\`\`
+
+3. Start development server:
+   \`\`\`bash
+   npm run dev
+   \`\`\`
+
+## Scripts
+
+- \`npm run dev\` - Start development server with hot reload
+- \`npm run build\` - Build production bundle
+- \`npm run start\` - Start production server
+- \`npm run init\` - Initialize agent identity
+- \`npm run status\` - Check identity and server status
+- \`npm run keys:rotate\` - Rotate cryptographic keys
+
+## Project Structure
+
+\`\`\`
+├── src/
+│   └── tools/          # MCP tools
+│       └── greet.ts    # Example tool
+├── xmcp.config.ts      # MCP-I configuration
+└── .mcpi/              # Identity files (git-ignored)
+\`\`\`
+
+**Optional directories** (add as needed):
+- \`src/scenarios/\` - Demo/testing scenarios
+- \`src/lib/\` - Shared utilities
+- \`scripts/\` - Build/utility scripts
+- \`docs/\` - Documentation
+
+## Learn More
+
+- [MCP-I Documentation](https://github.com/modelcontextprotocol-identity/mcp-i)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+`;
+    fs.writeFileSync(path.join(projectPath, "README.md"), readmeContent);
+
+    console.log(chalk.green("✅ MCP-I project structure created"));
+
+    // Generate persistent identity for Node.js MCP-I server
+    if (!skipIdentity) {
+      console.log(chalk.cyan("🔐 Generating persistent identity..."));
+      try {
+        const identity = await generateIdentity();
+
+        // Create .mcpi directory
+        const mcpiDir = path.join(projectPath, ".mcpi");
+        fs.ensureDirSync(mcpiDir);
+
+        // Save identity to .mcpi/identity.json
+        const identityPath = path.join(mcpiDir, "identity.json");
+        fs.writeJsonSync(identityPath, identity, { spaces: 2 });
+
+        console.log(chalk.green("✅ Generated persistent identity"));
+        console.log(chalk.dim(`   DID: ${identity.did}`));
+        console.log(chalk.dim(`   Saved to: .mcpi/identity.json`));
+      } catch (error: any) {
+        console.log(
+          chalk.yellow("⚠️  Failed to generate identity:"),
+          error.message
+        );
+        console.log(
+          chalk.dim(
+            "   You can generate identity later by running: npm run init"
+          )
+        );
+      }
+    }
+  } catch (error) {
+    console.error(chalk.red("Failed to set up MCP-I project:"), error);
+    throw error;
+  }
+}