agentic-qe 3.10.0 → 3.10.2

package/dist/mcp/protocol-server.js

@@ -5,7 +5,7 @@
  *
  * ADR-039: Integrated with connection pooling, load balancing, and performance monitoring
  */
-import { createStdioTransport, JSON_RPC_ERRORS, } from './transport';
+import { createStdioTransport, JSON_RPC_ERRORS, isJsonRpcCodedError, McpError, } from './transport';
 import { createToolRegistry } from './tool-registry';
 import { MiddlewareChain } from './middleware/middleware-chain';
 import { createMicrocompactMiddleware } from './middleware/microcompact';
@@ -156,7 +156,15 @@ export class MCPProtocolServer {
                 return await this.handleRequest(request);
             }
             catch (err) {
-                // Last-resort safety net: catch anything that escapes handleToolsCall
+                // Errors that carry a JSON-RPC `code` (e.g. METHOD_NOT_FOUND for an
+                // unknown tool/method — thrown as McpError or a legacy plain
+                // `{ code, message }` object) are real protocol errors: re-throw so the
+                // transport serializes them as a proper JSON-RPC error response with the
+                // correct code/message, instead of flattening to "[object Object]".
+                if (isJsonRpcCodedError(err)) {
+                    throw err;
+                }
+                // Last-resort safety net: catch anything else that escapes handleToolsCall
                 // to prevent MCP connection from being killed (-32000)
                 const message = err instanceof Error ? err.message : String(err);
                 console.error(`[MCP] Unhandled error in request handler: ${message}`);
@@ -307,10 +315,7 @@ export class MCPProtocolServer {
                 return { pong: true };
             // Unknown method
             default:
-                throw {
-                    code: JSON_RPC_ERRORS.METHOD_NOT_FOUND,
-                    message: `Unknown method: ${method}`,
-                };
+                throw new McpError(JSON_RPC_ERRORS.METHOD_NOT_FOUND, `Unknown method: ${method}`);
         }
     }
     async handleNotification(notification) {
@@ -333,10 +338,7 @@ export class MCPProtocolServer {
     // ============================================================================
     async handleInitialize(params) {
         if (this.initialized) {
-            throw {
-                code: JSON_RPC_ERRORS.INVALID_REQUEST,
-                message: 'Server already initialized',
-            };
+            throw new McpError(JSON_RPC_ERRORS.INVALID_REQUEST, 'Server already initialized');
         }
         // Store client info
         if (params.clientInfo) {
@@ -371,10 +373,7 @@ export class MCPProtocolServer {
         const { name, arguments: args = {} } = params;
         const tool = this.tools.get(name);
         if (!tool) {
-            throw {
-                code: JSON_RPC_ERRORS.METHOD_NOT_FOUND,
-                message: `Unknown tool: ${name}`,
-            };
+            throw new McpError(JSON_RPC_ERRORS.METHOD_NOT_FOUND, `Unknown tool: ${name}`);
         }
         // ADR-039: Track tool invocation with performance monitoring
         const startTime = performance.now();

package/dist/mcp/qe-tool-bridge.js

@@ -75,7 +75,14 @@ export function registerMissingQETools(registerFn) {
                 parameters: schemaToParameters(tool),
             },
             handler: async (params) => {
-                const result = await tool.invoke(params);
+                // ADR-043: explicitly forward the shared HybridRouter (registered
+                // by QEKernelImpl during initialize() in production, or built
+                // lazily for MCP-only contexts) so the MCPToolContext.llmRouter
+                // field carries the actual instance rather than relying on each
+                // tool's getLLMRouter(context) singleton fallback.
+                const { getSharedLLMRouter } = await import('./tools/base.js');
+                const llmRouter = (await getSharedLLMRouter()) ?? undefined;
+                const result = await tool.invoke(params, { llmRouter });
                 return result;
             },
         };

package/dist/mcp/tools/base.d.ts

@@ -26,6 +26,41 @@ export declare function resetSharedMemoryBackend(): void;
  * Get memory backend from context or create shared one
  */
 export declare function getMemoryBackend(context?: MCPToolContext): Promise<MemoryBackend>;
+/**
+ * Register an externally-built HybridRouter as the shared singleton.
+ * Called by QEKernelImpl during initialize() so kernel-mode and MCP-mode
+ * tools share the same router instance. Idempotent — calling with the
+ * same router twice is a no-op; calling with a different router
+ * replaces the previous one (and any in-flight lazy init is cancelled
+ * for next-read semantics).
+ */
+export declare function setSharedLLMRouter(router: import('../../shared/llm/router/hybrid-router.js').HybridRouter): void;
+/**
+ * Get or create the shared HybridRouter for standalone MCP tools that
+ * construct their service directly (without going through the kernel /
+ * plugin chain that Phase 2 wired up).
+ *
+ * Returns null when:
+ *   - AQE_LLM_ROUTER_DISABLED env kill-switch is set, OR
+ *   - no provider key is in env and the project has no llm-config.json
+ *
+ * Callers MUST tolerate a null return value and fall back to
+ * deterministic-only behavior in that case.
+ *
+ * Resets via `resetSharedLLMRouter()` for tests.
+ */
+export declare function getSharedLLMRouter(): Promise<import('../../shared/llm/router/hybrid-router.js').HybridRouter | null>;
+/**
+ * Reset the shared LLM router singleton. For tests.
+ */
+export declare function resetSharedLLMRouter(): void;
+/**
+ * Get LLM router from context or shared singleton. Returns undefined
+ * (not null) when no router is available, so it can be spread directly
+ * into a `{ memory, llmRouter }` dependency bag without contaminating
+ * the value.
+ */
+export declare function getLLMRouter(context?: MCPToolContext): Promise<import('../../shared/llm/router/hybrid-router.js').HybridRouter | undefined>;
 /**
  * JSON Schema property definition for tool parameters
  */
@@ -79,6 +114,13 @@ export interface MCPToolContext {
     demoMode?: boolean;
     /** Shared memory backend for persistent storage */
     memory?: import('../../kernel/interfaces').MemoryBackend;
+    /**
+     * ADR-043: HybridRouter for LLM-enhanced analysis. Standalone MCP
+     * tools that construct services directly should fetch this via
+     * `getLLMRouter(context)` and pass it into the service dependency
+     * bag so isLLMAnalysisAvailable() returns true.
+     */
+    llmRouter?: import('../../shared/llm/router/hybrid-router.js').HybridRouter;
 }
 /**
  * Data source tracking for audit/transparency
@@ -167,6 +209,20 @@ export declare abstract class MCPToolBase<TParams extends Record<string, unknown
         abortSignal?: AbortSignal;
         /** Explicit demo mode - returns sample data without calling real services */
         demoMode?: boolean;
+        /**
+         * ADR-043: Optional memory backend injection. When provided, the
+         * context.memory field is populated and tools skip the shared
+         * singleton fallback.
+         */
+        memory?: import('../../kernel/interfaces').MemoryBackend;
+        /**
+         * ADR-043: Optional LLM router injection. When provided, the
+         * context.llmRouter field is populated so getLLMRouter(context)
+         * returns it directly — used by the MCP runtime to forward the
+         * kernel singleton without going through getSharedLLMRouter()'s
+         * lazy build path.
+         */
+        llmRouter?: import('../../shared/llm/router/hybrid-router.js').HybridRouter;
     }): Promise<ToolResult<TResult>>;
     /**
      * Create result metadata

package/dist/mcp/tools/base.js

@@ -97,6 +97,101 @@ export async function getMemoryBackend(context) {
     }
     return getSharedMemoryBackend();
 }
+// ============================================================================
+// Shared LLM Router for MCP Tools (ADR-043)
+// ============================================================================
+//
+// Two paths populate this singleton:
+//
+//   1. QEKernelImpl._initializeLLMRouter() calls setSharedLLMRouter() on
+//      boot, so kernel-mode AND MCP-mode share ONE HybridRouter — one
+//      cost tracker, one metrics collector, one provider circuit breaker.
+//      This is the production path.
+//
+//   2. Pure-MCP processes (no kernel — e.g. standalone CLI invocations
+//      that go directly through the MCP tool surface) lazily construct
+//      a router on first getSharedLLMRouter() call. Subordinate to (1).
+//
+// AQE_LLM_ROUTER_DISABLED env kill-switch is honored in both paths so a
+// user can opt out without code changes.
+let sharedLLMRouter = null;
+let llmRouterInitPromise = null;
+/**
+ * Returns true when the AQE_LLM_ROUTER_DISABLED env kill-switch is set.
+ * Honors '1', 'true', 'yes', 'on'; ignores '', '0', 'false', 'no', 'off'.
+ */
+function isRouterKillSwitchSet() {
+    const v = (process.env.AQE_LLM_ROUTER_DISABLED ?? '').trim().toLowerCase();
+    if (!v)
+        return false;
+    return v !== 'false' && v !== '0' && v !== 'no' && v !== 'off';
+}
+/**
+ * Register an externally-built HybridRouter as the shared singleton.
+ * Called by QEKernelImpl during initialize() so kernel-mode and MCP-mode
+ * tools share the same router instance. Idempotent — calling with the
+ * same router twice is a no-op; calling with a different router
+ * replaces the previous one (and any in-flight lazy init is cancelled
+ * for next-read semantics).
+ */
+export function setSharedLLMRouter(router) {
+    sharedLLMRouter = router;
+    llmRouterInitPromise = null;
+}
+/**
+ * Get or create the shared HybridRouter for standalone MCP tools that
+ * construct their service directly (without going through the kernel /
+ * plugin chain that Phase 2 wired up).
+ *
+ * Returns null when:
+ *   - AQE_LLM_ROUTER_DISABLED env kill-switch is set, OR
+ *   - no provider key is in env and the project has no llm-config.json
+ *
+ * Callers MUST tolerate a null return value and fall back to
+ * deterministic-only behavior in that case.
+ *
+ * Resets via `resetSharedLLMRouter()` for tests.
+ */
+export async function getSharedLLMRouter() {
+    if (isRouterKillSwitchSet()) {
+        return null;
+    }
+    if (sharedLLMRouter) {
+        return sharedLLMRouter;
+    }
+    if (llmRouterInitPromise) {
+        return llmRouterInitPromise;
+    }
+    llmRouterInitPromise = (async () => {
+        const { createLLMRouterService } = await import('../../shared/llm/llm-router-service.js');
+        const built = await createLLMRouterService();
+        if (!built)
+            return null;
+        sharedLLMRouter = built.router;
+        return sharedLLMRouter;
+    })();
+    return llmRouterInitPromise;
+}
+/**
+ * Reset the shared LLM router singleton. For tests.
+ */
+export function resetSharedLLMRouter() {
+    sharedLLMRouter = null;
+    llmRouterInitPromise = null;
+}
+/**
+ * Get LLM router from context or shared singleton. Returns undefined
+ * (not null) when no router is available, so it can be spread directly
+ * into a `{ memory, llmRouter }` dependency bag without contaminating
+ * the value.
+ */
+export async function getLLMRouter(context) {
+    if (context?.llmRouter) {
+        return context.llmRouter;
+    }
+    const shared = await getSharedLLMRouter();
+    return shared ?? undefined;
+}
 /**
  * Default console logger
  */
@@ -245,7 +340,13 @@ export class MCPToolBase {
                 metadata: this.createMetadata(startTime, requestId),
             };
         }
-        // Create execution context
+        // Create execution context.
+        // ADR-043: memory + llmRouter are populated from invoke() options so
+        // the MCP runtime (qe-tool-bridge, registry, daemon) can forward the
+        // kernel singleton explicitly rather than relying on the shared
+        // singleton fallback. When unset, getLLMRouter(context) falls back
+        // to getSharedLLMRouter() — which itself is kernel-aware via
+        // setSharedLLMRouter() registered during kernel.initialize().
         const context = {
             requestId,
             startTime,
@@ -253,6 +354,8 @@ export class MCPToolBase {
             onStream: options.onStream,
             abortSignal: options.abortSignal,
             demoMode: options.demoMode,
+            memory: options.memory,
+            llmRouter: options.llmRouter,
         };
         try {
             // Execute the tool

package/dist/mcp/tools/chaos-resilience/inject.js

@@ -7,7 +7,7 @@
  * - ChaosEngineerService for fault injection and experiment execution
  */
 import { v4 as uuidv4 } from 'uuid';
-import { MCPToolBase, getSharedMemoryBackend } from '../base.js';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base.js';
 import { ChaosEngineerService } from '../../../domains/chaos-resilience/services/chaos-engineer.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 // ============================================================================
@@ -26,7 +26,9 @@ export class ChaosInjectTool extends MCPToolBase {
     async getService(context) {
         if (!this.chaosEngineer) {
             const memory = context.memory || await getSharedMemoryBackend();
-            this.chaosEngineer = new ChaosEngineerService({ memory }, {
+            // ADR-043 wiring.
+            const llmRouter = await getLLMRouter(context);
+            this.chaosEngineer = new ChaosEngineerService({ memory, llmRouter }, {
                 enableDryRun: true,
                 autoRollbackOnFailure: true,
             });

package/dist/mcp/tools/code-intelligence/analyze.js

@@ -8,7 +8,7 @@
  * - SemanticAnalyzerService for semantic code search
  * - ImpactAnalyzerService for change impact analysis
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base';
 import { KnowledgeGraphService } from '../../../domains/code-intelligence/services/knowledge-graph';
 import { SemanticAnalyzerService } from '../../../domains/code-intelligence/services/semantic-analyzer';
 import { ImpactAnalyzerService } from '../../../domains/code-intelligence/services/impact-analyzer';
@@ -35,8 +35,10 @@ export class CodeAnalyzeTool extends MCPToolBase {
      */
     async getKnowledgeGraph(context) {
         if (!this.knowledgeGraph) {
-            const memory = context.memory;
-            this.knowledgeGraph = new KnowledgeGraphService(memory || await getSharedMemoryBackend());
+            // ADR-043 wiring.
+            const memory = context.memory ?? await getSharedMemoryBackend();
+            const llmRouter = await getLLMRouter(context);
+            this.knowledgeGraph = new KnowledgeGraphService({ memory, llmRouter });
         }
         return this.knowledgeGraph;
     }

package/dist/mcp/tools/contract-testing/validate.js

@@ -7,7 +7,7 @@
  * - ContractValidatorService for contract/schema validation
  * - ApiCompatibilityService for breaking change detection
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base.js';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base.js';
 import { safeJsonParse } from '../../../shared/safe-json.js';
 import { Version } from '../../../shared/value-objects/index.js';
 import { ContractValidatorService } from '../../../domains/contract-testing/services/contract-validator.js';
@@ -67,7 +67,9 @@ export class ContractValidateTool extends MCPToolBase {
     async getServices(context) {
         if (!this.contractValidator || !this.apiCompatibility) {
             const memory = context.memory || await getSharedMemoryBackend();
-            this.contractValidator = new ContractValidatorService({ memory });
+            // ADR-043 wiring.
+            const llmRouter = await getLLMRouter(context);
+            this.contractValidator = new ContractValidatorService({ memory, llmRouter });
             this.apiCompatibility = new ApiCompatibilityService(memory);
         }
         return {

package/dist/mcp/tools/coverage-analysis/index.js

@@ -7,7 +7,7 @@
  * This module wraps the REAL coverage-analysis domain services.
  * Uses actual LCOV/JSON parsing and vector-based gap detection.
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base';
 import { CoverageAnalyzerService } from '../../../domains/coverage-analysis/services/coverage-analyzer';
 import { GapDetectorService } from '../../../domains/coverage-analysis/services/gap-detector';
 import { findAndParseCoverage, parseCoverage, } from '../../../domains/coverage-analysis/services/coverage-parser';
@@ -83,8 +83,12 @@ export class CoverageAnalyzeTool extends MCPToolBase {
     analyzerService = null;
     async getService(context) {
         if (!this.analyzerService) {
-            const memory = context.memory;
-            this.analyzerService = new CoverageAnalyzerService(memory || await getSharedMemoryBackend());
+            // ADR-043 wiring: pull the shared HybridRouter (returns undefined
+            // when no provider key is present) so isLLMAnalysisAvailable()
+            // returns true in MCP mode the same way it does in kernel mode.
+            const memory = context.memory ?? await getSharedMemoryBackend();
+            const llmRouter = await getLLMRouter(context);
+            this.analyzerService = new CoverageAnalyzerService({ memory, llmRouter });
         }
         return this.analyzerService;
     }
@@ -296,8 +300,10 @@ export class CoverageGapsTool extends MCPToolBase {
     gapService = null;
     async getService(context) {
         if (!this.gapService) {
-            const memory = context.memory;
-            this.gapService = new GapDetectorService(memory || await getSharedMemoryBackend());
+            // ADR-043 wiring.
+            const memory = context.memory ?? await getSharedMemoryBackend();
+            const llmRouter = await getLLMRouter(context);
+            this.gapService = new GapDetectorService({ memory, llmRouter });
         }
         return this.gapService;
     }

package/dist/mcp/tools/defect-intelligence/predict.js

@@ -6,7 +6,7 @@
  * This tool wraps the REAL defect-intelligence domain service.
  * Uses actual code analysis, git history, and weighted feature prediction.
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base';
 import { DefectPredictorService } from '../../../domains/defect-intelligence/services/defect-predictor';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 // ============================================================================
@@ -44,15 +44,10 @@ export class DefectPredictTool extends MCPToolBase {
      */
     async getService(context) {
         if (!this.predictorService) {
-            // Create a memory backend from context or use shared persistent backend
-            const memory = context.memory;
-            if (memory) {
-                this.predictorService = new DefectPredictorService(memory);
-            }
-            else {
-                // Use shared persistent memory backend
-                this.predictorService = new DefectPredictorService(await getSharedMemoryBackend());
-            }
+            // ADR-043 wiring.
+            const memory = context.memory ?? await getSharedMemoryBackend();
+            const llmRouter = await getLLMRouter(context);
+            this.predictorService = new DefectPredictorService({ memory, llmRouter });
         }
         return this.predictorService;
     }

package/dist/mcp/tools/learning-optimization/optimize.js

@@ -8,7 +8,7 @@
  * - MetricsOptimizerService for strategy optimization
  * - TransferSpecialistService for knowledge transfer
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base.js';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base.js';
 import { TimeRange } from '../../../shared/value-objects/index.js';
 import { LearningCoordinatorService } from '../../../domains/learning-optimization/services/learning-coordinator.js';
 import { MetricsOptimizerService } from '../../../domains/learning-optimization/services/metrics-optimizer.js';
@@ -33,7 +33,9 @@ export class LearningOptimizeTool extends MCPToolBase {
     async getServices(context) {
         if (!this.learningCoordinator || !this.metricsOptimizer || !this.transferSpecialist) {
             const memory = context.memory || await getSharedMemoryBackend();
-            this.learningCoordinator = new LearningCoordinatorService({ memory });
+            // ADR-043 wiring.
+            const llmRouter = await getLLMRouter(context);
+            this.learningCoordinator = new LearningCoordinatorService({ memory, llmRouter });
             this.metricsOptimizer = new MetricsOptimizerService(memory);
             this.transferSpecialist = new TransferSpecialistService(memory);
         }

package/dist/mcp/tools/registry.js

@@ -166,7 +166,14 @@ export function registerAllQETools(registry) {
             category: 'domain',
             domain: tool.domain,
             lazyLoad: false, // QE tools are always available
-        }, async (params) => tool.invoke(params));
+        }, 
+        // ADR-043: forward the shared HybridRouter so the tool's
+        // MCPToolContext.llmRouter is populated explicitly.
+        async (params) => {
+            const { getSharedLLMRouter } = await import('./base.js');
+            const llmRouter = (await getSharedLLMRouter()) ?? undefined;
+            return tool.invoke(params, { llmRouter });
+        });
     }
 }
 /**

package/dist/mcp/tools/test-generation/generate.js

@@ -6,8 +6,8 @@
  * This tool wraps the test-generation domain service and exposes it via MCP.
  * Supports unit, integration, and e2e test generation with AI enhancement.
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base';
-import { createTestGeneratorService } from '../../../domains/test-generation/services/test-generator';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base';
+import { createTestGeneratorServiceWithDependencies } from '../../../domains/test-generation/services/test-generator';
 import { TokenOptimizerService } from '../../../optimization/token-optimizer-service.js';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 // ============================================================================
@@ -27,10 +27,13 @@ export class TestGenerateTool extends MCPToolBase {
      * Initialize or get the test generator service with persistent storage
      * Uses factory function for proper dependency injection
      */
-    async getService() {
+    async getService(context) {
         if (!this.testGeneratorService) {
+            // ADR-043 wiring: dependencies factory accepts llmRouter so the
+            // ADR-051 LLM-enhanced generation branch is reachable in MCP mode.
             const memory = await getSharedMemoryBackend();
-            this.testGeneratorService = createTestGeneratorService(memory, {
+            const llmRouter = await getLLMRouter(context);
+            this.testGeneratorService = createTestGeneratorServiceWithDependencies({ memory, llmRouter }, {
                 defaultFramework: 'vitest',
                 maxTestsPerFile: 50,
                 coverageTargetDefault: 80,
@@ -71,8 +74,9 @@ export class TestGenerateTool extends MCPToolBase {
                         `saving ~${earlyExitResult.estimatedTokensSaved} tokens`);
                 }
             }
-            // Get the domain service and call it with the request
-            const service = await this.getService();
+            // Get the domain service and call it with the request.
+            // Pass context so ADR-043 llmRouter reaches the service.
+            const service = await this.getService(context);
             // Build the domain request from MCP params
             const domainRequest = {
                 sourceFiles,

package/dist/mcp/tools/visual-accessibility/index.js

@@ -8,8 +8,8 @@
  * - VisualTesterService for screenshot capture and comparison
  * - AccessibilityTesterService for WCAG compliance auditing
  */
-import { MCPToolBase, getSharedMemoryBackend } from '../base';
-import { createVisualTesterService } from '../../../domains/visual-accessibility/services/visual-tester';
+import { MCPToolBase, getSharedMemoryBackend, getLLMRouter } from '../base';
+import { createVisualTesterServiceWithDependencies } from '../../../domains/visual-accessibility/services/visual-tester';
 import { AccessibilityTesterService } from '../../../domains/visual-accessibility/services/accessibility-tester';
 import { toErrorMessage } from '../../../shared/error-utils.js';
 // ============================================================================
@@ -30,8 +30,11 @@ export class VisualCompareTool extends MCPToolBase {
      */
     async getService(context) {
         if (!this.visualTester) {
-            const memory = context.memory;
-            this.visualTester = createVisualTesterService(memory || await getSharedMemoryBackend());
+            // ADR-043 wiring: dependencies factory accepts llmRouter so the
+            // ADR-051 LLM-enhanced visual analysis branch is reachable in MCP mode.
+            const memory = context.memory ?? await getSharedMemoryBackend();
+            const llmRouter = await getLLMRouter(context);
+            this.visualTester = createVisualTesterServiceWithDependencies({ memory, llmRouter });
         }
         return this.visualTester;
     }

package/dist/mcp/transport/stdio.d.ts

@@ -43,6 +43,26 @@ export declare const JSON_RPC_ERRORS: {
     readonly INTERNAL_ERROR: -32603;
     readonly SERVER_ERROR: -32000;
 };
+/**
+ * Error subclass that carries a JSON-RPC error `code` so it can be surfaced as a
+ * proper JSON-RPC error response (instead of being flattened to "[object Object]").
+ * Mirrors the OAuthProviderError pattern used in the security layer.
+ */
+export declare class McpError extends Error {
+    readonly code: number;
+    readonly data?: unknown | undefined;
+    constructor(code: number, message: string, data?: unknown | undefined);
+}
+/**
+ * Type guard for any thrown value that carries a JSON-RPC `code` + `message`.
+ * Accepts both the McpError subclass and legacy plain `{ code, message }` objects
+ * so existing throw sites continue to map to the right JSON-RPC error code.
+ */
+export declare function isJsonRpcCodedError(err: unknown): err is {
+    code: number;
+    message: string;
+    data?: unknown;
+};
 export declare class StdioTransport {
     private readonly inputStream;
     private readonly outputStream;

package/dist/mcp/transport/stdio.js

@@ -16,6 +16,32 @@ export const JSON_RPC_ERRORS = {
     INTERNAL_ERROR: -32603,
     SERVER_ERROR: -32000,
 };
+/**
+ * Error subclass that carries a JSON-RPC error `code` so it can be surfaced as a
+ * proper JSON-RPC error response (instead of being flattened to "[object Object]").
+ * Mirrors the OAuthProviderError pattern used in the security layer.
+ */
+export class McpError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.code = code;
+        this.data = data;
+        this.name = 'McpError';
+    }
+}
+/**
+ * Type guard for any thrown value that carries a JSON-RPC `code` + `message`.
+ * Accepts both the McpError subclass and legacy plain `{ code, message }` objects
+ * so existing throw sites continue to map to the right JSON-RPC error code.
+ */
+export function isJsonRpcCodedError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        typeof err.code === 'number' &&
+        typeof err.message === 'string');
+}
 // ============================================================================
 // Stdio Transport Implementation
 // ============================================================================
@@ -205,8 +231,15 @@ export class StdioTransport {
             });
         }
         catch (err) {
-            const error = err;
-            await this.sendError(request.id, JSON_RPC_ERRORS.INTERNAL_ERROR, error.message || 'Internal error');
+            // Honor a JSON-RPC `code` carried by the thrown value (McpError or a legacy
+            // plain `{ code, message }` object); otherwise fall back to INTERNAL_ERROR.
+            if (isJsonRpcCodedError(err)) {
+                await this.sendError(request.id, err.code, err.message, err.data);
+            }
+            else {
+                const error = err;
+                await this.sendError(request.id, JSON_RPC_ERRORS.INTERNAL_ERROR, error.message || 'Internal error');
+            }
         }
     }
     async handleNotification(notification) {