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

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

@@ -7,7 +7,7 @@ import { generateIdentity } from "./generate-identity.js";
  * Uses McpAgent from agents/mcp for MCP protocol support
  */
 export async function fetchCloudflareMcpiTemplate(projectPath, options = {}) {
-    const { packageManager = "npm", projectName = path.basename(projectPath), apikey, skipIdentity = false, } = options;
+    const { packageManager = "npm", projectName = path.basename(projectPath), apikey, projectId, skipIdentity = false, } = options;
     // Sanitize project name for class names
     const className = projectName
         .replace(/[^a-zA-Z0-9]/g, "")
@@ -518,7 +518,7 @@ describe('Delegation Management', () => {
  */
 describe('DO Multi-Instance Routing', () => {
 
-  function getDoInstanceId(request: Request, env: any): string {
+  function getDoInstanceId(request: Request, env: { DO_ROUTING_STRATEGY?: string; DO_SHARD_COUNT?: string }): string {
     const strategy = env.DO_ROUTING_STRATEGY || 'session';
     const headers = request.headers;
 
@@ -602,7 +602,7 @@ describe('DO Multi-Instance Routing', () => {
  */
 describe('Security Configuration', () => {
 
-  function getCorsOrigin(requestOrigin: string | null, env: any): string | null {
+  function getCorsOrigin(requestOrigin: string | null, env: { ALLOWED_ORIGINS?: string; MCPI_ENV?: string }): string | null {
     const allowedOrigins = env.ALLOWED_ORIGINS?.split(',').map((o: string) => o.trim()) || [
       'https://claude.ai',
       'https://app.anthropic.com'
@@ -738,8 +738,12 @@ 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'}
+        const runtimeConfigContent = `import type { MCPIConfig } from '@kya-os/contracts/config';
+import type { CloudflareRuntimeConfig } from '@kya-os/mcp-i-cloudflare/config';
+import type { CloudflareEnv } from '@kya-os/mcp-i-cloudflare';
+import { buildBaseConfig } from '@kya-os/create-mcpi-app/config-builder';
+// Always import CloudflareRuntime for tool protection service creation
+import { CloudflareRuntime } from "@kya-os/mcp-i-cloudflare";
 
 /**
  * Runtime configuration for MCP-I server
@@ -755,150 +759,112 @@ ${apikey ? 'import { CloudflareRuntime } from "@kya-os/mcp-i-cloudflare";  // Au
  *
  * Note: The service fetches tool protection config by agent DID automatically.
  * No project ID configuration needed!
+ *
+ * This config uses the unified MCPIConfig architecture, ensuring the same
+ * base configuration shape across all platforms (Cloudflare, Node.js, Vercel).
  */
-export function getRuntimeConfig(env: any): MCPIRuntimeConfig {
-  // Accept env parameter to work in both Node.js (process.env) and Cloudflare Workers (worker env)
+export function getRuntimeConfig(env: CloudflareEnv): CloudflareRuntimeConfig {
+  // Build base config that works across all platforms
+  const baseConfig = buildBaseConfig(env);
 
+  // Extend with Cloudflare-specific properties
   return {
+    ...baseConfig,
     // Identity configuration
     identity: {
-      environment: (env.MCPI_ENV as "development" | "production") || "development",
-      devIdentityPath: ".mcpi/identity.json"
+      ...baseConfig.identity,
+      enabled: true,
+      environment: (env.ENVIRONMENT || env.MCPI_ENV || 'development') as 'development' | 'production'
     },
-
-    // Proof submission configuration
+    // Proofing configuration
     proofing: {
       enabled: true,
       batchQueue: {
         destinations: [
           {
             type: "agentshield" as const,
-            apiUrl: env.AGENTSHIELD_API_URL || "https://kya.vouched.id",
-            apiKey: env.AGENTSHIELD_API_KEY || ""
+            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"
+        debug: (env.ENVIRONMENT || env.MCPI_ENV || 'development') === 'development'
       }
     },
-
-    // Delegation verification (AgentShield API)
+    // Delegation configuration
     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
+      ...baseConfig.delegation
+    },
+    // Audit configuration
+    audit: {
+      ...baseConfig.audit
+    },
+    // Cloudflare Workers-specific configuration
+    workers: {
+      cpuMs: 50,
+      memoryMb: 128
+    },
+    // KV namespace bindings
+    kv: env.TOOL_PROTECTION_KV ? [{
+      name: 'TOOL_PROTECTION_KV',
+      purpose: 'cache' as const
+    }] : [],
+    // Environment variable bindings
+    vars: {
+      ENVIRONMENT: env.ENVIRONMENT || env.MCPI_ENV || 'development',
+      AGENTSHIELD_API_KEY: env.AGENTSHIELD_API_KEY
+    },
+    // Tool protection service (Cloudflare-specific)
+    toolProtection: env.TOOL_PROTECTION_KV && env.AGENTSHIELD_API_KEY ? {
+      source: 'agentshield' as const,
+      agentShield: {
+        apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+        apiKey: env.AGENTSHIELD_API_KEY,
+        projectId: env.AGENTSHIELD_PROJECT_ID,
+        cacheTtl: 300000 // 5 minutes
       },
-      // ⚠️ 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
+      fallback: {
         greet: {
-          requiresDelegation: false,  // No delegation needed for low-risk tool
-          requiredScopes: ["greet:execute"]  // ✅ Enables tool discovery in AgentShield
+          requiresDelegation: false,
+          requiredScopes: ['greet:execute']
         }
-        // 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,  // Optional: Use projectId endpoint (preferred) if available
-            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,  // Optional: Use projectId endpoint (preferred) if available
-    //         cacheTtl: 300000,  // 5 minutes
-    //         debug: env.MCPI_ENV === "development",
-    //         fallbackConfig: {
-    //           toolProtections: {
-    //             greet: {
-    //               requiresDelegation: false,
-    //               requiredScopes: ["greet:execute"],
-    //             },
-    //           },
-    //         },
-    //       }
-    //     )
-    //   : undefined,`}
-
-    // Audit logging
-    audit: {
-      enabled: true
-    }
-  };
+    } : undefined
+  } as CloudflareRuntimeConfig;
 }
 `;
         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, type DetachedProof, createOAuthCallbackHandler } from "@kya-os/mcp-i-cloudflare";
+import { createCloudflareRuntime, type CloudflareEnv, KVProofArchive, type DetachedProof, createOAuthCallbackHandler, CloudflareRuntime } from "@kya-os/mcp-i-cloudflare";
+import { DelegationRequiredError } from "@kya-os/mcp-i-core";
+import type { ToolProtectionService } from "@kya-os/mcp-i-core";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { greetTool } from "./tools/greet";
 import { getRuntimeConfig } from "./mcpi-runtime-config";
+import type { CloudflareRuntimeConfig } from "@kya-os/mcp-i-cloudflare/config";
+
+/**
+ * Extended CloudflareEnv with prefixed KV bindings for multi-agent deployments
+ * This allows multiple agents to share the same Cloudflare account without conflicts
+ */
+interface PrefixedCloudflareEnv extends CloudflareEnv {
+  // Prefixed KV bindings (e.g., MYAGENT_NONCE_CACHE, MYAGENT_PROOF_ARCHIVE)
+  [key: string]: KVNamespace | string | DurableObjectState | undefined;
+  // Optional routing configuration
+  DO_ROUTING_STRATEGY?: string;
+  DO_SHARD_COUNT?: string;
+  // Prefixed KV namespaces (dynamically accessed)
+  ${className.toUpperCase()}_NONCE_CACHE?: KVNamespace;
+  ${className.toUpperCase()}_PROOF_ARCHIVE?: KVNamespace;
+  ${className.toUpperCase()}_IDENTITY_STORAGE?: KVNamespace;
+  ${className.toUpperCase()}_DELEGATION_STORAGE?: KVNamespace;
+  ${className.toUpperCase()}_TOOL_PROTECTION_KV?: KVNamespace;
+}
 
 export class ${pascalClassName}MCP extends McpAgent {
   server = new McpServer({
@@ -906,13 +872,13 @@ export class ${pascalClassName}MCP extends McpAgent {
     version: "1.0.0"
   });
 
-  private mcpiRuntime?: any;
+  private mcpiRuntime?: ReturnType<typeof createCloudflareRuntime>;
   private proofArchive?: KVProofArchive;
   private agentShieldConfig?: { apiUrl: string; apiKey: string };
-  private env: CloudflareEnv;
+  private env: PrefixedCloudflareEnv;
   private mcpServerUrl?: string;
 
-  constructor(state: DurableObjectState, env: CloudflareEnv) {
+  constructor(state: DurableObjectState, env: PrefixedCloudflareEnv) {
     super(state, env);
     this.env = env;
 
@@ -920,29 +886,29 @@ export class ${pascalClassName}MCP extends McpAgent {
     // 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,
-      DELEGATION_STORAGE: (env as any).${className.toUpperCase()}_DELEGATION_STORAGE,
-      TOOL_PROTECTION_KV: (env as any).${className.toUpperCase()}_TOOL_PROTECTION_KV,
+      NONCE_CACHE: env.${className.toUpperCase()}_NONCE_CACHE,
+      PROOF_ARCHIVE: env.${className.toUpperCase()}_PROOF_ARCHIVE,
+      IDENTITY_STORAGE: env.${className.toUpperCase()}_IDENTITY_STORAGE,
+      DELEGATION_STORAGE: env.${className.toUpperCase()}_DELEGATION_STORAGE,
+      TOOL_PROTECTION_KV: env.${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,
+      MCP_IDENTITY_PRIVATE_KEY: env.MCP_IDENTITY_PRIVATE_KEY,
+      MCP_IDENTITY_PUBLIC_KEY: env.MCP_IDENTITY_PUBLIC_KEY,
+      MCP_IDENTITY_AGENT_DID: env.MCP_IDENTITY_AGENT_DID,
       // Pass through other env vars for runtime config
-      AGENTSHIELD_API_URL: (env as any).AGENTSHIELD_API_URL,
-      AGENTSHIELD_API_KEY: (env as any).AGENTSHIELD_API_KEY,
-      AGENTSHIELD_PROJECT_ID: (env as any).AGENTSHIELD_PROJECT_ID,
-      MCPI_ENV: (env as any).MCPI_ENV,
-      MCP_SERVER_URL: (env as any).MCP_SERVER_URL,
+      AGENTSHIELD_API_URL: env.AGENTSHIELD_API_URL,
+      AGENTSHIELD_API_KEY: env.AGENTSHIELD_API_KEY,
+      AGENTSHIELD_PROJECT_ID: env.AGENTSHIELD_PROJECT_ID,
+      MCPI_ENV: env.MCPI_ENV,
+      MCP_SERVER_URL: env.MCP_SERVER_URL,
       // Pass Durable Object state for identity persistence
       // NOTE: Without this, identity will be ephemeral (new DID every call)!
-      // TODO: Implement KV-based identity provider for shared identity across DO instances
+      // Note: createCloudflareRuntime will automatically use KVIdentityProvider if IDENTITY_STORAGE KV is available
       _durableObjectState: state,
     };
 
     // Store MCP server URL for proof submission context
-    this.mcpServerUrl = (env as any).MCP_SERVER_URL;
+    this.mcpServerUrl = env.MCP_SERVER_URL;
     if (this.mcpServerUrl) {
       console.log('[MCP-I] MCP Server URL configured:', this.mcpServerUrl);
     } else {
@@ -953,15 +919,44 @@ export class ${pascalClassName}MCP extends McpAgent {
     // Pass mappedEnv so it can access KV bindings with standard names
     const runtimeConfig = getRuntimeConfig(mappedEnv);
 
+    // ✅ Create tool protection service helper function
+    // Always import CloudflareRuntime but conditionally instantiate
+    function createToolProtectionService(env: CloudflareEnv, runtimeConfig: CloudflareRuntimeConfig): ToolProtectionService | undefined {
+      if (!runtimeConfig.toolProtection) {
+        return undefined;
+      }
+
+      if (!env.TOOL_PROTECTION_KV || !env.AGENTSHIELD_API_KEY) {
+        console.log('[MCP-I] Tool protection disabled - configure TOOL_PROTECTION_KV and AGENTSHIELD_API_KEY to enable');
+        return undefined;
+      }
+
+      return CloudflareRuntime.createToolProtectionService(
+        env.TOOL_PROTECTION_KV,
+        {
+          apiUrl: runtimeConfig.toolProtection.agentShield?.apiUrl || env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+          apiKey: env.AGENTSHIELD_API_KEY,
+          projectId: runtimeConfig.toolProtection.agentShield?.projectId || env.AGENTSHIELD_PROJECT_ID,
+          cacheTtl: runtimeConfig.toolProtection.agentShield?.cacheTtl || 300000,
+          debug: runtimeConfig.environment === 'development',
+          fallbackConfig: runtimeConfig.toolProtection.fallback
+        }
+      );
+    }
+
+    // Create tool protection service if configured
+    // Note: createCloudflareRuntime will automatically use KVIdentityProvider if IDENTITY_STORAGE KV is available
+    const toolProtectionService = createToolProtectionService(mappedEnv, runtimeConfig);
+
     // Initialize MCP-I runtime for cryptographic proofs and identity
     this.mcpiRuntime = createCloudflareRuntime({
       env: mappedEnv,
+      environment: runtimeConfig.environment,
       audit: {
         enabled: runtimeConfig.audit?.enabled ?? true,
         logFunction: runtimeConfig.audit?.logFunction || ((record) => console.log('[MCP-I Audit]', record))
       },
-      toolProtectionService: runtimeConfig.toolProtectionService,
-      authorizationUrl: runtimeConfig.delegation?.authorization?.authorizationUrl
+      toolProtectionService
     });
 
     // Initialize proof archive if PROOF_ARCHIVE KV is available
@@ -1001,7 +996,7 @@ export class ${pascalClassName}MCP extends McpAgent {
       const sessionId = this.getSessionId();
 
       // Get routing strategy from environment (default: session)
-      const strategy = (this.env as any).DO_ROUTING_STRATEGY || 'session';
+      const strategy = this.env.DO_ROUTING_STRATEGY || 'session';
 
       if (strategy === 'session') {
         // One DO instance per MCP session (recommended for most use cases)
@@ -1010,7 +1005,7 @@ export class ${pascalClassName}MCP extends McpAgent {
       } else if (strategy === 'shard') {
         // Hash-based sharding across N DO instances (for high load)
         // Distributes load evenly while maintaining session affinity
-        const shardCount = parseInt((this.env as any).DO_SHARD_COUNT || '10');
+        const shardCount = parseInt(this.env.DO_SHARD_COUNT || '10');
         // Validate shard count - must be a valid positive number
         const validShardCount = (!isNaN(shardCount) && shardCount > 0) ? shardCount : 10;
 
@@ -1042,7 +1037,7 @@ export class ${pascalClassName}MCP extends McpAgent {
    * @returns Delegation token if found, null otherwise
    */
   private async getDelegationToken(sessionId?: string): Promise<string | null> {
-    const delegationStorage = (this.env as any).${className.toUpperCase()}_DELEGATION_STORAGE;
+    const delegationStorage = this.env.${className.toUpperCase()}_DELEGATION_STORAGE;
 
     if (!delegationStorage) {
       console.log('[Delegation] No delegation storage configured');
@@ -1116,7 +1111,7 @@ export class ${pascalClassName}MCP extends McpAgent {
    */
   private async verifyDelegationWithAgentShield(token: string): Promise<boolean> {
     // Check verification cache first (1 minute TTL for verified tokens)
-    const verificationCache = (this.env as any).TOOL_PROTECTION_KV;
+    const verificationCache = this.env.TOOL_PROTECTION_KV;
     if (verificationCache) {
       const cacheKey = \`verified:\${token.substring(0, 16)}\`; // Use prefix to avoid key size issues
       const cached = await verificationCache.get(cacheKey);
@@ -1127,8 +1122,8 @@ export class ${pascalClassName}MCP extends McpAgent {
     }
 
     try {
-      const agentShieldUrl = (this.env as any).AGENTSHIELD_API_URL || 'https://hobbs.work';
-      const apiKey = (this.env as any).AGENTSHIELD_API_KEY;
+      const agentShieldUrl = this.env.AGENTSHIELD_API_URL || 'https://kya.vouched.id';
+      const apiKey = this.env.AGENTSHIELD_API_KEY;
 
       if (!apiKey) {
         console.warn('[Delegation] No AgentShield API key configured, skipping verification');
@@ -1178,8 +1173,8 @@ export class ${pascalClassName}MCP extends McpAgent {
    * @param agentDid - Agent DID to clear
    */
   private async invalidateDelegationCache(sessionId?: string, token?: string, agentDid?: string): Promise<void> {
-    const delegationStorage = (this.env as any).${className.toUpperCase()}_DELEGATION_STORAGE;
-    const verificationCache = (this.env as any).TOOL_PROTECTION_KV;
+    const delegationStorage = this.env.${className.toUpperCase()}_DELEGATION_STORAGE;
+    const verificationCache = this.env.TOOL_PROTECTION_KV;
 
     if (!delegationStorage) return;
 
@@ -1216,10 +1211,10 @@ export class ${pascalClassName}MCP extends McpAgent {
    */
   private async submitProofToAgentShield(
     proof: DetachedProof,
-    session: any,
+    session: { id: string },
     toolName: string,
-    args: any,
-    result: any
+    args: Record<string, unknown>,
+    result: unknown
   ): Promise<void> {
     if (!this.agentShieldConfig || !proof.jws || !proof.meta) return;
 
@@ -1275,7 +1270,7 @@ export class ${pascalClassName}MCP extends McpAgent {
       throw new Error(\`AgentShield error: \${response.status}\`);
     }
 
-    const responseData = await response.json() as any;
+    const responseData = await response.json() as { success?: boolean; received?: number; processed?: number; accepted?: number; rejected?: number; errors?: Array<{ proofId: string; error: string }> };
     console.log('[AgentShield] Response:', responseData);
 
     if (responseData.accepted) {
@@ -1297,7 +1292,7 @@ export class ${pascalClassName}MCP extends McpAgent {
       greetTool.name,
       greetTool.description,
       greetTool.inputSchema.shape,
-      async (args: any) => {
+      async (args: { name: string }) => {
         // Use MCP-I runtime's processToolCall for automatic proof generation
         if (this.mcpiRuntime) {
           try {
@@ -1358,8 +1353,8 @@ export class ${pascalClassName}MCP extends McpAgent {
                     toolName: greetTool.name
                   }).then(() => {
                     console.log('[MCP-I] Proof stored in archive');
-                  }).catch((archiveError: any) => {
-                    console.error('[MCP-I] Archive error:', archiveError);
+                  }).catch((archiveError: unknown) => {
+                    console.error('[MCP-I] Archive error:', archiveError instanceof Error ? archiveError.message : String(archiveError));
                   })
                 );
               }
@@ -1368,8 +1363,8 @@ export class ${pascalClassName}MCP extends McpAgent {
               if (this.agentShieldConfig) {
                 proofOperations.push(
                   this.submitProofToAgentShield(proof, session, greetTool.name, args, result)
-                    .catch((err: any) => {
-                      console.error('[MCP-I] AgentShield failed:', err.message);
+                    .catch((err: unknown) => {
+                      console.error('[MCP-I] AgentShield failed:', err instanceof Error ? err.message : String(err));
                     })
                 );
               }
@@ -1380,8 +1375,8 @@ export class ${pascalClassName}MCP extends McpAgent {
               }
 
               // Attach proof to result for MCP Inspector
-              if (result && typeof result === 'object') {
-                (result as any)._meta = {
+              if (result && typeof result === 'object' && result !== null) {
+                (result as Record<string, unknown>)._meta = {
                   proof: {
                     jws: proof.jws,
                     did: proof.meta.did,
@@ -1397,7 +1392,29 @@ export class ${pascalClassName}MCP extends McpAgent {
             }
 
             return result;
-          } catch (error) {
+          } catch (error: unknown) {
+            // If this is a DelegationRequiredError, re-throw it so the MCP framework can handle it properly
+            // The agents/mcp framework will format it as a proper error response to Claude Desktop
+            if (error instanceof DelegationRequiredError) {
+              console.warn('[MCP-I] Delegation required, propagating error:', {
+                tool: error.toolName,
+                requiredScopes: error.requiredScopes,
+                consentUrl: error.consentUrl
+              });
+              throw error;
+            }
+            // Check for DelegationRequiredError by name (for cases where error is not instanceof)
+            if (error && typeof error === 'object' && 'name' in error && error.name === 'DelegationRequiredError') {
+              const delegationError = error as DelegationRequiredError;
+              console.warn('[MCP-I] Delegation required, propagating error:', {
+                tool: delegationError.toolName,
+                requiredScopes: delegationError.requiredScopes,
+                consentUrl: delegationError.consentUrl
+              });
+              throw error;
+            }
+            
+            // For other errors, log and fallback to direct execution
             console.error('[MCP-I] Failed to process tool with runtime:', error);
             // Fallback to direct execution
             return await greetTool.handler(args);
@@ -1460,7 +1477,7 @@ app.get("/health", (c) => c.json({
  *   { "success": true, "message": "Cache cleared", "agent_did": "..." }
  */
 app.post("/admin/clear-cache", async (c) => {
-  const env = c.env as any;
+  const env = c.env as PrefixedCloudflareEnv;
 
   // Parse request body first to get agent_did
   const body = await c.req.json().catch(() => ({}));
@@ -1572,7 +1589,7 @@ app.post("/admin/clear-cache", async (c) => {
  * 4. Returns success page to user
  */
 app.get('/oauth/callback', (c) => {
-  const env = c.env as any;
+  const env = c.env as PrefixedCloudflareEnv;
   return createOAuthCallbackHandler({
     agentShieldApiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
     delegationStorage: env.${className.toUpperCase()}_DELEGATION_STORAGE,
@@ -1668,9 +1685,11 @@ id = "your_delegation_kv_namespace_id"  # Auto-filled by setup script
 # If you need to recreate it: npm run kv:create-tool-protection
 # After deployment, toggle delegation requirements in AgentShield dashboard
 #
-${apikey ? "" : "# "}[[kv_namespaces]]
-${apikey ? "" : "# "}binding = "${className.toUpperCase()}_TOOL_PROTECTION_KV"
-${apikey ? "" : "# "}id = "your_tool_protection_kv_id"  # Auto-filled by setup script
+# Note: This namespace is REQUIRED when using AgentShield API key (--apikey)
+#       It will be automatically created by the setup script (npm run setup)
+[[kv_namespaces]]
+binding = "${className.toUpperCase()}_TOOL_PROTECTION_KV"
+id = "your_tool_protection_kv_id"  # Auto-filled by setup script
 
 [vars]
 XMCP_I_TS_SKEW_SEC = "120"
@@ -1683,12 +1702,12 @@ AGENTSHIELD_API_URL = "https://kya.vouched.id"
 #   Production: wrangler secret put AGENTSHIELD_API_KEY
 AGENTSHIELD_API_KEY = ""
 # AGENTSHIELD_PROJECT_ID - Your project ID from AgentShield dashboard (e.g., "batman-txh0ae")
-#   Required for project-scoped tool protection configuration
+#   Required for project-scoped tool protection configuration (recommended)
 #   Find it in your dashboard URL: https://kya.vouched.id/dashboard/projects/{PROJECT_ID}
 #   Or in your project settings
-#   Development: Add to .dev.vars file
+#   Development: Add to .dev.vars file${projectId ? ` (already configured: ${projectId})` : ""}
 #   Production: wrangler secret put AGENTSHIELD_PROJECT_ID
-AGENTSHIELD_PROJECT_ID = ""
+AGENTSHIELD_PROJECT_ID = "${projectId || ""}"
 MCPI_ENV = "development"
 
 # Optional: MCP Server URL for tool discovery
@@ -1727,17 +1746,33 @@ DO_ROUTING_STRATEGY = "session"
 DO_SHARD_COUNT = "10"  # Number of shards if using shard strategy
 
 `;
-                    // Always add API key declarations (even if apikey not provided)
+                    // Check if API key variables already exist in wrangler.toml
+                    // (They may have been added by the initial template)
+                    const hasAgentshieldApiKey = /AGENTSHIELD_API_KEY\s*=/.test(wranglerTomlContent);
+                    const hasAgentshieldProjectId = /AGENTSHIELD_PROJECT_ID\s*=/.test(wranglerTomlContent);
+                    const hasAdminApiKey = /ADMIN_API_KEY\s*=/.test(wranglerTomlContent);
+                    // Build API key declarations only for variables that don't already exist
                     // Cloudflare Workers REQUIRE variables to be declared in [vars] for .dev.vars to work
-                    const apiKeyVars = `
-# API keys - MUST be declared here for .dev.vars to work!
-# Development: Values in .dev.vars will override these empty strings
-# Production: Use wrangler secret put to set these
-AGENTSHIELD_API_KEY = ""
-ADMIN_API_KEY = ""
-AGENTSHIELD_PROJECT_ID = ""
-
-`;
+                    const apiKeyVarsParts = [];
+                    if (!hasAgentshieldApiKey ||
+                        !hasAgentshieldProjectId ||
+                        !hasAdminApiKey) {
+                        apiKeyVarsParts.push(`# API keys - MUST be declared here for .dev.vars to work!`);
+                        apiKeyVarsParts.push(`# Development: Values in .dev.vars will override these empty strings`);
+                        apiKeyVarsParts.push(`# Production: Use wrangler secret put to set these`);
+                    }
+                    if (!hasAgentshieldApiKey) {
+                        apiKeyVarsParts.push(`AGENTSHIELD_API_KEY = ""`);
+                    }
+                    if (!hasAdminApiKey) {
+                        apiKeyVarsParts.push(`ADMIN_API_KEY = ""`);
+                    }
+                    if (!hasAgentshieldProjectId) {
+                        apiKeyVarsParts.push(`AGENTSHIELD_PROJECT_ID = ""`);
+                    }
+                    const apiKeyVars = apiKeyVarsParts.length > 0
+                        ? `\n${apiKeyVarsParts.join("\n")}\n`
+                        : "";
                     wranglerTomlContent =
                         wranglerTomlContent.slice(0, insertPosition) +
                             identityVars +
@@ -1763,7 +1798,7 @@ MCP_IDENTITY_PUBLIC_KEY="${identity.publicKey}"
 AGENTSHIELD_API_KEY="${apikey || ""}"${apikey ? "  # Provided via --apikey flag" : ""}
 
 # AgentShield Project ID (from dashboard URL: /dashboard/projects/{PROJECT_ID})
-AGENTSHIELD_PROJECT_ID=""
+AGENTSHIELD_PROJECT_ID="${projectId || ""}"${projectId ? "  # Provided via --project flag" : ""}
 
 # Admin API key for protected endpoints
 ADMIN_API_KEY=""