@kya-os/create-mcpi-app 1.3.5-canary.1 → 1.3.5-canary.11

package/dist/helpers/fetch-cloudflare-mcpi-template.js

@@ -6,7 +6,7 @@ import chalk from "chalk";
  * Uses McpAgent from agents/mcp for MCP protocol support
  */
 export async function fetchCloudflareMcpiTemplate(projectPath, options = {}) {
-    const { packageManager = "npm", projectName = path.basename(projectPath) } = options;
+    const { packageManager = "npm", projectName = path.basename(projectPath), apikey } = options;
     // Sanitize project name for class names
     const className = projectName
         .replace(/[^a-zA-Z0-9]/g, "")
@@ -23,16 +23,31 @@ export async function fetchCloudflareMcpiTemplate(projectPath, options = {}) {
                 deploy: "wrangler deploy",
                 dev: "wrangler dev",
                 start: "wrangler dev",
-                "kv:create": "npm run kv:create-nonce && npm run kv:create-proof",
-                "kv:create-nonce": `wrangler kv namespace create NONCE_CACHE`,
-                "kv:create-proof": `wrangler kv namespace create PROOF_ARCHIVE`,
-                "kv:list": "wrangler kv namespace list | grep -E '(NONCE|PROOF|MCPI)' || wrangler kv namespace list",
-                "kv:setup": "echo 'Run npm run kv:list to find existing namespaces, or npm run kv:create to create both, or use kv:create-nonce and kv:create-proof individually'",
+                "kv:create": "npm run kv:create-nonce && npm run kv:create-proof && npm run kv:create-identity && npm run kv:create-delegation && npm run kv:create-tool-protection",
+                "kv:create-nonce": `wrangler kv namespace create ${className.toUpperCase()}_NONCE_CACHE`,
+                "kv:create-proof": `wrangler kv namespace create ${className.toUpperCase()}_PROOF_ARCHIVE`,
+                "kv:create-identity": `wrangler kv namespace create ${className.toUpperCase()}_IDENTITY_STORAGE`,
+                "kv:create-delegation": `wrangler kv namespace create ${className.toUpperCase()}_DELEGATION_STORAGE`,
+                "kv:create-tool-protection": `wrangler kv namespace create ${className.toUpperCase()}_TOOL_PROTECTION_KV`,
+                "kv:list": "wrangler kv namespace list | grep -E '(NONCE|PROOF|IDENTITY|DELEGATION|TOOL_PROTECTION|MCPI)' || wrangler kv namespace list",
+                "kv:keys-nonce": `wrangler kv key list --binding=${className.toUpperCase()}_NONCE_CACHE`,
+                "kv:keys-proof": `wrangler kv key list --binding=${className.toUpperCase()}_PROOF_ARCHIVE`,
+                "kv:keys-identity": `wrangler kv key list --binding=${className.toUpperCase()}_IDENTITY_STORAGE`,
+                "kv:keys-delegation": `wrangler kv key list --binding=${className.toUpperCase()}_DELEGATION_STORAGE`,
+                "kv:keys-tool-protection": `wrangler kv key list --binding=${className.toUpperCase()}_TOOL_PROTECTION_KV`,
+                "kv:delete-nonce": `wrangler kv namespace delete --binding=${className.toUpperCase()}_NONCE_CACHE`,
+                "kv:delete-proof": `wrangler kv namespace delete --binding=${className.toUpperCase()}_PROOF_ARCHIVE`,
+                "kv:delete-identity": `wrangler kv namespace delete --binding=${className.toUpperCase()}_IDENTITY_STORAGE`,
+                "kv:delete-delegation": `wrangler kv namespace delete --binding=${className.toUpperCase()}_DELEGATION_STORAGE`,
+                "kv:delete-tool-protection": `wrangler kv namespace delete --binding=${className.toUpperCase()}_TOOL_PROTECTION_KV`,
+                "kv:delete": "npm run kv:delete-nonce && npm run kv:delete-proof && npm run kv:delete-identity && npm run kv:delete-delegation && npm run kv:delete-tool-protection",
+                "kv:reset": "npm run kv:delete && npm run kv:create",
+                "kv:setup": "echo 'KV Commands: kv:create (create all), kv:list (list all), kv:keys-* (view keys), kv:delete (delete all), kv:reset (delete+recreate)'",
                 "cf-typegen": "wrangler types",
                 "type-check": "tsc --noEmit",
             },
             dependencies: {
-                "@kya-os/mcp-i-cloudflare": "^1.1.1",
+                "@kya-os/mcp-i-cloudflare": "1.2.3-canary.8",
                 "@modelcontextprotocol/sdk": "^1.19.1",
                 "agents": "^0.2.8",
                 "hono": "^4.9.10",
@@ -53,6 +68,31 @@ export async function fetchCloudflareMcpiTemplate(projectPath, options = {}) {
         // Create greet tool
         const greetToolContent = `import { z } from "zod";
 
+/**
+ * Greet Tool - Example MCP tool with AgentShield integration
+ *
+ * This tool demonstrates proper scopeId configuration for tool auto-discovery.
+ *
+ * Configure the corresponding scope in mcpi-runtime-config.ts:
+ * \`\`\`typescript
+ * toolProtections: {
+ *   greet: {
+ *     requiresDelegation: false,
+ *     requiredScopes: ["greet:execute"],  // ← This becomes the scopeId in proofs
+ *   }
+ * }
+ * \`\`\`
+ *
+ * The scopeId format is "toolName:action":
+ * - Tool name: "greet" (extracted before the ":")
+ * - Action: "execute" (extracted after the ":")
+ * - Risk level: Auto-determined from action keyword (execute = high)
+ *
+ * Other scopeId examples:
+ * - "files:read" → Medium risk
+ * - "files:write" → High risk
+ * - "database:delete" → Critical risk
+ */
 export const greetTool = {
   name: "greet",
   description: "Greet a user by name",
@@ -72,13 +112,166 @@ export const greetTool = {
 };
 `;
         fs.writeFileSync(path.join(toolsDir, "greet.ts"), greetToolContent);
+        // Create mcpi-runtime-config.ts for AgentShield integration
+        const runtimeConfigContent = `import type { MCPIRuntimeConfig } from "@kya-os/mcp-i-cloudflare";
+${apikey ? 'import { CloudflareRuntime } from "@kya-os/mcp-i-cloudflare";  // Auto-enabled: Tool Protection Service' : '// import { CloudflareRuntime } from "@kya-os/mcp-i-cloudflare";  // Uncomment to enable Tool Protection Service'}
+
+/**
+ * Runtime configuration for MCP-I server
+ *
+ * This file configures runtime features like proof submission to AgentShield,
+ * delegation verification, and audit logging.
+ *
+ * Environment variables are automatically injected from wrangler.toml (Cloudflare)
+ * or .env (Node.js). Configure them there:
+ * - AGENTSHIELD_API_URL: AgentShield API base URL
+ * - AGENTSHIELD_API_KEY: Your AgentShield API key
+ * - AGENTSHIELD_PROJECT_ID: Your AgentShield project ID
+ * - MCPI_ENV: "development" or "production"
+ */
+export function getRuntimeConfig(): MCPIRuntimeConfig {
+  const env = process.env;
+
+  return {
+    // Identity configuration
+    identity: {
+      environment: (env.MCPI_ENV as "development" | "production") || "development",
+      devIdentityPath: ".mcpi/identity.json"
+    },
+
+    // Proof submission configuration
+    proofing: {
+      enabled: true,
+      batchQueue: {
+        destinations: [
+          {
+            type: "agentshield" as const,
+            apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+            apiKey: env.AGENTSHIELD_API_KEY || ""
+          }
+        ],
+        maxBatchSize: 10,
+        flushIntervalMs: 5000,
+        maxRetries: 3,
+        debug: env.MCPI_ENV === "development"
+      }
+    },
+
+    // Delegation verification (AgentShield API)
+    delegation: {
+      enabled: true,
+      enforceDelegations: true,  // ✅ NEW: Enable enforcement of delegation requirements
+      verifier: {
+        type: "agentshield-api",
+        agentshield: {
+          apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+          apiKey: env.AGENTSHIELD_API_KEY || ""
+        },
+        cacheTtl: 60000, // 1 minute cache
+        debug: env.MCPI_ENV === "development"
+      },
+      authorization: {
+        authorizationUrl: env.AUTHORIZATION_URL || \`\${env.AGENTSHIELD_API_URL}/authorize\`,
+        resumeTokenTtl: 600000, // 10 minutes
+        minReputationScore: 76
+      },
+      // ⚠️ DEPRECATED (if using dynamic tool protection):
+      // Tool protection rules - Configure scopes for auto-discovery in AgentShield
+      //
+      // NOTE: These are now managed via AgentShield dashboard and fetched dynamically
+      // when you enable the Tool Protection Service (see below). This fallback config
+      // is only used if:
+      // 1. Tool Protection Service is not configured, OR
+      // 2. AgentShield API is unavailable
+      toolProtections: {
+        // Example: Public tool with execution scope
+        greet: {
+          requiresDelegation: false,  // No delegation needed for low-risk tool
+          requiredScopes: ["greet:execute"]  // ✅ Enables tool discovery in AgentShield
+        }
+        // Add more tools as needed:
+        // High-risk tool requiring delegation:
+        // checkout: {
+        //   requiresDelegation: true,  // User must explicitly delegate
+        //   requiredScopes: ["checkout:execute"]  // Scope for tool discovery
+        // },
+        // delete_file: {
+        //   requiresDelegation: true,
+        //   requiredScopes: ["files:delete"]  // Action-based scope for better categorization
+        // }
+      }
+    },
+
+    // 🆕 Dynamic Tool Protection Service (Dashboard-Controlled)
+    //
+    // When AgentShield API key is configured, tool delegation requirements
+    // are fetched from the dashboard in real-time (5-minute cache).
+    //
+    // Benefits:
+    // - Toggle "Require Delegation" for any tool in dashboard - no code changes
+    // - Changes apply in real-time (5-minute cache via KV)
+    // - Automatic tool discovery from proof submissions
+    //
+    // Performance: 1 API call per 5 minutes, all other requests use KV cache
+    ${apikey ? `toolProtectionService: env.TOOL_PROTECTION_KV
+      ? CloudflareRuntime.createToolProtectionService(
+          env.TOOL_PROTECTION_KV,  // KV namespace from wrangler.toml
+          {
+            apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+            apiKey: env.AGENTSHIELD_API_KEY || "",
+            projectId: env.AGENTSHIELD_PROJECT_ID || "",
+            cacheTtl: 300000,  // 5 minutes (in milliseconds)
+            debug: env.MCPI_ENV === "development",
+            // Fallback to local config if API unavailable
+            fallbackConfig: {
+              toolProtections: {
+                greet: {
+                  requiresDelegation: false,
+                  requiredScopes: ["greet:execute"],
+                },
+              },
+            },
+          }
+        )
+      : undefined,` : `// toolProtectionService: env.TOOL_PROTECTION_KV
+    //   ? CloudflareRuntime.createToolProtectionService(
+    //       env.TOOL_PROTECTION_KV,
+    //       {
+    //         apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
+    //         apiKey: env.AGENTSHIELD_API_KEY || "",
+    //         projectId: env.AGENTSHIELD_PROJECT_ID || "",
+    //         cacheTtl: 300000,  // 5 minutes
+    //         debug: env.MCPI_ENV === "development",
+    //         fallbackConfig: {
+    //           toolProtections: {
+    //             greet: {
+    //               requiresDelegation: false,
+    //               requiredScopes: ["greet:execute"],
+    //             },
+    //           },
+    //         },
+    //       }
+    //     )
+    //   : undefined,`}
+
+    // Audit logging
+    audit: {
+      enabled: true
+    }
+  };
+}
+
+export default getRuntimeConfig();
+`;
+        fs.writeFileSync(path.join(srcDir, "mcpi-runtime-config.ts"), runtimeConfigContent);
         // Create main index.ts using McpAgent with MCP-I runtime
         const indexContent = `import { McpAgent } from "agents/mcp";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { createCloudflareRuntime, type CloudflareEnv, KVProofArchive } from "@kya-os/mcp-i-cloudflare";
+import { createCloudflareRuntime, type CloudflareEnv, KVProofArchive, type DetachedProof } from "@kya-os/mcp-i-cloudflare";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { greetTool } from "./tools/greet";
+import { getRuntimeConfig } from "./mcpi-runtime-config";
 
 export class ${pascalClassName}MCP extends McpAgent {
   server = new McpServer({
@@ -88,27 +281,136 @@ export class ${pascalClassName}MCP extends McpAgent {
 
   private mcpiRuntime?: any;
   private proofArchive?: KVProofArchive;
+  private agentShieldConfig?: { apiUrl: string; apiKey: string };
   private env: CloudflareEnv;
 
   constructor(state: DurableObjectState, env: CloudflareEnv) {
     super(state, env);
     this.env = env;
 
+    // Load runtime configuration for AgentShield integration
+    const runtimeConfig = getRuntimeConfig();
+
+    // Create CloudflareEnv adapter to map prefixed KV bindings to expected names
+    // This allows multiple agents to be deployed without KV namespace conflicts
+    const mappedEnv: CloudflareEnv = {
+      // Map prefixed bindings to standard names expected by createCloudflareRuntime
+      NONCE_CACHE: (env as any).${className.toUpperCase()}_NONCE_CACHE,
+      PROOF_ARCHIVE: (env as any).${className.toUpperCase()}_PROOF_ARCHIVE,
+      IDENTITY_STORAGE: (env as any).${className.toUpperCase()}_IDENTITY_STORAGE,
+      TOOL_PROTECTION_KV: (env as any).${className.toUpperCase()}_TOOL_PROTECTION_KV,
+      // Pass through environment variables unchanged
+      MCP_IDENTITY_PRIVATE_KEY: (env as any).MCP_IDENTITY_PRIVATE_KEY,
+      MCP_IDENTITY_PUBLIC_KEY: (env as any).MCP_IDENTITY_PUBLIC_KEY,
+      MCP_IDENTITY_AGENT_DID: (env as any).MCP_IDENTITY_AGENT_DID,
+    };
+
     // Initialize MCP-I runtime for cryptographic proofs and identity
     this.mcpiRuntime = createCloudflareRuntime({
-      env: env,
+      env: mappedEnv,
       audit: {
-        enabled: true,
-        logFunction: (record) => console.log('[MCP-I Audit]', record)
+        enabled: runtimeConfig.audit?.enabled ?? true,
+        logFunction: runtimeConfig.audit?.logFunction || ((record) => console.log('[MCP-I Audit]', record))
       }
     });
 
     // Initialize proof archive if PROOF_ARCHIVE KV is available
-    if (env.PROOF_ARCHIVE) {
-      this.proofArchive = new KVProofArchive(env.PROOF_ARCHIVE);
-      console.log('[MCP-I] Proof archive enabled - proofs will be stored in KV');
-    } else {
-      console.warn('[MCP-I] PROOF_ARCHIVE KV not configured - proofs will only be logged');
+    if (mappedEnv.PROOF_ARCHIVE) {
+      this.proofArchive = new KVProofArchive(mappedEnv.PROOF_ARCHIVE);
+      console.log('[MCP-I] Proof archive enabled');
+    }
+
+    // Load AgentShield config for proof submission
+    if (runtimeConfig.proofing?.enabled && runtimeConfig.proofing.batchQueue) {
+      const agentShieldDest = runtimeConfig.proofing.batchQueue.destinations?.find(
+        (dest) => dest.type === "agentshield" && dest.apiKey
+      );
+      if (agentShieldDest) {
+        this.agentShieldConfig = {
+          apiUrl: agentShieldDest.apiUrl,
+          apiKey: agentShieldDest.apiKey!
+        };
+        console.log('[MCP-I] AgentShield enabled:', agentShieldDest.apiUrl);
+      }
+    }
+  }
+
+  /**
+   * Submit proof to AgentShield API
+   * Uses the proof.jws directly (full JWS format from CloudflareRuntime)
+   *
+   * Also submits optional context for AgentShield dashboard integration.
+   * Context provides plaintext tool/args data while proof provides cryptographic verification.
+   */
+  private async submitProofToAgentShield(
+    proof: DetachedProof,
+    session: any,
+    toolName: string,
+    args: any,
+    result: any
+  ): Promise<void> {
+    if (!this.agentShieldConfig || !proof.jws || !proof.meta) return;
+
+    const { apiUrl, apiKey } = this.agentShieldConfig;
+
+    // Get tool call context from runtime (if available)
+    const toolCallContext = this.mcpiRuntime?.getLastToolCallContext();
+
+    // Proof already has correct format from CloudflareRuntime
+    // Adding optional context for AgentShield dashboard (Option A architecture)
+    const requestBody = {
+      session_id: session.id,
+      delegation_id: null,
+      proofs: [{
+        jws: proof.jws,  // Already in full JWS format
+        meta: proof.meta  // Already has all required fields
+      }],
+      // ✅ NEW: Optional context for dashboard integration
+      context: {
+        toolCalls: toolCallContext ? [toolCallContext] : [{
+          // Fallback if context not available from runtime
+          tool: toolName,
+          args: args,
+          result: result,
+          scopeId: proof.meta.scopeId || \`\${toolName}:execute\`
+        }],
+        // ✅ NEW: MCP server URL for tool discovery (optional, only needed once)
+        mcpServerUrl: env.MCP_SERVER_URL
+      }
+    };
+
+    console.log('[AgentShield] Submitting proof with context:', {
+      did: proof.meta.did,
+      sessionId: proof.meta.sessionId,
+      jwsFormat: proof.jws.split('.').length === 3 ? 'valid (3 parts)' : 'invalid',
+      contextTool: requestBody.context.toolCalls[0]?.tool,
+      contextScopeId: requestBody.context.toolCalls[0]?.scopeId,
+      mcpServerUrl: requestBody.context.mcpServerUrl || 'not-set'
+    });
+
+    const response = await fetch(\`\${apiUrl}/api/v1/bouncer/proofs\`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': \`Bearer \${apiKey}\`
+      },
+      body: JSON.stringify(requestBody)
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      console.error('[AgentShield] Submission failed:', response.status, errorText);
+      throw new Error(\`AgentShield error: \${response.status}\`);
+    }
+
+    const responseData = await response.json() as any;
+    console.log('[AgentShield] Response:', responseData);
+
+    if (responseData.accepted) {
+      console.log('[AgentShield] ✅ Proofs accepted:', responseData.accepted);
+    }
+    if (responseData.rejected) {
+      console.log('[AgentShield] ❌ Proofs rejected:', responseData.rejected);
     }
   }
 
@@ -131,7 +433,7 @@ export class ${pascalClassName}MCP extends McpAgent {
             const timestamp = Date.now();
             const session = {
               id: \`ephemeral-\${timestamp}-\${Math.random().toString(36).substring(2, 10)}\`,
-              audience: 'mcp-client',
+              audience: 'https://kya.vouched.id',  // CRITICAL: Must match AgentShield domain
               agentDid: (await this.mcpiRuntime.getIdentity()).did,
               createdAt: timestamp,
               expiresAt: timestamp + (30 * 60 * 1000) // 30 minutes
@@ -145,41 +447,52 @@ export class ${pascalClassName}MCP extends McpAgent {
               session
             );
 
-            // Get the proof that was just generated
-            const proof = this.mcpiRuntime.getLastProof();
+            // Get proof in DetachedProof format
+            const proof = this.mcpiRuntime.getLastProof() as DetachedProof;
 
-            if (proof) {
+            if (proof && proof.jws && proof.meta) {
+              // Log proof details (using DetachedProof format)
               console.log('[MCP-I Proof]', {
                 tool: greetTool.name,
-                did: proof.did,
-                timestamp: proof.timestamp,
-                signature: proof.signature.substring(0, 20) + '...'
+                did: proof.meta.did,
+                timestamp: proof.meta.ts,
+                jws: proof.jws.substring(0, 50) + '...',
+                jwsValid: proof.jws.split('.').length === 3
               });
 
-              // Store proof in KV archive (if configured)
+              // Store in KV archive
               if (this.proofArchive) {
                 try {
                   await this.proofArchive.store(proof, {
-                    toolName: greetTool.name,
-                    sessionId: session.id
+                    toolName: greetTool.name
                   });
-                  console.log('[MCP-I] Proof stored in PROOF_ARCHIVE KV');
+                  console.log('[MCP-I] Proof stored in archive');
                 } catch (archiveError) {
-                  console.error('[MCP-I] Failed to store proof in archive:', archiveError);
-                  // Continue even if archiving fails
+                  console.error('[MCP-I] Archive error:', archiveError);
+                }
+              }
+
+              // Submit to AgentShield with context
+              if (this.agentShieldConfig) {
+                try {
+                  await this.submitProofToAgentShield(proof, session, greetTool.name, args, result);
+                } catch (err: any) {
+                  console.error('[MCP-I] AgentShield failed:', err.message);
                 }
               }
 
-              // Attach proof to result for MCP Inspector and clients
-              // Following MCP-I pattern: { content: [...], _meta: { proof: {...} } }
+              // Attach proof to result for MCP Inspector
               if (result && typeof result === 'object') {
                 (result as any)._meta = {
                   proof: {
-                    did: proof.did,
-                    signature: proof.signature,
-                    timestamp: proof.timestamp,
-                    nonce: proof.nonce,
-                    algorithm: proof.algorithm
+                    jws: proof.jws,
+                    did: proof.meta.did,
+                    kid: proof.meta.kid,
+                    timestamp: proof.meta.ts,
+                    nonce: proof.meta.nonce,
+                    sessionId: proof.meta.sessionId,
+                    requestHash: proof.meta.requestHash,
+                    responseHash: proof.meta.responseHash
                   }
                 };
               }
@@ -221,7 +534,7 @@ app.mount("/mcp", ${pascalClassName}MCP.serve("/mcp").fetch, { replaceRequest: f
 export default app;
 `;
         fs.writeFileSync(path.join(srcDir, "index.ts"), indexContent);
-        // Create wrangler.toml
+        // Create wrangler.toml with optional API key
         const wranglerContent = `#:schema node_modules/wrangler/config-schema.json
 name = "${projectName}"
 main = "src/index.ts"
@@ -246,8 +559,8 @@ new_sqlite_classes = ["${pascalClassName}MCP"]
 #
 # Then replace the id below with the namespace ID from the output
 [[kv_namespaces]]
-binding = "NONCE_CACHE"  # Binding name must match runtime expectation
-id = "your-nonce-kv-namespace-id"  # Replace with actual namespace ID
+binding = "${className.toUpperCase()}_NONCE_CACHE"
+id = "your_nonce_kv_namespace_id"  # Replace with actual namespace ID
 
 # KV Namespace for proof archive (RECOMMENDED for auditability)
 #
@@ -259,12 +572,67 @@ id = "your-nonce-kv-namespace-id"  # Replace with actual namespace ID
 #
 # Note: Comment out if you don't need proof archiving
 [[kv_namespaces]]
-binding = "PROOF_ARCHIVE"  # Binding name must match runtime expectation
-id = "your-proof-kv-namespace-id"  # Replace with actual namespace ID
+binding = "${className.toUpperCase()}_PROOF_ARCHIVE"
+id = "your_proof_kv_namespace_id"  # Replace with actual namespace ID
+
+# KV Namespace for identity storage (RECOMMENDED for persistent agent identity)
+#
+# Stores the agent's cryptographic identity (DID, keys) in KV
+# Ensures consistent identity across Worker restarts and deployments
+#
+# Run: npm run kv:create-identity  (creates IDENTITY_STORAGE namespace)
+# Then replace the id below with the namespace ID from the output
+#
+[[kv_namespaces]]
+binding = "${className.toUpperCase()}_IDENTITY_STORAGE"
+id = "your_identity_kv_namespace_id"  # Replace with actual namespace ID
+
+# KV Namespace for delegation storage (REQUIRED for OAuth/delegation flows)
+#
+# Stores active delegations from users to agents
+# Enables OAuth consent flows and scope-based authorization
+#
+# Run: npm run kv:create-delegation  (creates DELEGATION_STORAGE namespace)
+# Then replace the id below with the namespace ID from the output
+#
+[[kv_namespaces]]
+binding = "${className.toUpperCase()}_DELEGATION_STORAGE"
+id = "your_delegation_kv_namespace_id"  # Replace with actual namespace ID
+
+# KV Namespace for tool protection config (${apikey ? 'ENABLED' : 'OPTIONAL'} for dashboard-controlled delegation)
+#
+# 🆕 Enables dynamic tool protection configuration from AgentShield dashboard
+# Caches which tools require user delegation based on dashboard toggle switches
+#
+# Benefits:
+# - Control tool permissions from AgentShield dashboard without code changes
+# - Update delegation requirements in real-time (5-minute cache)
+# - No redeployments needed to change tool permissions
+#
+# Setup:
+# 1. Run: npm run kv:create-tool-protection
+# 2. Copy the namespace ID from output
+# 3. Replace "your_tool_protection_kv_id" below with the actual ID
+# 4. Deploy and toggle delegation in AgentShield dashboard
+#
+${apikey ? '' : '# '}[[kv_namespaces]]
+${apikey ? '' : '# '}binding = "${className.toUpperCase()}_TOOL_PROTECTION_KV"
+${apikey ? '' : '# '}id = "your_tool_protection_kv_id"  # Replace with actual namespace ID
 
 [vars]
 XMCP_I_TS_SKEW_SEC = "120"
 XMCP_I_SESSION_TTL = "1800"
+
+# AgentShield Integration (https://kya.vouched.id)
+# ${apikey ? 'Configure' : 'Uncomment and configure'} these variables to enable proof submission to AgentShield
+AGENTSHIELD_API_URL = "https://kya.vouched.id"
+${apikey ? `AGENTSHIELD_API_KEY = "${apikey}"  # Provided via --apikey flag` : '# AGENTSHIELD_API_KEY = "sk_your_api_key_here"  # Get from https://kya.vouched.id/dashboard'}
+${apikey ? 'AGENTSHIELD_PROJECT_ID = "your-project-id"  # Replace with your project ID from dashboard' : '# AGENTSHIELD_PROJECT_ID = "your-project-id"  # Get from https://kya.vouched.id/dashboard'}
+MCPI_ENV = "development"
+
+# Optional: MCP Server URL for tool discovery
+# Uncomment to explicitly set your MCP server URL (auto-detected if not set)
+# MCP_SERVER_URL = "https://your-worker.workers.dev/mcp"
 `;
         fs.writeFileSync(path.join(projectPath, "wrangler.toml"), wranglerContent);
         // Create tsconfig.json
@@ -319,37 +687,49 @@ ${packageManager} install
 
 ### 2. Create KV Namespaces
 
-#### Create Nonce Cache (Required)
+#### Create All KV Namespaces (Recommended)
 
 \`\`\`bash
-${packageManager === "npm" ? "npm run" : packageManager} kv:create-nonce
+${packageManager === "npm" ? "npm run" : packageManager} kv:create
 \`\`\`
 
-Copy the \`id\` from the output and update \`wrangler.toml\`:
+This creates all 5 KV namespaces at once:
+- \`NONCE_CACHE\` - Replay attack prevention (Required)
+- \`PROOF_ARCHIVE\` - Cryptographic proof storage (Recommended)
+- \`IDENTITY_STORAGE\` - Agent identity persistence (Recommended)
+- \`DELEGATION_STORAGE\` - OAuth delegation storage (Required for delegation)
+- \`TOOL_PROTECTION_KV\` - Dashboard-controlled permissions (Optional)
+
+Copy the namespace IDs from the output and update each one in \`wrangler.toml\`:
 
 \`\`\`toml
 [[kv_namespaces]]
 binding = "NONCE_CACHE"
-id = "your-nonce-kv-id-here"  # ← Update this
-\`\`\`
-
-#### Create Proof Archive (Recommended)
+id = "your_nonce_kv_id_here"  # ← Update this
 
-\`\`\`bash
-${packageManager === "npm" ? "npm run" : packageManager} kv:create-proof
-\`\`\`
+[[kv_namespaces]]
+binding = "PROOF_ARCHIVE"
+id = "your_proof_kv_id_here"  # ← Update this
 
-This runs: \`wrangler kv namespace create PROOF_ARCHIVE\`
+[[kv_namespaces]]
+binding = "IDENTITY_STORAGE"
+id = "your_identity_kv_id_here"  # ← Update this
 
-Copy the \`id\` from the output and update \`wrangler.toml\`:
+[[kv_namespaces]]
+binding = "DELEGATION_STORAGE"
+id = "your_delegation_kv_id_here"  # ← Update this
 
-\`\`\`toml
 [[kv_namespaces]]
-binding = "PROOF_ARCHIVE"
-id = "your-proof-kv-id-here"  # ← Update this
+binding = "TOOL_PROTECTION_KV"
+id = "your_tool_protection_kv_id_here"  # ← Update this
 \`\`\`
 
-**Note:** The PROOF_ARCHIVE stores cryptographic proofs for auditability. If you don't need proof archiving, you can comment out this namespace in \`wrangler.toml\`.
+**Note:** You can also create namespaces individually:
+- \`${packageManager === "npm" ? "npm run" : packageManager} kv:create-nonce\` - Create nonce cache only
+- \`${packageManager === "npm" ? "npm run" : packageManager} kv:create-proof\` - Create proof archive only
+- \`${packageManager === "npm" ? "npm run" : packageManager} kv:create-identity\` - Create identity storage only
+- \`${packageManager === "npm" ? "npm run" : packageManager} kv:create-delegation\` - Create delegation storage only
+- \`${packageManager === "npm" ? "npm run" : packageManager} kv:create-tool-protection\` - Create tool protection cache only
 
 ### 3. Test Locally
 
@@ -444,10 +824,10 @@ If you configured the \`PROOF_ARCHIVE\` KV namespace, proofs are also stored for
 
 \`\`\`bash
 # List all proofs
-wrangler kv:key list --namespace-id=your-proof-kv-id
+wrangler kv:key list --namespace-id=your_proof_kv_id
 
 # View a specific proof
-wrangler kv:key get "proof_1234567890_abcd" --namespace-id=your-proof-kv-id
+wrangler kv:key get "proof_1234567890_abcd" --namespace-id=your_proof_kv_id
 \`\`\`
 
 ## Identity Management
@@ -462,6 +842,105 @@ The identity includes:
 - \`publicKey\`: Ed25519 public key for signature verification
 - \`privateKey\`: Ed25519 private key (secured in Durable Object state)
 
+## AgentShield Integration
+
+This project is configured to send cryptographic proofs to AgentShield for audit trails and compliance monitoring.
+
+### Setup
+
+1. **Get your AgentShield API key**:
+   - Sign up at https://kya.vouched.id
+   - Create a project
+   - Copy your API key from the dashboard
+
+2. **Update \`wrangler.toml\`**:
+   \`\`\`toml
+   [vars]
+   AGENTSHIELD_API_URL = "https://kya.vouched.id"
+   AGENTSHIELD_API_KEY = "sk_your_actual_key_here"  # ← Replace this
+   AGENTSHIELD_PROJECT_ID = "your-project-id"       # ← Replace this
+   MCPI_ENV = "development"
+   \`\`\`
+
+3. **Test proof submission**:
+   \`\`\`bash
+   ${packageManager === "npm" ? "npm run" : packageManager} dev
+   \`\`\`
+
+   Call a tool and check the logs:
+   \`\`\`
+   [AgentShield] Submitting proof: { did: 'did:web:...', sessionId: '...', jwsFormat: 'valid (3 parts)' }
+   [AgentShield] ✅ Proofs accepted: 1
+   \`\`\`
+
+4. **View proofs in dashboard**:
+   - Go to https://kya.vouched.id/dashboard
+   - Select your project
+   - Click "Interactions" tab
+   - See your proofs in real-time
+
+### Configuration
+
+The AgentShield integration is configured in \`src/mcpi-runtime-config.ts\`. You can customize:
+- Proof batch size (\`maxBatchSize\`)
+- Flush interval (\`flushIntervalMs\`)
+- Retry policy (\`maxRetries\`)
+- Tool protection rules (\`toolProtections\`)
+
+### Dashboard-Controlled Tool Protection (Advanced)
+
+🆕 **NEW**: Control which tools require user delegation directly from the AgentShield dashboard - no code changes needed!
+
+Instead of hardcoding \`requiresDelegation\` in your config, enable dynamic tool protection:
+
+1. **Create Tool Protection KV namespace**:
+   \`\`\`bash
+   ${packageManager === "npm" ? "npm run" : packageManager} kv:create-tool-protection
+   \`\`\`
+
+2. **Uncomment TOOL_PROTECTION_KV in \`wrangler.toml\`**:
+   \`\`\`toml
+   [[kv_namespaces]]
+   binding = "TOOL_PROTECTION_KV"
+   id = "your_tool_protection_kv_id"  # ← Add the ID from step 1
+   \`\`\`
+
+3. **Enable Tool Protection Service in \`src/mcpi-runtime-config.ts\`**:
+   - Uncomment the import: \`import { CloudflareRuntime } from "@kya-os/mcp-i-cloudflare";\`
+   - Uncomment the \`toolProtectionService\` configuration block
+
+4. **Deploy and test**:
+   \`\`\`bash
+   ${packageManager === "npm" ? "npm run" : packageManager} deploy
+   \`\`\`
+
+5. **Control delegation from dashboard**:
+   - Go to https://kya.vouched.id/dashboard
+   - Select your project → "Tools" tab
+   - Toggle "Require Delegation" for any tool
+   - Changes apply in real-time (5-minute cache)
+
+**Benefits:**
+- Update tool permissions without redeploying
+- Test delegation flows instantly
+- Different requirements per environment (dev vs prod)
+- Automatic tool discovery from proof submissions
+
+**Note:** The first time a tool is called, it auto-discovers in the dashboard. The \`requiresDelegation\` toggle will appear after the first proof is submitted.
+
+### Disable AgentShield (Optional)
+
+If you don't want to use AgentShield, edit \`src/mcpi-runtime-config.ts\`:
+
+\`\`\`typescript
+proofing: {
+  enabled: false,  // Disable proof submission
+  // ...
+}
+\`\`\`
+
+Or simply don't configure the \`AGENTSHIELD_API_KEY\` environment variable.
+
 ## References
 
 - [Cloudflare Agents MCP](https://developers.cloudflare.com/agents/model-context-protocol/)
@@ -470,6 +949,28 @@ The identity includes:
 `;
         fs.writeFileSync(path.join(projectPath, "README.md"), readmeContent);
         console.log(chalk.green("✅ Cloudflare Worker MCP server created"));
+        console.log();
+        if (apikey) {
+            console.log(chalk.green("🔑 AgentShield API key configured in wrangler.toml"));
+            console.log(chalk.dim("   Your API key has been added to the [vars] section"));
+            console.log(chalk.dim("   Remember to add your AGENTSHIELD_PROJECT_ID before deployment"));
+            console.log();
+        }
+        else {
+            console.log(chalk.yellow("⚠️  No AgentShield API key provided"));
+            console.log(chalk.dim("   Add your API key to wrangler.toml [vars] section before deployment"));
+            console.log(chalk.dim("   Get your key at: https://kya.vouched.id/dashboard"));
+            console.log();
+        }
+        console.log(chalk.bold("📦 All KV Namespaces Configured"));
+        console.log(chalk.dim("   - NONCE_CACHE: Replay attack prevention"));
+        console.log(chalk.dim("   - PROOF_ARCHIVE: Cryptographic proof storage"));
+        console.log(chalk.dim("   - IDENTITY_STORAGE: Agent identity persistence"));
+        console.log(chalk.dim("   - DELEGATION_STORAGE: OAuth delegation storage"));
+        console.log(chalk.dim("   - TOOL_PROTECTION_KV: Dashboard-controlled permissions"));
+        console.log();
+        console.log(chalk.cyan("   Run 'npm run kv:create' to create all namespaces"));
+        console.log();
     }
     catch (error) {
         console.error(chalk.red("Failed to set up Cloudflare Worker MCP server:"), error);