@mhingston5/conduit 1.0.0 → 1.1.1

package/README.md

@@ -6,17 +6,18 @@
 
 <div align="center">
 
-[![npm version](https://badge.fury.io/js/@mhingston5%2Fconduit.svg)](https://www.npmjs.com/package/@mhingston/conduit)
+[![npm version](https://badge.fury.io/js/@mhingston5%2Fconduit.svg)](https://www.npmjs.com/package/@mhingston5/conduit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 [![Node.js Version](https://img.shields.io/badge/node-24-brightgreen.svg)](https://nodejs.org/)
 [![MCP](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io/)
+[![Standard MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/server)
 
 </div>
 
 ## What is Conduit?
 
-Conduit is a **secure Code Mode execution substrate** for [MCP](https://modelcontextprotocol.io/) agents.
+Conduit is a **secure Code Mode execution substrate** for [MCP](https://modelcontextprotocol.io/) agents. It functions as a **standard MCP server**, allowing native integration with clients like Claude Desktop or VS Code without extra adapters.
 
 It lets agents:
 - generate **real TypeScript or Python code**
@@ -94,6 +95,28 @@ Conduit runs the code, handles the tool call securely, and returns:
 }
 ```
 
+---
+
+## Example usage with VS Code
+
+```json
+{
+  "mcpServers": {
+    "conduit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "@mhingston5/conduit",
+        "--stdio"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+
 ---
 
 ## How It Works (High Level)
@@ -152,6 +175,21 @@ By default, Conduit runs in **Permissive Mode** to allow easy exploration.
 - permissive mode for exploration
 - strict mode for production agents
 
+## Code Mode Prompting Guide
+
+To get the most out of Conduit, you should guide your LLM (agent) to prefer multi-tool scripts over individual tool calls.
+
+**Recommended System Prompt Additions:**
+> You are equipped with a "Code Mode" execution environment via Conduit.
+>
+> - **Prefer `mcp.executeTypeScript`**: Use this for any task requiring multiple steps, data transformation, or logical branching.
+> - **Use `tools.*` SDK**: Within your scripts, access all upstream tools via the `tools` namespace (e.g., `await tools.github.create_issue(...)`).
+> - **Avoid JSON tool-calling overhead**: Instead of making 5 separate tool calls and waiting for 5 round-trips, write one script that orchestrates the entire operation.
+> - **Data Transformation**: Perform loops, filters, and aggregations directly in your code rather than asking the user (or yourself) to process large datasets in the chat context.
+
+Example of a high-efficiency prompt:
+*"Scan the last 50 emails for invoices, total their amounts by currency, and create a single summary ticket in Jira if the total exceeds $1000."*
+
 ---
 
 ## Design Principles

package/conduit.yaml

@@ -0,0 +1,6 @@
+logLevel: info
+upstreams:
+  - id: filesystem
+    type: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhingston5/conduit",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "description": "A secure Code Mode execution substrate for MCP agents",
   "main": "index.js",

package/src/core/config.service.ts

@@ -4,7 +4,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
 
+// Silence dotenv logging
+const originalWrite = process.stdout.write;
+// @ts-ignore
+process.stdout.write = () => true;
 dotenv.config();
+process.stdout.write = originalWrite;
 
 import { AppConfig } from './interfaces/app.config.js';
 
@@ -64,6 +69,7 @@ export const ConfigSchema = z.object({
     pyodideMaxPoolSize: z.number().default(3),
     metricsUrl: z.string().default('http://127.0.0.1:9464/metrics'),
     opsPort: z.number().optional(),
+    transport: z.enum(['socket', 'stdio']).default('socket'),
     upstreams: z.array(UpstreamInfoSchema).default([]),
 });
 
@@ -80,6 +86,8 @@ export class ConfigService {
             nodeEnv: process.env.NODE_ENV,
             logLevel: process.env.LOG_LEVEL,
             metricsUrl: process.env.METRICS_URL,
+            ipcBearerToken: process.env.IPC_BEARER_TOKEN,
+            transport: process.argv.includes('--stdio') ? 'stdio' : undefined,
             // upstreams: process.env.UPSTREAMS ? JSON.parse(process.env.UPSTREAMS) : undefined, // Removed per user request
         };
 
@@ -101,8 +109,12 @@ export class ConfigService {
         this.config = result.data as AppConfig;
 
         // Default opsPort if not set
-        if (!this.config.opsPort) {
-            this.config.opsPort = this.config.port === 0 ? 0 : this.config.port + 1;
+        if (this.config.opsPort === undefined) {
+            if (this.config.transport === 'stdio') {
+                this.config.opsPort = 0; // Random port for stdio to avoid conflicts
+            } else {
+                this.config.opsPort = this.config.port === 0 ? 0 : this.config.port + 1;
+            }
         }
     }
 

package/src/core/execution.service.ts

@@ -1,14 +1,14 @@
 import { Logger } from 'pino';
 import { ExecutorRegistry } from './registries/executor.registry.js';
-import { ResourceLimits } from './config.service.js';
+import type { ResourceLimits } from './config.service.js';
 import { GatewayService } from '../gateway/gateway.service.js';
 import { SecurityService } from './security.service.js';
 import { SDKGenerator, toToolBinding } from '../sdk/index.js';
 import { ExecutionContext } from './execution.context.js';
 import { ConduitError } from './types.js';
-import { ExecutionResult } from './interfaces/executor.interface.js';
+import type { ExecutionResult } from './interfaces/executor.interface.js';
 
-export { ExecutionResult };
+export type { ExecutionResult };
 
 export class ExecutionService {
     private logger: Logger;

package/src/core/interfaces/app.config.ts

@@ -13,5 +13,6 @@ export interface AppConfig {
     pyodideMaxPoolSize: number;
     metricsUrl: string;
     opsPort?: number;
+    transport: 'socket' | 'stdio';
     upstreams?: UpstreamInfo[];
 }

package/src/core/interfaces/middleware.interface.ts

@@ -1,12 +1,12 @@
 import { ExecutionContext } from '../execution.context.js';
 import { JSONRPCRequest, JSONRPCResponse } from '../types.js';
 
-export type NextFunction = () => Promise<JSONRPCResponse>;
+export type NextFunction = () => Promise<JSONRPCResponse | null>;
 
 export interface Middleware {
     handle(
         request: JSONRPCRequest,
         context: ExecutionContext,
         next: NextFunction
-    ): Promise<JSONRPCResponse>;
+    ): Promise<JSONRPCResponse | null>;
 }

package/src/core/logger.ts

@@ -54,11 +54,12 @@ export function createLogger(configService: ConfigService) {
                 correlationId: store?.correlationId,
             };
         },
-        transport: configService.get('nodeEnv') === 'development' ? {
-            target: 'pino-pretty',
-            options: {
-                colorize: true,
-            }
-        } : undefined,
-    });
+        // In stdio mode, never use pino-pretty to avoid stdout pollution
+        transport: configService.get('transport') !== 'stdio' && configService.get('nodeEnv') === 'development'
+            ? { target: 'pino-pretty', options: { colorize: true } }
+            : undefined,
+    }, configService.get('transport') === 'stdio'
+        ? pino.destination(2) // Always write to stderr in stdio mode
+        : undefined
+    );
 }

package/src/core/middleware/auth.middleware.ts

@@ -10,11 +10,13 @@ export class AuthMiddleware implements Middleware {
         request: JSONRPCRequest,
         context: ExecutionContext,
         next: NextFunction
-    ): Promise<JSONRPCResponse> {
+    ): Promise<JSONRPCResponse | null> {
         const providedToken = request.auth?.bearerToken || '';
+        const masterToken = this.securityService.getIpcToken();
 
-        const isMaster = providedToken === this.securityService.getIpcToken();
-        const isSession = this.securityService.validateIpcToken(providedToken) && !isMaster;
+        // If no master token is set (stdio mode), treat all requests as master (auth disabled)
+        const isMaster = !masterToken || providedToken === masterToken;
+        const isSession = !isMaster && this.securityService.validateIpcToken(providedToken);
 
         if (!isMaster && !isSession) {
             return {
@@ -29,7 +31,7 @@ export class AuthMiddleware implements Middleware {
 
         // Strict scoping for session tokens
         if (isSession) {
-            const allowedMethods = ['mcp.discoverTools', 'mcp.callTool'];
+            const allowedMethods = ['initialize', 'notifications/initialized', 'mcp.discoverTools', 'mcp.callTool', 'ping'];
             if (!allowedMethods.includes(request.method)) {
                 return {
                     jsonrpc: '2.0',

package/src/core/middleware/error.middleware.ts

@@ -3,7 +3,7 @@ import { JSONRPCRequest, JSONRPCResponse, ConduitError } from '../types.js';
 import { ExecutionContext } from '../execution.context.js';
 
 export class ErrorHandlingMiddleware implements Middleware {
-    async handle(request: JSONRPCRequest, context: ExecutionContext, next: NextFunction): Promise<JSONRPCResponse> {
+    async handle(request: JSONRPCRequest, context: ExecutionContext, next: NextFunction): Promise<JSONRPCResponse | null> {
         try {
             return await next();
         } catch (err: any) {

package/src/core/middleware/logging.middleware.ts

@@ -4,7 +4,7 @@ import { ExecutionContext } from '../execution.context.js';
 import { metrics } from '../metrics.service.js';
 
 export class LoggingMiddleware implements Middleware {
-    async handle(request: JSONRPCRequest, context: ExecutionContext, next: NextFunction): Promise<JSONRPCResponse> {
+    async handle(request: JSONRPCRequest, context: ExecutionContext, next: NextFunction): Promise<JSONRPCResponse | null> {
         const { method, id } = request;
         const childLogger = context.logger.child({ method, id });
         context.logger = childLogger; // Update context logger for downstream

package/src/core/middleware/ratelimit.middleware.ts

@@ -10,7 +10,7 @@ export class RateLimitMiddleware implements Middleware {
         request: JSONRPCRequest,
         context: ExecutionContext,
         next: NextFunction
-    ): Promise<JSONRPCResponse> {
+    ): Promise<JSONRPCResponse | null> {
         const providedToken = request.auth?.bearerToken;
         // Use token if available, otherwise fallback to remote address from context
         const rateLimitKey = providedToken || context.remoteAddress || 'unknown';

package/src/core/ops.server.ts

@@ -57,7 +57,7 @@ export class OpsServer {
 
     async listen(): Promise<string> {
         // Use explicit opsPort from config
-        const port = this.config.opsPort || 3001;
+        const port = this.config.opsPort !== undefined ? this.config.opsPort : 3001;
         try {
             const address = await this.fastify.listen({ port, host: '0.0.0.0' });
             this.logger.info({ address }, 'Ops server listening');

package/src/core/request.controller.ts

@@ -7,9 +7,11 @@ import { ExecutionService } from './execution.service.js';
 
 import { Middleware } from './interfaces/middleware.interface.js';
 
-import { ConduitError, JSONRPCRequest, JSONRPCResponse } from './types.js';
+import { ConduitError } from './types.js';
+import type { JSONRPCRequest, JSONRPCResponse } from './types.js';
 
-export { ConduitError, JSONRPCRequest, JSONRPCResponse };
+export { ConduitError };
+export type { JSONRPCRequest, JSONRPCResponse };
 
 export class RequestController {
     private logger: Logger;
@@ -36,14 +38,14 @@ export class RequestController {
 
 
 
-    async handleRequest(request: JSONRPCRequest, context: ExecutionContext): Promise<JSONRPCResponse> {
+    async handleRequest(request: JSONRPCRequest, context: ExecutionContext): Promise<JSONRPCResponse | null> {
         return this.executePipeline(request, context);
     }
 
-    private async executePipeline(request: JSONRPCRequest, context: ExecutionContext): Promise<JSONRPCResponse> {
+    private async executePipeline(request: JSONRPCRequest, context: ExecutionContext): Promise<JSONRPCResponse | null> {
         let index = -1;
 
-        const dispatch = async (i: number): Promise<JSONRPCResponse> => {
+        const dispatch = async (i: number): Promise<JSONRPCResponse | null> => {
             if (i <= index) throw new Error('next() called multiple times');
             index = i;
 
@@ -90,7 +92,7 @@ export class RequestController {
         }
     }
 
-    private async finalHandler(request: JSONRPCRequest, context: ExecutionContext): Promise<JSONRPCResponse> {
+    private async finalHandler(request: JSONRPCRequest, context: ExecutionContext): Promise<JSONRPCResponse | null> {
         const { method, params, id } = request;
         // Logging and metrics handled by middlewares now
 
@@ -99,6 +101,7 @@ export class RequestController {
         // Or specific logic.
 
         switch (method) {
+            case 'tools/list': // Standard MCP method name
             case 'mcp.discoverTools':
                 return this.handleDiscoverTools(params, context, id);
             case 'mcp.listToolPackages':
@@ -117,6 +120,12 @@ export class RequestController {
                 return this.handleExecutePython(params, context, id);
             case 'mcp.executeIsolate':
                 return this.handleExecuteIsolate(params, context, id);
+            case 'initialize':
+                return this.handleInitialize(params, context, id);
+            case 'notifications/initialized':
+                return null; // Notifications don't get responses per MCP spec
+            case 'ping':
+                return { jsonrpc: '2.0', id, result: {} };
             default:
                 // metrics.recordExecutionEnd is handled by LoggingMiddleware??
                 // Wait, if 404, LoggingMiddleware records execution end?
@@ -127,11 +136,19 @@ export class RequestController {
 
     private async handleDiscoverTools(params: any, context: ExecutionContext, id: string | number): Promise<JSONRPCResponse> {
         const tools = await this.gatewayService.discoverTools(context);
+
+        // Filter to only MCP-standard fields for compatibility with strict clients
+        const standardizedTools = tools.map(t => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+        }));
+
         return {
             jsonrpc: '2.0',
             id,
             result: {
-                tools,
+                tools: standardizedTools,
             },
         };
     }
@@ -244,6 +261,31 @@ export class RequestController {
         };
     }
 
+    private async handleInitialize(params: any, context: ExecutionContext, id: string | number): Promise<JSONRPCResponse> {
+        // Echo back the client's protocol version for compatibility, or use latest if not provided
+        const clientVersion = params?.protocolVersion || '2025-06-18';
+        return {
+            jsonrpc: '2.0',
+            id,
+            result: {
+                protocolVersion: clientVersion,
+                capabilities: {
+                    tools: {
+                        listChanged: true
+                    },
+                    resources: {
+                        listChanged: true,
+                        subscribe: true
+                    }
+                },
+                serverInfo: {
+                    name: 'conduit',
+                    version: process.env.npm_package_version || '1.1.0'
+                }
+            }
+        };
+    }
+
     private async handleExecuteIsolate(params: any, context: ExecutionContext, id: string | number): Promise<JSONRPCResponse> {
         const { code, limits, allowedTools } = params;
 

package/src/core/security.service.ts

@@ -1,10 +1,11 @@
 import { Logger } from 'pino';
 import { NetworkPolicyService } from './network.policy.service.js';
-import { SessionManager, Session } from './session.manager.js';
+import { SessionManager } from './session.manager.js';
+import type { Session } from './session.manager.js';
 import { IUrlValidator } from './interfaces/url.validator.interface.js';
 import crypto from 'node:crypto';
 
-export { Session };
+export type { Session };
 
 export class SecurityService implements IUrlValidator {
     private logger: Logger;
@@ -39,6 +40,10 @@ export class SecurityService implements IUrlValidator {
 
     validateIpcToken(token: string): boolean {
         // Fix Sev1: Use timing-safe comparison for sensitive tokens
+        if (!this.ipcToken) {
+            return true;
+        }
+
         const expected = Buffer.from(this.ipcToken);
         const actual = Buffer.from(token);
 

package/src/core/types.ts

@@ -20,7 +20,7 @@ export interface JSONRPCRequest {
 
 export interface JSONRPCResponse {
     jsonrpc: '2.0';
-    id: string | number;
+    id: string | number | null;
     result?: any;
     error?: {
         code: number;

package/src/executors/deno.executor.ts

@@ -12,7 +12,7 @@ import { resolveAssetPath } from '../core/asset.utils.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-import { Executor, ExecutorConfig, ExecutionResult } from '../core/interfaces/executor.interface.js';
+import type { Executor, ExecutorConfig, ExecutionResult } from '../core/interfaces/executor.interface.js';
 
 export { ExecutionResult };
 

package/src/executors/isolate.executor.ts

@@ -5,7 +5,7 @@ import { ResourceLimits } from '../core/config.service.js';
 import { GatewayService } from '../gateway/gateway.service.js';
 import { ConduitError } from '../core/types.js';
 
-import { Executor, ExecutorConfig, ExecutionResult } from '../core/interfaces/executor.interface.js';
+import type { Executor, ExecutorConfig, ExecutionResult } from '../core/interfaces/executor.interface.js';
 
 export { ExecutionResult as IsolateExecutionResult };
 

package/src/executors/pyodide.executor.ts

@@ -9,7 +9,7 @@ import { resolveAssetPath } from '../core/asset.utils.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-import { Executor, ExecutorConfig, ExecutionResult } from '../core/interfaces/executor.interface.js';
+import type { Executor, ExecutorConfig, ExecutionResult } from '../core/interfaces/executor.interface.js';
 
 export { ExecutionResult };
 
@@ -113,13 +113,13 @@ export class PyodideExecutor implements Executor {
         const needed = this.maxPoolSize - this.pool.length;
         if (needed <= 0) return;
 
-        console.info(`Pre-warming ${needed} Pyodide workers...`);
+        console.error(`Pre-warming ${needed} Pyodide workers...`);
         const promises = [];
         for (let i = 0; i < needed; i++) {
             promises.push(this.createAndPoolWorker(limits));
         }
         await Promise.all(promises);
-        console.info(`Pyodide pool pre-warmed with ${this.pool.length} workers.`);
+        console.error(`Pyodide pool pre-warmed with ${this.pool.length} workers.`);
     }
 
     private async createAndPoolWorker(limits: ConduitResourceLimits) {

package/src/gateway/gateway.service.ts

@@ -10,6 +10,66 @@ import { PolicyService, ToolIdentifier } from '../core/policy.service.js';
 import { Ajv } from 'ajv';
 import addFormats from 'ajv-formats';
 
+const BUILT_IN_TOOLS: ToolSchema[] = [
+    {
+        name: 'mcp.executeTypeScript',
+        description: 'Executes TypeScript code in a secure sandbox with access to `tools.*` SDK.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    description: 'The TypeScript code to execute.'
+                },
+                allowedTools: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of tools the script is allowed to call (e.g. ["github.*"]).'
+                }
+            },
+            required: ['code']
+        }
+    },
+    {
+        name: 'mcp.executePython',
+        description: 'Executes Python code in a secure sandbox with access to `tools.*` SDK.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    description: 'The Python code to execute.'
+                },
+                allowedTools: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of tools the script is allowed to call (e.g. ["github.*"]).'
+                }
+            },
+            required: ['code']
+        }
+    },
+    {
+        name: 'mcp.executeIsolate',
+        description: 'Executes JavaScript code in a high-speed V8 isolate (no Deno/Node APIs).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    description: 'The JavaScript code to execute.'
+                },
+                allowedTools: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional list of tools the script is allowed to call.'
+                }
+            },
+            required: ['code']
+        }
+    }
+];
+
 export class GatewayService {
     private logger: Logger;
     private clients: Map<string, UpstreamClient> = new Map();
@@ -110,8 +170,13 @@ export class GatewayService {
         }
 
         const parsed = this.policyService.parseToolName(toolId);
+        const toolName = parsed.name; // Use a new variable for the un-namespaced name
+
+        // Check for built-in tools
+        const builtIn = BUILT_IN_TOOLS.find(t => t.name === toolId); // Compare with the full toolId
+        if (builtIn) return builtIn;
+
         const upstreamId = parsed.namespace;
-        const toolName = parsed.name;
 
         // Ensure we have schemas for this upstream
         if (!this.schemaCache.get(upstreamId)) {
@@ -132,7 +197,7 @@ export class GatewayService {
     }
 
     async discoverTools(context: ExecutionContext): Promise<ToolSchema[]> {
-        const allTools: ToolSchema[] = [];
+        const allTools: ToolSchema[] = [...BUILT_IN_TOOLS];
 
         for (const [id, client] of this.clients.entries()) {
             let tools = this.schemaCache.get(id);

package/src/index.ts

@@ -1,6 +1,7 @@
 import { ConfigService } from './core/config.service.js';
 import { createLogger, loggerStorage } from './core/logger.js';
 import { SocketTransport } from './transport/socket.transport.js';
+import { StdioTransport } from './transport/stdio.transport.js';
 import { OpsServer } from './core/ops.server.js';
 import { ConcurrencyService } from './core/concurrency.service.js';
 import { RequestController } from './core/request.controller.js';
@@ -14,14 +15,20 @@ import { ExecutorRegistry } from './core/registries/executor.registry.js';
 import { ExecutionService } from './core/execution.service.js';
 import { buildDefaultMiddleware } from './core/middleware/middleware.builder.js';
 async function main() {
+    // console.error('DEBUG: Starting Conduit main...');
     const configService = new ConfigService();
+    // console.error('DEBUG: Config loaded');
     const logger = createLogger(configService);
 
     const otelService = new OtelService(logger);
     await otelService.start();
 
     await loggerStorage.run({ correlationId: 'system' }, async () => {
-        const securityService = new SecurityService(logger, configService.get('ipcBearerToken'));
+        // Disable auth for Stdio transport (implicitly trusted as it is spawned by the user)
+        const isStdio = configService.get('transport') === 'stdio';
+        const ipcToken = isStdio ? undefined : configService.get('ipcBearerToken');
+
+        const securityService = new SecurityService(logger, ipcToken!);
 
         const gatewayService = new GatewayService(logger, securityService);
         const upstreams = configService.get('upstreams') || [];
@@ -59,9 +66,18 @@ async function main() {
             maxConcurrent: configService.get('maxConcurrent')
         });
 
-        const transport = new SocketTransport(logger, requestController, concurrencyService);
-        const port = configService.get('port');
-        const address = await transport.listen({ port });
+        let transport: SocketTransport | StdioTransport;
+        let address: string;
+
+        if (configService.get('transport') === 'stdio') {
+            transport = new StdioTransport(logger, requestController, concurrencyService);
+            await transport.start();
+            address = 'stdio';
+        } else {
+            transport = new SocketTransport(logger, requestController, concurrencyService);
+            const port = configService.get('port');
+            address = await transport.listen({ port });
+        }
         executionService.ipcAddress = address; // Update IPC address on ExecutionService instead of RequestController
 
         // Pre-warm workers

package/src/sdk/index.ts

@@ -1,2 +1,3 @@
-export { ToolBinding, SDKGeneratorOptions, toToolBinding, groupByNamespace } from './tool-binding.js';
+export { toToolBinding, groupByNamespace } from './tool-binding.js';
+export type { ToolBinding, SDKGeneratorOptions } from './tool-binding.js';
 export { SDKGenerator } from './sdk-generator.js';

package/src/transport/stdio.transport.ts

@@ -0,0 +1,116 @@
+import { Logger } from 'pino';
+import { RequestController } from '../core/request.controller.js';
+import { JSONRPCRequest, ConduitError } from '../core/types.js';
+import { ExecutionContext } from '../core/execution.context.js';
+import { ConcurrencyService } from '../core/concurrency.service.js';
+import { loggerStorage } from '../core/logger.js';
+
+export class StdioTransport {
+    private logger: Logger;
+    private requestController: RequestController;
+    private concurrencyService: ConcurrencyService;
+    private buffer: string = '';
+
+    constructor(
+        logger: Logger,
+        requestController: RequestController,
+        concurrencyService: ConcurrencyService
+    ) {
+        this.logger = logger;
+        this.requestController = requestController;
+        this.concurrencyService = concurrencyService;
+    }
+
+    async start(): Promise<void> {
+        this.logger.info('Starting Stdio transport');
+
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', this.handleData.bind(this));
+
+        // Handle stream end if necessary, though usually main process exit handles this
+        process.stdin.on('end', () => {
+            this.logger.info('Stdin closed');
+        });
+    }
+
+    private handleData(chunk: string) {
+        this.buffer += chunk;
+
+        let pos: number;
+        while ((pos = this.buffer.indexOf('\n')) >= 0) {
+            const line = this.buffer.substring(0, pos).trim();
+            this.buffer = this.buffer.substring(pos + 1);
+
+            if (!line) continue;
+
+            this.processLine(line);
+        }
+    }
+
+    private async processLine(line: string) {
+        let request: JSONRPCRequest;
+        try {
+            request = JSON.parse(line) as JSONRPCRequest;
+        } catch (err) {
+            this.logger.error({ err, line }, 'Failed to parse JSON-RPC request');
+            const errorResponse = {
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: -32700,
+                    message: 'Parse error',
+                },
+            };
+            this.sendResponse(errorResponse);
+            return;
+        }
+
+        const context = new ExecutionContext({
+            logger: this.logger,
+            remoteAddress: 'stdio',
+        });
+
+        await loggerStorage.run({ correlationId: context.correlationId }, async () => {
+            try {
+                const response = await this.concurrencyService.run(() =>
+                    this.requestController.handleRequest(request, context)
+                );
+                // Don't send response for notifications (they return null)
+                if (response !== null) {
+                    this.sendResponse(response);
+                }
+            } catch (err: any) {
+                if (err.name === 'QueueFullError') {
+                    this.sendResponse({
+                        jsonrpc: '2.0',
+                        id: request.id,
+                        error: {
+                            code: ConduitError.ServerBusy,
+                            message: 'Server busy'
+                        }
+                    });
+                } else {
+                    this.logger.error({ err, requestId: request.id }, 'Request handling failed');
+                    this.sendResponse({
+                        jsonrpc: '2.0',
+                        id: request.id,
+                        error: {
+                            code: ConduitError.InternalError,
+                            message: 'Internal server error'
+                        }
+                    });
+                }
+            }
+        });
+    }
+
+    private sendResponse(response: any) {
+        process.stdout.write(JSON.stringify(response) + '\n');
+    }
+
+    async close(): Promise<void> {
+        process.stdin.removeAllListeners();
+        // We don't close stdout/stdin as they are process-level
+        return Promise.resolve();
+    }
+}

package/tests/dynamic.tool.test.ts

@@ -101,12 +101,12 @@ describe('Dynamic Tool Calling (E2E)', () => {
             auth: { bearerToken: testToken }
         }, context);
 
-        fs.appendFileSync(LOG_FILE, `Deno Stdout: ${response.result?.stdout}\n`);
-        fs.appendFileSync(LOG_FILE, `Deno Stderr: ${response.result?.stderr}\n`);
+        fs.appendFileSync(LOG_FILE, `Deno Stdout: ${response!.result?.stdout}\n`);
+        fs.appendFileSync(LOG_FILE, `Deno Stderr: ${response!.result?.stderr}\n`);
 
-        expect(response.error).toBeUndefined();
-        expect(response.result.stdout).toContain('mock__hello');
-        expect(response.result.stdout).toContain('Hello Deno');
+        expect(response!.error).toBeUndefined();
+        expect(response!.result.stdout).toContain('mock__hello');
+        expect(response!.result.stdout).toContain('Hello Deno');
     }, 15000);
 
     it('should allow Python to discover and call tools via SDK', async () => {
@@ -127,13 +127,13 @@ print(f"RESULT:{result}")
             auth: { bearerToken: testToken }
         }, context);
 
-        fs.appendFileSync(LOG_FILE, `Python Stdout: ${response.result?.stdout}\n`);
-        fs.appendFileSync(LOG_FILE, `Python Stderr: ${response.result?.stderr}\n`);
-        if (response.error) fs.appendFileSync(LOG_FILE, `Python Error: ${JSON.stringify(response.error)}\n`);
+        fs.appendFileSync(LOG_FILE, `Python Stdout: ${response!.result?.stdout}\n`);
+        fs.appendFileSync(LOG_FILE, `Python Stderr: ${response!.result?.stderr}\n`);
+        if (response!.error) fs.appendFileSync(LOG_FILE, `Python Error: ${JSON.stringify(response!.error)}\n`);
 
-        expect(response.error).toBeUndefined();
-        expect(response.result.stdout).toContain('mock__hello');
-        expect(response.result.stdout).toContain('Hello Python');
+        expect(response!.error).toBeUndefined();
+        expect(response!.result.stdout).toContain('mock__hello');
+        expect(response!.result.stdout).toContain('Hello Python');
     }, 25000);
 
     it('should reject tools not in allowlist via $raw()', async () => {
@@ -159,12 +159,12 @@ print(f"RESULT:{result}")
             auth: { bearerToken: testToken }
         }, context);
 
-        fs.appendFileSync(LOG_FILE, `Allowlist Stdout: ${response.result?.stdout}\n`);
-        if (response.error) fs.appendFileSync(LOG_FILE, `Allowlist Error: ${JSON.stringify(response.error)}\n`);
+        fs.appendFileSync(LOG_FILE, `Allowlist Stdout: ${response!.result?.stdout}\n`);
+        if (response!.error) fs.appendFileSync(LOG_FILE, `Allowlist Error: ${JSON.stringify(response!.error)}\n`);
 
-        expect(response.error).toBeUndefined();
-        expect(response.result.stdout).toContain('REJECTED');
-        expect(response.result.stdout).toContain('not in the allowlist');
+        expect(response!.error).toBeUndefined();
+        expect(response!.result.stdout).toContain('REJECTED');
+        expect(response!.result.stdout).toContain('not in the allowlist');
     }, 15000);
 
     it('should allow tools matching wildcard pattern', async () => {
@@ -186,11 +186,11 @@ print(f"RESULT:{result}")
             auth: { bearerToken: testToken }
         }, context);
 
-        fs.appendFileSync(LOG_FILE, `Wildcard Stdout: ${response.result?.stdout}\n`);
-        if (response.error) fs.appendFileSync(LOG_FILE, `Wildcard Error: ${JSON.stringify(response.error)}\n`);
+        fs.appendFileSync(LOG_FILE, `Wildcard Stdout: ${response!.result?.stdout}\n`);
+        if (response!.error) fs.appendFileSync(LOG_FILE, `Wildcard Error: ${JSON.stringify(response!.error)}\n`);
 
-        expect(response.error).toBeUndefined();
-        expect(response.result.stdout).toContain('Hello Wildcard');
+        expect(response!.error).toBeUndefined();
+        expect(response!.result.stdout).toContain('Hello Wildcard');
     }, 15000);
 
     it('should allow isolated-vm to discover and call tools via typed SDK', async () => {
@@ -215,11 +215,11 @@ print(f"RESULT:{result}")
             auth: { bearerToken: testToken }
         }, context);
 
-        fs.appendFileSync(LOG_FILE, `Isolate Stdout: ${response.result?.stdout}\n`);
-        if (response.error) fs.appendFileSync(LOG_FILE, `Isolate Error: ${JSON.stringify(response.error)}\n`);
+        fs.appendFileSync(LOG_FILE, `Isolate Stdout: ${response!.result?.stdout}\n`);
+        if (response!.error) fs.appendFileSync(LOG_FILE, `Isolate Error: ${JSON.stringify(response!.error)}\n`);
 
-        expect(response.error).toBeUndefined();
-        expect(response.result.stdout).toContain('Isolate call done');
+        expect(response!.error).toBeUndefined();
+        expect(response!.result.stdout).toContain('Isolate call done');
 
         // Verify tool was called
         expect(mockClient.call).toHaveBeenCalled();

package/tests/gateway.service.test.ts

@@ -31,11 +31,21 @@ describe('GatewayService', () => {
         });
 
         const tools = await gateway.discoverTools(context);
-        expect(tools).toHaveLength(2);
+        expect(tools.length).toBeGreaterThanOrEqual(3);
+        expect(tools.find(t => t.name === 'mcp.executeTypeScript')).toBeDefined();
+        expect(tools.find(t => t.name === 'mcp.executePython')).toBeDefined();
+        expect(tools.find(t => t.name === 'mcp.executeIsolate')).toBeDefined();
         expect(tools.find(t => t.name === 'u1__t1')).toBeDefined();
         expect(tools.find(t => t.name === 'u2__t2')).toBeDefined();
     });
 
+    it('should return schema for built-in tools', async () => {
+        const schema = await gateway.getToolSchema('mcp.executeTypeScript', context);
+        expect(schema).toBeDefined();
+        expect(schema?.name).toBe('mcp.executeTypeScript');
+        expect(schema?.inputSchema.required).toContain('code');
+    });
+
     it('should route tool calls to correct upstream', async () => {
         gateway.registerUpstream({ id: 'u1', url: 'http://u1' });
 

package/tests/ops.server.test.ts

@@ -17,7 +17,11 @@ describe('OpsServer', () => {
     let gatewayService: GatewayService;
 
     beforeEach(() => {
-        configService = new ConfigService({ port: 0 as any });
+        configService = new ConfigService({
+            port: 0,
+            opsPort: 0,
+            metricsUrl: 'http://127.0.0.1:0/metrics' // Force fallback by using invalid URL
+        } as any);
         const securityService = new SecurityService(logger, 'test-token');
         gatewayService = new GatewayService(logger, securityService);
         const executorRegistry = new ExecutorRegistry();

package/tests/routing.test.ts

@@ -94,7 +94,7 @@ describe('RequestController Routing', () => {
 
         expect(mockIsolateExecutor.execute).toHaveBeenCalled();
         expect(mockDenoExecutor.execute).not.toHaveBeenCalled();
-        expect(result.result.stdout).toBe('isolate');
+        expect(result!.result.stdout).toBe('isolate');
     });
 
     it('should route scripts with imports to DenoExecutor', async () => {
@@ -111,7 +111,7 @@ describe('RequestController Routing', () => {
 
         expect(mockDenoExecutor.execute).toHaveBeenCalled();
         expect(mockIsolateExecutor.execute).not.toHaveBeenCalled();
-        expect(result.result.stdout).toBe('deno');
+        expect(result!.result.stdout).toBe('deno');
     });
 
     it('should route scripts with exports to DenoExecutor', async () => {

package/tests/vscode_e2e.test.ts

@@ -0,0 +1,91 @@
+/**
+ * E2E Test: Native Stdio Mode
+ * 
+ * This test verifies that Conduit can be run in native Stdio mode (via --stdio flag),
+ * communicating directly over stdin/stdout.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawn } from 'child_process';
+import path from 'path';
+
+describe('E2E: Native Stdio Mode', () => {
+    it('should start in stdio mode and discover tools', async () => {
+        const indexPath = path.resolve(__dirname, '../src/index.ts');
+
+        const child = spawn('npx', ['tsx', indexPath, '--stdio'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                PATH: process.env.PATH,
+                PORT: '0', // Use random port for ops server to avoid conflicts
+            }
+        });
+
+        const request = {
+            jsonrpc: '2.0',
+            id: '1',
+            method: 'mcp.discoverTools',
+            params: {},
+            // Use a dummy token, security service might reject if auth is enabled but 
+            // the default config generates a random token.
+            // However, in this test we are spawning a fresh process, so we don't know the token.
+            // Wait, security service checks 'ipcBearerToken'.
+            // If we don't provide one, it generates random.
+            // We should provide one via env var so we can auth.
+            auth: { bearerToken: 'test-token' },
+        };
+
+        // We need to inject the token into the spawned process env
+        child.kill();
+
+        // Restart with known token
+        const childWithAuth = spawn('npx', ['tsx', indexPath, '--stdio'], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: {
+                ...process.env,
+                PATH: process.env.PATH,
+                PORT: '0',
+                IPC_BEARER_TOKEN: 'test-token'
+            }
+        });
+
+        // Write request to process stdin
+        childWithAuth.stdin.write(JSON.stringify(request) + '\n');
+
+        const response = await new Promise<any>((resolve, reject) => {
+            let buffer = '';
+            childWithAuth.stdout.on('data', (chunk) => {
+                buffer += chunk.toString();
+                if (buffer.includes('\n')) {
+                    const lines = buffer.split('\n');
+                    for (const line of lines) {
+                        if (!line.trim()) continue;
+                        try {
+                            const parsed = JSON.parse(line);
+                            resolve(parsed);
+                            return;
+                        } catch (e) {
+                            // ignore partial or non-json (though stdout should be pure json-rpc)
+                        }
+                    }
+                }
+            });
+
+            childWithAuth.stderr.pipe(process.stderr);
+
+            childWithAuth.on('error', reject);
+
+            setTimeout(() => {
+                childWithAuth.kill();
+                reject(new Error('Timeout waiting for response'));
+            }, 30000);
+        });
+
+        childWithAuth.kill();
+
+        expect(response.error).toBeUndefined();
+        expect(response.result).toBeDefined();
+        expect(response.result.tools).toBeInstanceOf(Array);
+        expect(response.id).toBe('1');
+    }, 35000);
+});

package/tsup.config.ts

@@ -10,10 +10,10 @@ export default defineConfig({
     splitting: false,
     sourcemap: true,
     clean: true,
-    loader: {
-        '.py': 'text',
-        '.ts': 'text', // We want the shim source as text
-    },
+    // loader: {
+    //     '.py': 'text',
+    //     '.ts': 'text', // REMOVED: This was causing src/index.ts to be compiled as a string!
+    // },
     // Ensure assets are included
     // We can use the 'onSuccess' hook to copy them or just include them in the bundle
     // But the spec says 'into dist/assets', which implies they should be separate files.