@true-and-useful/janee 0.11.3 → 0.13.0

package/dist/core/mcp-server.js

@@ -40,26 +40,38 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DenialError = void 0;
+exports.explainAccessDenial = explainAccessDenial;
 exports.createMCPServer = createMCPServer;
 exports.makeAPIRequest = makeAPIRequest;
 exports.captureClientInfo = captureClientInfo;
 exports.startMCPServer = startMCPServer;
 exports.startMCPServerHTTP = startMCPServerHTTP;
+const express_1 = __importDefault(require("express"));
+const fs_1 = require("fs");
+const http_1 = __importDefault(require("http"));
+const https_1 = __importDefault(require("https"));
+const path_1 = require("path");
 const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
-const rules_js_1 = require("./rules.js");
-const http_1 = __importDefault(require("http"));
-const https_1 = __importDefault(require("https"));
-const express_1 = __importDefault(require("express"));
-const exec_js_1 = require("./exec.js");
-const fs_1 = require("fs");
 const agent_scope_js_1 = require("./agent-scope.js");
-const path_1 = require("path");
+const exec_js_1 = require("./exec.js");
+const health_js_1 = require("./health.js");
+const rules_js_1 = require("./rules.js");
 // Read version from package.json
-const packageJsonPath = (0, path_1.join)(__dirname, '../../package.json');
-const pkgVersion = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, 'utf8')).version || '0.0.0';
+const packageJsonPath = (0, path_1.join)(__dirname, "../../package.json");
+const pkgVersion = JSON.parse((0, fs_1.readFileSync)(packageJsonPath, "utf8")).version || "0.0.0";
+class DenialError extends Error {
+    denial;
+    constructor(message, denial) {
+        super(message);
+        this.name = 'DenialError';
+        this.denial = denial;
+    }
+}
+exports.DenialError = DenialError;
 /**
  * Check whether an agent can access a capability.
  * Checks capability-level allowedAgents first, then falls back to
@@ -73,11 +85,40 @@ function canAccessCapability(agentId, cap, service, defaultAccessPolicy) {
     if (cap.allowedAgents && cap.allowedAgents.length > 0) {
         return cap.allowedAgents.includes(agentId);
     }
-    if (defaultAccessPolicy === 'restricted') {
+    if (defaultAccessPolicy === "restricted") {
         return false;
     }
     return (0, agent_scope_js_1.canAgentAccess)(agentId, service?.ownership);
 }
+/**
+ * Returns the specific reason access was denied, or null if access is allowed.
+ */
+function explainAccessDenial(agentId, cap, service, defaultAccessPolicy) {
+    if (!agentId)
+        return null;
+    if (cap.allowedAgents && cap.allowedAgents.length > 0) {
+        if (!cap.allowedAgents.includes(agentId)) {
+            return {
+                reason: 'AGENT_NOT_ALLOWED',
+                detail: `Agent "${agentId}" is not in allowedAgents [${cap.allowedAgents.join(', ')}]`
+            };
+        }
+        return null;
+    }
+    if (defaultAccessPolicy === 'restricted') {
+        return {
+            reason: 'DEFAULT_ACCESS_RESTRICTED',
+            detail: `defaultAccess is "restricted" and capability has no allowedAgents list`
+        };
+    }
+    if (!(0, agent_scope_js_1.canAgentAccess)(agentId, service?.ownership)) {
+        return {
+            reason: 'OWNERSHIP_DENIED',
+            detail: `Agent "${agentId}" is not listed in service ownership for "${service?.baseUrl || 'unknown'}"`
+        };
+    }
+    return null;
+}
 /**
  * Parse TTL string to seconds
  */
@@ -91,7 +132,7 @@ function parseTTL(ttl) {
         s: 1,
         m: 60,
         h: 3600,
-        d: 86400
+        d: 86400,
     };
     return value * multipliers[unit];
 }
@@ -99,7 +140,7 @@ function parseTTL(ttl) {
  * Create and start MCP server
  */
 function createMCPServer(options) {
-    const { sessionManager, auditLogger, defaultAccess, onExecute, onExecCommand, onReloadConfig, onPersistOwnership, onForwardToolCall } = options;
+    const { sessionManager, auditLogger, defaultAccess, onExecute, onExecCommand, onReloadConfig, onPersistOwnership, onForwardToolCall, } = options;
     // Store as mutable to support hot-reloading
     let capabilities = options.capabilities;
     let services = options.services;
@@ -107,12 +148,12 @@ function createMCPServer(options) {
     // Populated by captureClientInfo() after connecting a transport.
     const clientSessions = new Map();
     const server = new index_js_1.Server({
-        name: 'janee',
-        version: pkgVersion
+        name: "janee",
+        version: pkgVersion,
     }, {
         capabilities: {
-            tools: {}
-        }
+            tools: {},
+        },
     });
     /**
      * Resolve agent identity from the MCP session.
@@ -122,126 +163,192 @@ function createMCPServer(options) {
      * Falls back to args.agentId for legacy scenarios.
      */
     function resolveAgentFromRequest(extra, args) {
-        const sessionKey = extra?.sessionId || '__default__';
-        const clientName = clientSessions.get(sessionKey) || clientSessions.get('__default__');
-        return (0, agent_scope_js_1.resolveAgentIdentity)({ agentId: extra?.sessionId, metadata: { transportAgentHint: clientName } }, args?.agentId);
+        const sessionKey = extra?.sessionId || "__default__";
+        const clientName = clientSessions.get(sessionKey) || clientSessions.get("__default__");
+        return (0, agent_scope_js_1.resolveAgentIdentity)({
+            agentId: extra?.sessionId,
+            metadata: { transportAgentHint: clientName },
+        }, args?.agentId);
     }
     // Tool: list_services
     const listServicesTool = {
-        name: 'list_services',
-        description: 'List available API capabilities managed by Janee',
+        name: "list_services",
+        description: "List available API capabilities managed by Janee",
         inputSchema: {
-            type: 'object',
+            type: "object",
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     };
     // Tool: execute
     const executeTool = {
-        name: 'execute',
-        description: 'Execute an API request through Janee proxy',
+        name: "execute",
+        description: "Execute an API request through Janee proxy",
         inputSchema: {
-            type: 'object',
+            type: "object",
             properties: {
                 capability: {
-                    type: 'string',
-                    description: 'Capability name to use (from list_services)'
+                    type: "string",
+                    description: "Capability name to use (from list_services)",
                 },
                 method: {
-                    type: 'string',
-                    enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
-                    description: 'HTTP method'
+                    type: "string",
+                    enum: ["GET", "POST", "PUT", "DELETE", "PATCH"],
+                    description: "HTTP method",
                 },
                 path: {
-                    type: 'string',
-                    description: 'API path (e.g., /v1/customers)'
+                    type: "string",
+                    description: "API path (e.g., /v1/customers)",
                 },
                 body: {
-                    type: 'string',
-                    description: 'Request body (JSON string, optional)'
+                    type: "string",
+                    description: "Request body (JSON string, optional)",
                 },
                 headers: {
-                    type: 'object',
-                    description: 'Additional headers (optional)',
-                    additionalProperties: { type: 'string' }
+                    type: "object",
+                    description: "Additional headers (optional)",
+                    additionalProperties: { type: "string" },
                 },
                 reason: {
-                    type: 'string',
-                    description: 'Reason for this request (required for some capabilities)'
-                }
+                    type: "string",
+                    description: "Reason for this request (required for some capabilities)",
+                },
             },
-            required: ['capability', 'method', 'path']
-        }
+            required: ["capability", "method", "path"],
+        },
     };
     // Tool: reload_config
     const reloadConfigTool = {
-        name: 'reload_config',
-        description: 'Reload Janee configuration from disk without restarting the server. Use after adding new services or capabilities.',
+        name: "reload_config",
+        description: "Reload Janee configuration from disk without restarting the server. Use after adding new services or capabilities.",
         inputSchema: {
-            type: 'object',
+            type: "object",
             properties: {},
-            required: []
-        }
+            required: [],
+        },
     };
     // Tool: janee_exec (RFC 0001 - Secure CLI Execution)
     const execTool = {
-        name: 'janee_exec',
-        description: 'Execute a CLI command with credentials injected via environment variables. The agent never sees the actual credential — Janee injects it and scrubs output.',
+        name: "janee_exec",
+        description: "Execute a CLI command with credentials injected via environment variables. The agent never sees the actual credential — Janee injects it and scrubs output.",
         inputSchema: {
-            type: 'object',
+            type: "object",
             properties: {
                 capability: {
-                    type: 'string',
-                    description: 'Capability name (must be exec mode, from list_services)'
+                    type: "string",
+                    description: "Capability name (must be exec mode, from list_services)",
                 },
                 command: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Command and arguments as array, e.g. ["gh", "issue", "list"]'
+                    type: "array",
+                    items: { type: "string" },
+                    description: 'Command and arguments as array, e.g. ["gh", "issue", "list"]',
                 },
                 cwd: {
-                    type: 'string',
-                    description: 'Working directory for the command (defaults to process cwd)'
+                    type: "string",
+                    description: "Working directory for the command (defaults to process cwd)",
                 },
                 stdin: {
-                    type: 'string',
-                    description: 'Optional stdin input to pipe to the command'
+                    type: "string",
+                    description: "Optional stdin input to pipe to the command",
                 },
                 reason: {
-                    type: 'string',
-                    description: 'Reason for this execution (required for some capabilities)'
-                }
+                    type: "string",
+                    description: "Reason for this execution (required for some capabilities)",
+                },
             },
-            required: ['capability', 'command']
-        }
+            required: ["capability", "command"],
+        },
     };
     // Tool: manage_credential (agent-scoped credential access control)
     const manageCredentialTool = {
-        name: 'manage_credential',
-        description: 'View or manage access policies for agent-scoped credentials. Agents can check who has access, grant access to other agents, or revoke access.',
+        name: "manage_credential",
+        description: "View or manage access policies for agent-scoped credentials. Agents can check who has access, grant access to other agents, or revoke access.",
         inputSchema: {
-            type: 'object',
+            type: "object",
             properties: {
                 action: {
-                    type: 'string',
-                    enum: ['view', 'grant', 'revoke'],
-                    description: 'Action to perform: view ownership info, grant access to another agent, or revoke access'
+                    type: "string",
+                    enum: ["view", "grant", "revoke"],
+                    description: "Action to perform: view ownership info, grant access to another agent, or revoke access",
                 },
                 service: {
-                    type: 'string',
-                    description: 'Service name to manage'
+                    type: "string",
+                    description: "Service name to manage",
                 },
                 targetAgentId: {
+                    type: "string",
+                    description: "Agent ID to grant/revoke access for (required for grant/revoke actions)",
+                },
+            },
+            required: ["action", "service"],
+        },
+    };
+    // Tool: test_service
+    const testServiceTool = {
+        name: "test_service",
+        description: "Test connectivity and authentication for a configured service. Verifies that Janee can reach the service and that credentials are valid.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                service: {
+                    type: "string",
+                    description: "Service name to test (from list_services). Omit to test all services.",
+                },
+                timeout: {
+                    type: "number",
+                    description: "Timeout in milliseconds for the health check (default: 10000).",
+                },
+            },
+            required: [],
+        },
+    };
+    // Tool: whoami — lets agents discover their resolved identity
+    const whoamiTool = {
+        name: 'whoami',
+        description: 'Show your resolved agent identity as Janee sees it, which capabilities you can access, and the server access policy. Useful for understanding allowedAgents restrictions.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: []
+        }
+    };
+    // Tool: explain_access — full policy evaluation trace
+    const explainAccessTool = {
+        name: 'explain_access',
+        description: 'Trace exactly why a given agent can or cannot access a capability. Returns step-by-step policy evaluation (capability exists, mode, allowedAgents, defaultAccess, ownership, rules). Use for debugging access issues.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agent: {
+                    type: 'string',
+                    description: 'Agent ID to evaluate access for. Defaults to the calling agent.'
+                },
+                capability: {
+                    type: 'string',
+                    description: 'Capability name to check access for.'
+                },
+                method: {
+                    type: 'string',
+                    description: 'HTTP method for rules evaluation (optional, only applies to proxy capabilities).'
+                },
+                path: {
                     type: 'string',
-                    description: 'Agent ID to grant/revoke access for (required for grant/revoke actions)'
+                    description: 'Request path for rules evaluation (optional, only applies to proxy capabilities).'
                 }
             },
-            required: ['action', 'service']
+            required: ['capability']
         }
     };
     // Register tools
     server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
-        const tools = [listServicesTool, executeTool, manageCredentialTool];
+        const tools = [
+            listServicesTool,
+            executeTool,
+            manageCredentialTool,
+            testServiceTool,
+            whoamiTool,
+            explainAccessTool,
+        ];
         if (onExecCommand && !options.hideExecTool) {
             tools.push(execTool);
         }
@@ -254,42 +361,40 @@ function createMCPServer(options) {
     server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: args } = request.params;
         try {
-            // Runner proxy: forward non-exec tools to the Authority
-            if (onForwardToolCall && name !== 'janee_exec') {
+            // Runner proxy: forward all non-exec tools to the Authority
+            if (onForwardToolCall && name !== "janee_exec") {
                 const forwardAgentId = resolveAgentFromRequest(extra, args);
                 const result = await onForwardToolCall(name, (args || {}), forwardAgentId);
                 return result;
             }
             switch (name) {
-                case 'list_services': {
+                case "list_services": {
                     const listAgentId = resolveAgentFromRequest(extra, args);
                     return {
-                        content: [{
-                                type: 'text',
-                                text: JSON.stringify(capabilities
-                                    .filter(cap => {
-                                    const svc = services.get(cap.service);
-                                    return canAccessCapability(listAgentId, cap, svc, defaultAccess);
-                                })
-                                    .map(cap => ({
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(capabilities.map((cap) => ({
+                                    accessible: canAccessCapability(listAgentId, cap, services.get(cap.service), defaultAccess),
                                     name: cap.name,
                                     service: cap.service,
-                                    mode: cap.mode || 'proxy',
+                                    mode: cap.mode || "proxy",
                                     ttl: cap.ttl,
                                     autoApprove: cap.autoApprove,
                                     requiresReason: cap.requiresReason,
                                     rules: cap.rules,
-                                    ...(cap.mode === 'exec' && {
+                                    ...(cap.mode === "exec" && {
                                         allowCommands: cap.allowCommands,
                                         env: cap.env ? Object.keys(cap.env) : undefined,
-                                    })
-                                })), null, 2)
-                            }]
+                                    }),
+                                })), null, 2),
+                            },
+                        ],
                     };
                 }
-                case 'reload_config': {
+                case "reload_config": {
                     if (!onReloadConfig) {
-                        throw new Error('Config reload not supported');
+                        throw new Error("Config reload not supported");
                     }
                     try {
                         const result = onReloadConfig();
@@ -298,63 +403,93 @@ function createMCPServer(options) {
                         capabilities = result.capabilities;
                         services = result.services;
                         return {
-                            content: [{
-                                    type: 'text',
+                            content: [
+                                {
+                                    type: "text",
                                     text: JSON.stringify({
                                         success: true,
-                                        message: 'Configuration reloaded successfully',
+                                        message: "Configuration reloaded successfully",
                                         services: services.size,
                                         capabilities: capabilities.length,
                                         changes: {
                                             services: services.size - prevServiceCount,
-                                            capabilities: capabilities.length - prevCapCount
-                                        }
-                                    }, null, 2)
-                                }]
+                                            capabilities: capabilities.length - prevCapCount,
+                                        },
+                                    }, null, 2),
+                                },
+                            ],
                         };
                     }
                     catch (error) {
-                        throw new Error(`Failed to reload config: ${error instanceof Error ? error.message : 'Unknown error'}`);
+                        throw new Error(`Failed to reload config: ${error instanceof Error ? error.message : "Unknown error"}`);
                     }
                 }
-                case 'execute': {
+                case "execute": {
                     const { capability, method, path, body, headers, reason } = args;
                     // Validate required arguments
                     if (!capability) {
-                        throw new Error('Missing required argument: capability');
+                        throw new Error("Missing required argument: capability");
                     }
                     if (!method) {
-                        throw new Error('Missing required argument: method (GET, POST, PUT, DELETE, etc.)');
+                        throw new Error("Missing required argument: method (GET, POST, PUT, DELETE, etc.)");
                     }
                     if (!path) {
-                        throw new Error('Missing required argument: path');
+                        throw new Error("Missing required argument: path");
                     }
                     // Find capability
-                    const cap = capabilities.find(c => c.name === capability);
+                    const cap = capabilities.find((c) => c.name === capability);
                     if (!cap) {
-                        throw new Error(`Unknown capability: ${capability}`);
+                        throw new DenialError(`Unknown capability: ${capability}`, {
+                            reasonCode: 'CAPABILITY_NOT_FOUND',
+                            capability,
+                            nextStep: `Run 'janee cap list' to see available capabilities, or add one with 'janee cap add'.`
+                        });
                     }
                     // Reject exec-mode capabilities — they should use janee_exec instead
-                    if (cap.mode === 'exec') {
-                        throw new Error(`Capability "${capability}" is an exec-mode capability. Use the 'janee_exec' tool instead.`);
+                    if (cap.mode === "exec") {
+                        throw new DenialError(`Capability "${capability}" is an exec-mode capability. Use the 'janee_exec' tool instead.`, {
+                            reasonCode: "MODE_MISMATCH",
+                            capability,
+                            nextStep: `Use the 'janee_exec' tool for exec-mode capabilities.`,
+                        });
                     }
                     // Check if reason required
                     if (cap.requiresReason && !reason) {
-                        throw new Error(`Capability "${capability}" requires a reason`);
+                        throw new DenialError(`Capability "${capability}" requires a reason`, {
+                            reasonCode: 'REASON_REQUIRED',
+                            capability,
+                            nextStep: `Include a 'reason' argument explaining why you need this access.`
+                        });
                     }
                     // Check rules (path-based policies)
                     const ruleCheck = (0, rules_js_1.checkRules)(cap.rules, method, path);
                     if (!ruleCheck.allowed) {
-                        // Log denied request
-                        auditLogger.logDenied(cap.service, method, path, ruleCheck.reason || 'Request denied by policy', reason);
-                        throw new Error(ruleCheck.reason || 'Request denied by policy');
+                        auditLogger.logDenied(cap.service, method, path, ruleCheck.reason || "Request denied by policy", reason);
+                        throw new DenialError(ruleCheck.reason || "Request denied by policy", {
+                            reasonCode: "RULE_DENY",
+                            capability,
+                            agentId: resolveAgentFromRequest(extra, args),
+                            evaluatedPolicy: `rules for ${method} ${path}`,
+                            nextStep: `Check capability rules with 'janee cap list --json' — the path/method may be explicitly denied.`,
+                        });
                     }
                     // Check agent-scoped access (capability-level allowedAgents, then service-level ownership)
                     const executeAgentId = resolveAgentFromRequest(extra, args);
                     const executeSvc = services.get(cap.service);
                     if (!canAccessCapability(executeAgentId, cap, executeSvc, defaultAccess)) {
-                        auditLogger.logDenied(cap.service, method, path, 'Agent does not have access to this capability', reason);
-                        throw new Error(`Access denied: capability "${capability}" is not accessible to this agent`);
+                        const denialDetail = explainAccessDenial(executeAgentId, cap, executeSvc, defaultAccess);
+                        auditLogger.logDenied(cap.service, method, path, "Agent does not have access to this capability", reason);
+                        throw new DenialError(`Access denied: capability "${capability}" is not accessible to this agent`, {
+                            reasonCode: denialDetail?.reason || "AGENT_NOT_ALLOWED",
+                            capability,
+                            agentId: executeAgentId,
+                            evaluatedPolicy: denialDetail?.detail,
+                            nextStep: denialDetail?.reason === "AGENT_NOT_ALLOWED"
+                                ? `Add this agent to allowedAgents: 'janee cap edit ${capability} --allowed-agents ${executeAgentId}'`
+                                : denialDetail?.reason === "DEFAULT_ACCESS_RESTRICTED"
+                                    ? `Either add allowedAgents to the capability or change defaultAccess to 'open'.`
+                                    : `Check service ownership settings for the backing service.`,
+                        });
                     }
                     // Get or create session
                     const ttlSeconds = parseTTL(cap.ttl);
@@ -365,34 +500,38 @@ function createMCPServer(options) {
                         path,
                         method,
                         headers: headers || {},
-                        body
+                        body,
                     };
                     // Execute
                     const response = await onExecute(session, apiReq);
                     return {
-                        content: [{
-                                type: 'text',
+                        content: [
+                            {
+                                type: "text",
                                 text: JSON.stringify({
                                     status: response.statusCode,
-                                    body: response.body
-                                }, null, 2)
-                            }]
+                                    body: response.body,
+                                }, null, 2),
+                            },
+                        ],
                     };
                 }
-                case 'janee_exec': {
+                case "janee_exec": {
                     if (!onExecCommand) {
-                        throw new Error('CLI execution not supported in this configuration');
+                        throw new Error("CLI execution not supported in this configuration");
                     }
-                    const { capability: execCapName, command: rawExecCommand, cwd: execCwd, stdin: execStdin, reason: execReason } = args;
+                    const { capability: execCapName, command: rawExecCommand, cwd: execCwd, stdin: execStdin, reason: execReason, } = args;
                     if (!execCapName) {
-                        throw new Error('Missing required argument: capability');
+                        throw new Error("Missing required argument: capability");
                     }
-                    if (!rawExecCommand || (Array.isArray(rawExecCommand) && rawExecCommand.length === 0) || (typeof rawExecCommand === 'string' && rawExecCommand.trim() === '')) {
-                        throw new Error('Missing required argument: command');
+                    if (!rawExecCommand ||
+                        (Array.isArray(rawExecCommand) && rawExecCommand.length === 0) ||
+                        (typeof rawExecCommand === "string" && rawExecCommand.trim() === "")) {
+                        throw new Error("Missing required argument: command");
                     }
                     const execCommand = Array.isArray(rawExecCommand)
                         ? rawExecCommand
-                        : typeof rawExecCommand === 'string'
+                        : typeof rawExecCommand === "string"
                             ? rawExecCommand.trim().split(/\s+/)
                             : [];
                     let execCap;
@@ -400,32 +539,67 @@ function createMCPServer(options) {
                     if (onForwardToolCall) {
                         // Runner mode: Authority handles validation and credential injection.
                         // Build a minimal capability stub so onExecCommand has the name.
-                        execCap = { name: execCapName, service: '', ttl: '1h', mode: 'exec', workDir: execCwd };
+                        execCap = {
+                            name: execCapName,
+                            service: "",
+                            ttl: "1h",
+                            mode: "exec",
+                            workDir: execCwd,
+                        };
                         execSession = { agentId: resolveAgentFromRequest(extra, args) };
                     }
                     else {
                         // Standalone mode: validate locally
-                        const foundCap = capabilities.find(c => c.name === execCapName);
+                        const foundCap = capabilities.find((c) => c.name === execCapName);
                         if (!foundCap) {
-                            throw new Error(`Unknown capability: ${execCapName}`);
+                            throw new DenialError(`Unknown capability: ${execCapName}`, {
+                                reasonCode: 'CAPABILITY_NOT_FOUND',
+                                capability: execCapName,
+                                nextStep: `Run 'janee cap list' to see available capabilities, or add one with 'janee cap add'.`
+                            });
                         }
                         execCap = execCwd ? { ...foundCap, workDir: execCwd } : foundCap;
-                        if (execCap.mode !== 'exec') {
-                            throw new Error(`Capability "${execCapName}" is not an exec-mode capability. Use the 'execute' tool for API proxy capabilities.`);
+                        if (execCap.mode !== "exec") {
+                            throw new DenialError(`Capability "${execCapName}" is not an exec-mode capability. Use the 'execute' tool for API proxy capabilities.`, {
+                                reasonCode: "MODE_MISMATCH",
+                                capability: execCapName,
+                                nextStep: `Use the 'execute' tool for proxy-mode capabilities.`,
+                            });
                         }
                         const execAgentId = resolveAgentFromRequest(extra, args);
                         const execSvc = services.get(execCap.service);
                         if (!canAccessCapability(execAgentId, execCap, execSvc, defaultAccess)) {
-                            auditLogger.logDenied(execCap.service, 'EXEC', execCommand.join(' '), 'Agent does not have access to this capability', execReason);
-                            throw new Error(`Access denied: capability "${execCapName}" is not accessible to this agent`);
+                            const execDenialDetail = explainAccessDenial(execAgentId, execCap, execSvc, defaultAccess);
+                            auditLogger.logDenied(execCap.service, "EXEC", execCommand.join(" "), "Agent does not have access to this capability", execReason);
+                            throw new DenialError(`Access denied: capability "${execCapName}" is not accessible to this agent`, {
+                                reasonCode: execDenialDetail?.reason || "AGENT_NOT_ALLOWED",
+                                capability: execCapName,
+                                agentId: execAgentId,
+                                evaluatedPolicy: execDenialDetail?.detail,
+                                nextStep: execDenialDetail?.reason === "AGENT_NOT_ALLOWED"
+                                    ? `Add this agent to allowedAgents: 'janee cap edit ${execCapName} --allowed-agents ${execAgentId}'`
+                                    : execDenialDetail?.reason === "DEFAULT_ACCESS_RESTRICTED"
+                                        ? `Either add allowedAgents to the capability or change defaultAccess to 'open'.`
+                                        : `Check service ownership settings for the backing service.`,
+                            });
                         }
                         if (execCap.requiresReason && !execReason) {
-                            throw new Error(`Capability "${execCapName}" requires a reason`);
+                            throw new DenialError(`Capability "${execCapName}" requires a reason`, {
+                                reasonCode: 'REASON_REQUIRED',
+                                capability: execCapName,
+                                nextStep: `Include a 'reason' argument explaining why you need this access.`
+                            });
                         }
                         const cmdValidation = (0, exec_js_1.validateCommand)(execCommand, execCap.allowCommands || []);
                         if (!cmdValidation.allowed) {
-                            auditLogger.logDenied(execCap.service, 'EXEC', execCommand.join(' '), cmdValidation.reason || 'Command not allowed', execReason);
-                            throw new Error(cmdValidation.reason || 'Command not allowed');
+                            auditLogger.logDenied(execCap.service, "EXEC", execCommand.join(" "), cmdValidation.reason || "Command not allowed", execReason);
+                            throw new DenialError(cmdValidation.reason || "Command not allowed", {
+                                reasonCode: "COMMAND_NOT_ALLOWED",
+                                capability: execCapName,
+                                agentId: execAgentId,
+                                evaluatedPolicy: `allowCommands: [${(execCap.allowCommands || []).join(", ")}]`,
+                                nextStep: `Update allowed commands: 'janee cap edit ${execCapName} --allow-commands "new-pattern"'`,
+                            });
                         }
                         const execTtlSeconds = parseTTL(execCap.ttl);
                         execSession = sessionManager.createSession(execCap.name, execCap.service, execTtlSeconds, { reason: execReason });
@@ -434,153 +608,338 @@ function createMCPServer(options) {
                     // Log to audit
                     auditLogger.log({
                         service: execCap.service,
-                        path: execCommand.join(' '),
-                        method: 'EXEC',
-                        headers: { 'x-janee-reason': execReason || '' },
+                        path: execCommand.join(" "),
+                        method: "EXEC",
+                        headers: { "x-janee-reason": execReason || "" },
                     }, {
                         statusCode: execResult.exitCode === 0 ? 200 : 500,
                         headers: {},
                         body: execResult.stdout,
                     }, execResult.executionTimeMs);
                     return {
-                        content: [{
-                                type: 'text',
+                        content: [
+                            {
+                                type: "text",
                                 text: JSON.stringify({
                                     exitCode: execResult.exitCode,
                                     stdout: execResult.stdout,
                                     stderr: execResult.stderr,
                                     executionTimeMs: execResult.executionTimeMs,
-                                    executionTarget: 'runner',
-                                }, null, 2)
-                            }]
+                                    executionTarget: "runner",
+                                }, null, 2),
+                            },
+                        ],
                     };
                 }
-                case 'manage_credential': {
-                    const { action: credAction, service: credService, targetAgentId: credTarget } = args;
+                case "manage_credential": {
+                    const { action: credAction, service: credService, targetAgentId: credTarget, } = args;
                     const credAgentId = resolveAgentFromRequest(extra, args);
                     if (!credService) {
-                        throw new Error('Missing required argument: service');
+                        throw new Error("Missing required argument: service");
                     }
                     const svc = services.get(credService);
                     if (!svc) {
                         throw new Error(`Unknown service: ${credService}`);
                     }
-                    if (credAction === 'view') {
+                    if (credAction === "view") {
                         return {
-                            content: [{
-                                    type: 'text',
+                            content: [
+                                {
+                                    type: "text",
                                     text: JSON.stringify({
                                         service: credService,
-                                        ownership: svc.ownership || { accessPolicy: 'all-agents', note: 'No ownership metadata (legacy credential)' },
-                                        yourAccess: (0, agent_scope_js_1.canAgentAccess)(credAgentId, svc.ownership)
-                                    }, null, 2)
-                                }]
+                                        ownership: svc.ownership || {
+                                            accessPolicy: "all-agents",
+                                            note: "No ownership metadata (legacy credential)",
+                                        },
+                                        yourAccess: (0, agent_scope_js_1.canAgentAccess)(credAgentId, svc.ownership),
+                                    }, null, 2),
+                                },
+                            ],
                         };
                     }
                     // Grant/revoke require ownership verification
                     if (!credAgentId) {
-                        throw new Error('agentId is required for grant/revoke actions');
+                        throw new Error("agentId is required for grant/revoke actions");
                     }
                     if (!svc.ownership) {
-                        throw new Error('Cannot manage access for legacy credentials without ownership metadata. Re-add the service to enable scoping.');
+                        throw new Error("Cannot manage access for legacy credentials without ownership metadata. Re-add the service to enable scoping.");
                     }
                     if (svc.ownership.createdBy !== credAgentId) {
-                        throw new Error('Only the credential owner can grant or revoke access');
+                        throw new Error("Only the credential owner can grant or revoke access");
                     }
-                    if (credAction === 'grant') {
+                    if (credAction === "grant") {
                         if (!credTarget) {
-                            throw new Error('targetAgentId is required for grant action');
+                            throw new Error("targetAgentId is required for grant action");
                         }
-                        const { grantAccess } = await Promise.resolve().then(() => __importStar(require('./agent-scope.js')));
+                        const { grantAccess } = await Promise.resolve().then(() => __importStar(require("./agent-scope.js")));
                         svc.ownership = grantAccess(svc.ownership, credTarget);
                         // Persist ownership change to config storage
                         if (onPersistOwnership) {
                             onPersistOwnership(credService, svc.ownership);
                         }
                         return {
-                            content: [{
-                                    type: 'text',
+                            content: [
+                                {
+                                    type: "text",
                                     text: JSON.stringify({
                                         success: true,
                                         message: `Granted access to ${credTarget}`,
                                         ownership: svc.ownership,
-                                        persisted: !!onPersistOwnership
-                                    }, null, 2)
-                                }]
+                                        persisted: !!onPersistOwnership,
+                                    }, null, 2),
+                                },
+                            ],
                         };
                     }
-                    if (credAction === 'revoke') {
+                    if (credAction === "revoke") {
                         if (!credTarget) {
-                            throw new Error('targetAgentId is required for revoke action');
+                            throw new Error("targetAgentId is required for revoke action");
                         }
-                        const { revokeAccess } = await Promise.resolve().then(() => __importStar(require('./agent-scope.js')));
+                        const { revokeAccess } = await Promise.resolve().then(() => __importStar(require("./agent-scope.js")));
                         svc.ownership = revokeAccess(svc.ownership, credTarget);
                         // Persist ownership change to config storage
                         if (onPersistOwnership) {
                             onPersistOwnership(credService, svc.ownership);
                         }
                         return {
-                            content: [{
-                                    type: 'text',
+                            content: [
+                                {
+                                    type: "text",
                                     text: JSON.stringify({
                                         success: true,
                                         message: `Revoked access from ${credTarget}`,
                                         ownership: svc.ownership,
-                                        persisted: !!onPersistOwnership
+                                        persisted: !!onPersistOwnership,
+                                    }, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                    throw new Error(`Unknown action: ${credAction}. Use 'view', 'grant', or 'revoke'.`);
+                }
+                case "test_service": {
+                    const { service: testSvcName, timeout: testTimeout } = (args ||
+                        {});
+                    const testOpts = testTimeout ? { timeout: testTimeout } : {};
+                    let targets;
+                    if (testSvcName) {
+                        const svc = services.get(testSvcName);
+                        if (!svc) {
+                            throw new Error(`Unknown service: ${testSvcName}. Use list_services to see available services.`);
+                        }
+                        targets = [[testSvcName, svc]];
+                    }
+                    else {
+                        targets = Array.from(services.entries());
+                    }
+                    if (targets.length === 0) {
+                        throw new Error("No services configured");
+                    }
+                    const results = await Promise.all(targets.map(([name, config]) => (0, health_js_1.testServiceConnection)(name, config, testOpts)));
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(results.length === 1 ? results[0] : results, null, 2),
+                            },
+                        ],
+                    };
+                }
+                case 'explain_access': {
+                    const { agent: explainAgent, capability: explainCapName, method: explainMethod, path: explainPath } = args;
+                    const targetAgentId = explainAgent || resolveAgentFromRequest(extra, args);
+                    const trace = [];
+                    const explainCap = capabilities.find(c => c.name === explainCapName);
+                    if (!explainCap) {
+                        trace.push({ check: 'capability_exists', result: 'fail', detail: `Capability "${explainCapName}" not found` });
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        agent: targetAgentId ?? null,
+                                        capability: explainCapName,
+                                        allowed: false,
+                                        trace,
+                                        nextStep: `Run 'janee cap list' to see available capabilities.`
                                     }, null, 2)
                                 }]
                         };
                     }
-                    throw new Error(`Unknown action: ${credAction}. Use 'view', 'grant', or 'revoke'.`);
+                    trace.push({ check: 'capability_exists', result: 'pass', detail: `Capability "${explainCapName}" exists (service: ${explainCap.service})` });
+                    // Mode check
+                    if (explainMethod && explainCap.mode === 'exec') {
+                        trace.push({ check: 'mode', result: 'fail', detail: `Capability is exec-mode but method/path were provided (use janee_exec)` });
+                    }
+                    else if (!explainMethod && explainCap.mode !== 'exec') {
+                        trace.push({ check: 'mode', result: 'pass', detail: `Capability mode: ${explainCap.mode || 'proxy'}` });
+                    }
+                    else {
+                        trace.push({ check: 'mode', result: 'pass', detail: `Capability mode: ${explainCap.mode || 'proxy'}` });
+                    }
+                    // allowedAgents
+                    if (explainCap.allowedAgents && explainCap.allowedAgents.length > 0) {
+                        if (!targetAgentId) {
+                            trace.push({ check: 'allowed_agents', result: 'pass', detail: `No agent ID (admin/CLI) — bypasses allowedAgents` });
+                        }
+                        else if (explainCap.allowedAgents.includes(targetAgentId)) {
+                            trace.push({ check: 'allowed_agents', result: 'pass', detail: `Agent "${targetAgentId}" is in allowedAgents [${explainCap.allowedAgents.join(', ')}]` });
+                        }
+                        else {
+                            trace.push({ check: 'allowed_agents', result: 'fail', detail: `Agent "${targetAgentId}" is NOT in allowedAgents [${explainCap.allowedAgents.join(', ')}]` });
+                        }
+                    }
+                    else {
+                        trace.push({ check: 'allowed_agents', result: 'skip', detail: `No allowedAgents restriction on this capability` });
+                    }
+                    // defaultAccess
+                    if (targetAgentId && (!explainCap.allowedAgents || explainCap.allowedAgents.length === 0)) {
+                        if (defaultAccess === 'restricted') {
+                            trace.push({ check: 'default_access', result: 'fail', detail: `defaultAccess is "restricted" and no allowedAgents list — agent blocked` });
+                        }
+                        else {
+                            trace.push({ check: 'default_access', result: 'pass', detail: `defaultAccess is "${defaultAccess ?? 'open'}" — agent allowed` });
+                        }
+                    }
+                    else {
+                        trace.push({ check: 'default_access', result: 'skip', detail: targetAgentId ? `allowedAgents list takes precedence` : `No agent ID (admin/CLI)` });
+                    }
+                    // Ownership
+                    const explainSvc = services.get(explainCap.service);
+                    if (targetAgentId && explainSvc?.ownership) {
+                        if ((0, agent_scope_js_1.canAgentAccess)(targetAgentId, explainSvc.ownership)) {
+                            trace.push({ check: 'ownership', result: 'pass', detail: `Agent can access service (ownership: ${JSON.stringify(explainSvc.ownership)})` });
+                        }
+                        else {
+                            trace.push({ check: 'ownership', result: 'fail', detail: `Agent cannot access service (ownership: ${JSON.stringify(explainSvc.ownership)})` });
+                        }
+                    }
+                    else {
+                        trace.push({ check: 'ownership', result: 'skip', detail: explainSvc?.ownership ? `No agent ID (admin/CLI)` : `No ownership restrictions on service` });
+                    }
+                    // Rules check (only if method/path provided)
+                    if (explainMethod && explainPath && explainCap.mode !== 'exec') {
+                        const ruleResult = (0, rules_js_1.checkRules)(explainCap.rules, explainMethod, explainPath);
+                        if (ruleResult.allowed) {
+                            trace.push({ check: 'rules', result: 'pass', detail: `${explainMethod} ${explainPath} is allowed by rules` });
+                        }
+                        else {
+                            trace.push({ check: 'rules', result: 'fail', detail: ruleResult.reason || `${explainMethod} ${explainPath} is denied by rules` });
+                        }
+                    }
+                    else if (explainCap.mode === 'exec') {
+                        trace.push({ check: 'rules', result: 'skip', detail: `Exec-mode capabilities use allowCommands, not path rules` });
+                    }
+                    else {
+                        trace.push({ check: 'rules', result: 'skip', detail: `No method/path provided for rules evaluation` });
+                    }
+                    // Command validation for exec mode
+                    if (explainCap.mode === 'exec') {
+                        trace.push({ check: 'allow_commands', result: 'skip', detail: `allowCommands: [${(explainCap.allowCommands || []).join(', ')}] — provide a specific command to validate` });
+                    }
+                    const hasFail = trace.some(t => t.result === 'fail');
+                    const firstFail = trace.find(t => t.result === 'fail');
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    agent: targetAgentId ?? null,
+                                    capability: explainCapName,
+                                    allowed: !hasFail,
+                                    trace,
+                                    ...(hasFail && firstFail ? { nextStep: firstFail.detail } : {})
+                                }, null, 2)
+                            }]
+                    };
+                }
+                case 'whoami': {
+                    const whoamiAgentId = resolveAgentFromRequest(extra, args);
+                    const accessibleCaps = capabilities
+                        .filter(cap => canAccessCapability(whoamiAgentId, cap, services.get(cap.service), defaultAccess))
+                        .map(cap => cap.name);
+                    const deniedCaps = capabilities
+                        .filter(cap => !canAccessCapability(whoamiAgentId, cap, services.get(cap.service), defaultAccess))
+                        .map(cap => cap.name);
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: JSON.stringify({
+                                    agentId: whoamiAgentId ?? null,
+                                    identitySource: whoamiAgentId
+                                        ? ((extra?.sessionId && clientSessions.has(extra.sessionId)) || clientSessions.has('__default__')
+                                            ? 'transport (clientInfo.name)'
+                                            : 'client-asserted (untrusted)')
+                                        : 'none',
+                                    defaultAccessPolicy: defaultAccess ?? 'open',
+                                    capabilities: {
+                                        accessible: accessibleCaps,
+                                        denied: deniedCaps,
+                                    },
+                                }, null, 2)
+                            }]
+                    };
                 }
                 default:
                     throw new Error(`Unknown tool: ${name}`);
             }
         }
         catch (error) {
+            const payload = {
+                error: error instanceof Error ? error.message : "Unknown error",
+            };
+            if (error instanceof DenialError) {
+                payload.denial = error.denial;
+            }
             return {
-                content: [{
-                        type: 'text',
-                        text: JSON.stringify({
-                            error: error instanceof Error ? error.message : 'Unknown error'
-                        }, null, 2)
-                    }],
-                isError: true
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(payload, null, 2),
+                    },
+                ],
+                isError: true,
             };
         }
     });
-    return { server, clientSessions };
+    return {
+        server,
+        clientSessions,
+        reloadConfig: (result) => {
+            capabilities = result.capabilities;
+            services = result.services;
+        },
+    };
 }
 /**
  * Make HTTP/HTTPS request to real API
  */
 function makeAPIRequest(targetUrl, request) {
     return new Promise((resolve, reject) => {
-        const client = targetUrl.protocol === 'https:' ? https_1.default : http_1.default;
+        const client = targetUrl.protocol === "https:" ? https_1.default : http_1.default;
         const options = {
             hostname: targetUrl.hostname,
             port: targetUrl.port,
             path: targetUrl.pathname + targetUrl.search,
             method: request.method,
             headers: {
-                'User-Agent': 'janee/' + pkgVersion,
-                ...request.headers
-            }
+                "User-Agent": "janee/" + pkgVersion,
+                ...request.headers,
+            },
         };
         const req = client.request(options, (res) => {
-            let body = '';
-            res.on('data', (chunk) => {
+            let body = "";
+            res.on("data", (chunk) => {
                 body += chunk;
             });
-            res.on('end', () => {
+            res.on("end", () => {
                 resolve({
                     statusCode: res.statusCode || 500,
                     headers: res.headers,
-                    body
+                    body,
                 });
             });
         });
-        req.on('error', (error) => {
+        req.on("error", (error) => {
             reject(error);
         });
         if (request.body) {
@@ -597,8 +956,8 @@ function makeAPIRequest(targetUrl, request) {
 function captureClientInfo(transport, clientSessions) {
     const original = transport.onmessage;
     transport.onmessage = (message, extra) => {
-        if (message?.method === 'initialize' && message?.params?.clientInfo?.name) {
-            const key = extra?.sessionId || '__default__';
+        if (message?.method === "initialize" && message?.params?.clientInfo?.name) {
+            const key = extra?.sessionId || "__default__";
             clientSessions.set(key, message.params.clientInfo.name);
         }
         return original?.call(transport, message, extra);
@@ -608,11 +967,13 @@ function captureClientInfo(transport, clientSessions) {
  * Start MCP server with stdio transport (single session).
  */
 async function startMCPServer(serverOptions) {
-    const { server, clientSessions } = createMCPServer(serverOptions);
+    const mcpResult = createMCPServer(serverOptions);
+    const { server, clientSessions } = mcpResult;
     const transport = new stdio_js_1.StdioServerTransport();
     await server.connect(transport);
     captureClientInfo(transport, clientSessions);
-    console.error('Janee MCP server started (stdio)');
+    console.error("Janee MCP server started (stdio)");
+    return mcpResult;
 }
 /**
  * Start MCP server with StreamableHTTP transport over HTTP.
@@ -633,72 +994,103 @@ async function startMCPServerHTTP(serverOptions, httpOptions) {
     const sessions = new Map();
     // Authority REST endpoints -- active when runnerKey is provided
     if (httpOptions.runnerKey && httpOptions.authorityHooks) {
-        const { timingSafeEqual } = await Promise.resolve().then(() => __importStar(require('crypto')));
+        const { timingSafeEqual } = await Promise.resolve().then(() => __importStar(require("crypto")));
         const runnerKey = httpOptions.runnerKey;
         const hooks = httpOptions.authorityHooks;
         const authMiddleware = (req, res, next) => {
-            const provided = req.header('x-janee-runner-key');
-            if (!provided || provided.length !== runnerKey.length ||
+            const provided = req.header("x-janee-runner-key");
+            if (!provided ||
+                provided.length !== runnerKey.length ||
                 !timingSafeEqual(Buffer.from(provided), Buffer.from(runnerKey))) {
-                res.status(401).json({ error: 'Unauthorized runner request' });
+                res.status(401).json({ error: "Unauthorized runner request" });
                 return;
             }
             next();
         };
-        app.get('/v1/health', (_req, res) => {
-            res.status(200).json({ ok: true, mode: 'authority' });
+        app.get("/v1/health", (_req, res) => {
+            res.status(200).json({ ok: true, mode: "authority" });
         });
-        app.post('/v1/exec/authorize', authMiddleware, async (req, res) => {
+        app.post("/v1/exec/authorize", authMiddleware, async (req, res) => {
             try {
                 const body = req.body;
-                if (!body?.runner?.runnerId || !Array.isArray(body?.command) || body.command.length === 0 || !body.capabilityId) {
-                    res.status(400).json({ error: 'Invalid authorize request' });
+                if (!body?.runner?.runnerId ||
+                    !Array.isArray(body?.command) ||
+                    body.command.length === 0 ||
+                    !body.capabilityId) {
+                    res.status(400).json({ error: "Invalid authorize request" });
                     return;
                 }
                 const response = await hooks.authorizeExec(body);
                 res.status(200).json(response);
             }
             catch (error) {
-                res.status(403).json({ error: error instanceof Error ? error.message : 'Authorization failed' });
+                res
+                    .status(403)
+                    .json({
+                    error: error instanceof Error ? error.message : "Authorization failed",
+                });
             }
         });
-        app.post('/v1/exec/complete', authMiddleware, async (req, res) => {
+        app.post("/v1/exec/complete", authMiddleware, async (req, res) => {
             try {
                 if (!req.body?.grantId) {
-                    res.status(400).json({ error: 'grantId is required' });
+                    res.status(400).json({ error: "grantId is required" });
                     return;
                 }
                 await hooks.completeExec(req.body);
                 res.status(200).json({ ok: true });
             }
             catch (error) {
-                res.status(500).json({ error: error instanceof Error ? error.message : 'completion failed' });
+                res
+                    .status(500)
+                    .json({
+                    error: error instanceof Error ? error.message : "completion failed",
+                });
             }
         });
-    }
-    // Sweep idle sessions every 60 seconds
-    const idleSweepInterval = idleTimeoutMs > 0 ? setInterval(async () => {
-        const now = Date.now();
-        for (const [sid, session] of sessions.entries()) {
-            if (now - session.lastActivityAt > idleTimeoutMs) {
-                console.error(`Closing idle session ${sid} (inactive for ${Math.round((now - session.lastActivityAt) / 1000)}s)`);
-                sessions.delete(sid);
+        if (hooks.testService) {
+            app.post("/v1/test", authMiddleware, async (req, res) => {
                 try {
-                    await session.transport.close?.();
-                    await session.server.close();
+                    const result = await hooks.testService(req.body?.service, {
+                        timeout: req.body?.timeout,
+                    });
+                    res.status(200).json(result);
                 }
-                catch {
-                    // best-effort cleanup
+                catch (error) {
+                    res
+                        .status(500)
+                        .json({
+                        error: error instanceof Error ? error.message : "Test failed",
+                    });
                 }
-            }
+            });
         }
-    }, Math.min(idleTimeoutMs, 60_000)) : undefined;
+    }
+    // Sweep idle sessions every 60 seconds
+    const idleSweepInterval = idleTimeoutMs > 0
+        ? setInterval(async () => {
+            const now = Date.now();
+            for (const [sid, session] of sessions.entries()) {
+                if (now - session.lastActivityAt > idleTimeoutMs) {
+                    console.error(`Closing idle session ${sid} (inactive for ${Math.round((now - session.lastActivityAt) / 1000)}s)`);
+                    sessions.delete(sid);
+                    try {
+                        await session.transport.close?.();
+                        await session.server.close();
+                    }
+                    catch {
+                        // best-effort cleanup
+                    }
+                }
+            }
+        }, Math.min(idleTimeoutMs, 60_000))
+        : undefined;
     if (idleSweepInterval) {
         idleSweepInterval.unref?.(); // Don't prevent Node from exiting
     }
-    app.all('/mcp', async (req, res) => {
+    app.all("/mcp", async (req, res) => {
         try {
-            const sessionId = req.headers['mcp-session-id'];
+            const sessionId = req.headers["mcp-session-id"];
             if (sessionId && sessions.has(sessionId)) {
                 const session = sessions.get(sessionId);
                 session.lastActivityAt = Date.now();
@@ -706,11 +1098,16 @@ async function startMCPServerHTTP(serverOptions, httpOptions) {
             }
             else if (!sessionId && (0, types_js_1.isInitializeRequest)(req.body)) {
                 const clientName = req.body?.params?.clientInfo?.name;
-                const { server, clientSessions } = createMCPServer(serverOptions);
+                const mcpResult = createMCPServer(serverOptions);
+                const { server, clientSessions } = mcpResult;
                 const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
                     sessionIdGenerator: () => crypto.randomUUID(),
                     onsessioninitialized: (sid) => {
-                        sessions.set(sid, { transport, server, lastActivityAt: Date.now() });
+                        sessions.set(sid, {
+                            transport,
+                            server,
+                            lastActivityAt: Date.now(),
+                        });
                         if (clientName)
                             clientSessions.set(sid, clientName);
                     },
@@ -730,25 +1127,28 @@ async function startMCPServerHTTP(serverOptions, httpOptions) {
             }
             else if (sessionId) {
                 res.status(404).json({
-                    jsonrpc: '2.0',
-                    error: { code: -32001, message: 'Session not found' },
+                    jsonrpc: "2.0",
+                    error: { code: -32001, message: "Session not found" },
                     id: null,
                 });
             }
             else {
                 res.status(400).json({
-                    jsonrpc: '2.0',
-                    error: { code: -32600, message: 'Bad Request: Missing session ID or not an initialize request' },
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32600,
+                        message: "Bad Request: Missing session ID or not an initialize request",
+                    },
                     id: null,
                 });
             }
         }
         catch (error) {
-            console.error('Error handling MCP request:', error);
+            console.error("Error handling MCP request:", error);
             if (!res.headersSent) {
                 res.status(500).json({
-                    jsonrpc: '2.0',
-                    error: { code: -32603, message: 'Internal server error' },
+                    jsonrpc: "2.0",
+                    error: { code: -32603, message: "Internal server error" },
                     id: null,
                 });
             }