@mhingston5/conduit 1.1.0 → 1.1.2

package/README.md

@@ -75,7 +75,7 @@ upstreams:
 
 ### 3. Execute TypeScript
 
-Using any [MCP Client](https://modelcontextprotocol.io/clients) (Claude Desktop, etc.), call `mcp.executeTypeScript`:
+Using any [MCP Client](https://modelcontextprotocol.io/clients) (Claude Desktop, etc.), call `mcp_execute_typescript`:
 
 ```ts
 // The agent writes this code:
@@ -175,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_execute_typescript`**: 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/docs/ARCHITECTURE.md

@@ -12,7 +12,7 @@ Conduit is built with a modular architecture, designed to be secure, observable,
 
 ## Detailed Flow
 
-1. **Client Request**: A client (like VS Code or Claude Desktop) sends a JSON-RPC request (`mcp.executeTypeScript`).
+1. **Client Request**: A client (like VS Code or Claude Desktop) sends a JSON-RPC request (`mcp_execute_typescript`).
 2. **Transportation**: The request is received via `SocketTransport` (TCP/UDS/Pipe).
 3. **Dispatch**: `RequestController` validates the request and session tokens.
 4. **Tool Discovery**: `GatewayService` aggregates tools from all upstream MCP servers.

package/docs/CODE_MODE.md

@@ -28,6 +28,6 @@ Because logic executes in a sandbox, you can enforce limits on loops, memory, an
 ## Implementation in Conduit
 
 Conduit provides:
-1. **`executeTypeScript` / `executePython`**: The entry points.
+1. **`mcp_execute_typescript` / `mcp_execute_python`**: The entry points.
 2. **`tools.*` SDK**: A dynamically generated client injected into the runtime.
 3. **Sandboxes**: Deno, Pyodide, and isolated-vm to run the code safely.

package/docs/SECURITY.md

@@ -27,7 +27,7 @@ Conduit enforces strict Server-Side Request Forgery (SSRF) protections on upstre
 ## Authorization
 
 - **Master Token**: Full access to all methods (set via `IPC_BEARER_TOKEN`).
-- **Session Tokens**: Generated per-execution, restricted to `mcp.discoverTools` and `mcp.callTool` only.
+- **Session Tokens**: Generated per-execution, restricted to `mcp_discover_tools` and `mcp_call_tool` only.
 - **Tool Allowlisting**: Per-request scope limits which tools code can discover/call (e.g., `["github.*"]`).
 
 ## Runtime Security

package/package.json

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

package/src/assets/deno-shim.ts

@@ -81,12 +81,12 @@ async function sendIPCRequest(method: string, params: any) {
 
 // Internal tool call function - used by generated SDK
 const __internalCallTool = async (name: string, params: any) => {
-    return await sendIPCRequest('mcp.callTool', { name, arguments: params });
+    return await sendIPCRequest('mcp_call_tool', { name, arguments: params });
 };
 
 // Tool discovery - still available for dynamic scenarios
 (globalThis as any).discoverMCPTools = async (options: any) => {
-    const result = await sendIPCRequest('mcp.discoverTools', options);
+    const result = await sendIPCRequest('mcp_discover_tools', options);
     return result.tools || [];
 };
 

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

@@ -31,7 +31,7 @@ export class AuthMiddleware implements Middleware {
 
         // Strict scoping for session tokens
         if (isSession) {
-            const allowedMethods = ['initialize', 'notifications/initialized', 'mcp.discoverTools', 'mcp.callTool', 'ping'];
+            const allowedMethods = ['initialize', 'notifications/initialized', 'mcp_discover_tools', 'mcp_call_tool', 'ping', 'tools/list', 'tools/call'];
             if (!allowedMethods.includes(request.method)) {
                 return {
                     jsonrpc: '2.0',

package/src/core/request.controller.ts

@@ -102,23 +102,24 @@ export class RequestController {
 
         switch (method) {
             case 'tools/list': // Standard MCP method name
-            case 'mcp.discoverTools':
+            case 'mcp_discover_tools':
                 return this.handleDiscoverTools(params, context, id);
-            case 'mcp.listToolPackages':
+            case 'mcp_list_tool_packages':
                 return this.handleListToolPackages(params, context, id);
-            case 'mcp.listToolStubs':
+            case 'mcp_list_tool_stubs':
                 return this.handleListToolStubs(params, context, id);
-            case 'mcp.readToolSchema':
+            case 'mcp_read_tool_schema':
                 return this.handleReadToolSchema(params, context, id);
-            case 'mcp.validateTool':
+            case 'mcp_validate_tool':
                 return this.handleValidateTool(request, context);
-            case 'mcp.callTool':
+            case 'mcp_call_tool':
+            case 'tools/call':
                 return this.handleCallTool(params, context, id);
-            case 'mcp.executeTypeScript':
+            case 'mcp_execute_typescript':
                 return this.handleExecuteTypeScript(params, context, id);
-            case 'mcp.executePython':
+            case 'mcp_execute_python':
                 return this.handleExecutePython(params, context, id);
-            case 'mcp.executeIsolate':
+            case 'mcp_execute_isolate':
                 return this.handleExecuteIsolate(params, context, id);
             case 'initialize':
                 return this.handleInitialize(params, context, id);
@@ -209,6 +210,17 @@ export class RequestController {
 
     private async handleCallTool(params: any, context: ExecutionContext, id: string | number): Promise<JSONRPCResponse> {
         const { name, arguments: toolArgs } = params;
+
+        // Route built-in tools to their specific handlers
+        switch (name) {
+            case 'mcp_execute_typescript':
+                return this.handleExecuteTypeScript(toolArgs, context, id);
+            case 'mcp_execute_python':
+                return this.handleExecutePython(toolArgs, context, id);
+            case 'mcp_execute_isolate':
+                return this.handleExecuteIsolate(toolArgs, context, id);
+        }
+
         const response = await this.gatewayService.callTool(name, toolArgs, context);
         return { ...response, id };
     }

package/src/executors/pyodide.worker.ts

@@ -131,11 +131,11 @@ async function handleTask(data: any) {
         };
 
         (p as any).globals.set('discover_mcp_tools_js', (options: any) => {
-            return sendIPCRequest('mcp.discoverTools', options);
+            return sendIPCRequest('mcp_discover_tools', options);
         });
 
         (p as any).globals.set('call_mcp_tool_js', (name: string, args: any) => {
-            return sendIPCRequest('mcp.callTool', { name, arguments: args });
+            return sendIPCRequest('mcp_call_tool', { name, arguments: args });
         });
 
         if (shim) {

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_execute_typescript',
+        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_execute_python',
+        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_execute_isolate',
+        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/tests/contract.test.ts

@@ -32,8 +32,8 @@ describe('Contract Test: Conduit vs Reference MCP', () => {
 
     it('should successfully discover tools from reference MCP', async () => {
         const tools = await gateway.discoverTools(context);
-        expect(tools).toHaveLength(1);
-        expect(tools[0].name).toBe('ref__echo');
+        expect(tools.length).toBeGreaterThanOrEqual(1);
+        expect(tools.find(t => t.name === 'ref__echo')).toBeDefined();
     });
 
     it('should successfully call tool on reference MCP', async () => {

package/tests/dynamic.tool.test.ts

@@ -96,7 +96,7 @@ describe('Dynamic Tool Calling (E2E)', () => {
         const response = await requestController.handleRequest({
             jsonrpc: '2.0',
             id: 1,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: { code },
             auth: { bearerToken: testToken }
         }, context);
@@ -122,7 +122,7 @@ print(f"RESULT:{result}")
         const response = await requestController.handleRequest({
             jsonrpc: '2.0',
             id: 2,
-            method: 'mcp.executePython',
+            method: 'mcp_execute_python',
             params: { code },
             auth: { bearerToken: testToken }
         }, context);
@@ -151,7 +151,7 @@ print(f"RESULT:{result}")
         const response = await requestController.handleRequest({
             jsonrpc: '2.0',
             id: 3,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: {
                 code,
                 allowedTools: ['mock.hello']  // Only mock.hello allowed
@@ -178,7 +178,7 @@ print(f"RESULT:{result}")
         const response = await requestController.handleRequest({
             jsonrpc: '2.0',
             id: 4,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: {
                 code,
                 allowedTools: ['mock.*']  // Wildcard allows all mock tools
@@ -206,7 +206,7 @@ print(f"RESULT:{result}")
         const response = await requestController.handleRequest({
             jsonrpc: '2.0',
             id: 5,
-            method: 'mcp.executeIsolate',
+            method: 'mcp_execute_isolate',
             params: {
                 code,
                 allowedTools: ['mock.*'],

package/tests/e2e_stdio_upstream.test.ts

@@ -149,7 +149,7 @@ describe('E2E: Stdio Upstream Integration', () => {
         const response = await sendRequest({
             jsonrpc: '2.0',
             id: '1',
-            method: 'mcp.discoverTools',
+            method: 'mcp_discover_tools',
             params: {},
             auth: { bearerToken: ipcToken },
         });
@@ -169,7 +169,7 @@ describe('E2E: Stdio Upstream Integration', () => {
         const discoverResponse = await sendRequest({
             jsonrpc: '2.0',
             id: '1',
-            method: 'mcp.discoverTools',
+            method: 'mcp_discover_tools',
             params: {},
             auth: { bearerToken: ipcToken },
         });
@@ -181,7 +181,7 @@ describe('E2E: Stdio Upstream Integration', () => {
         const callResponse = await sendRequest({
             jsonrpc: '2.0',
             id: '2',
-            method: 'mcp.callTool',
+            method: 'mcp_call_tool',
             params: {
                 name: echoTool.name,
                 arguments: { message: 'Hello from E2E test!' },

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_execute_typescript')).toBeDefined();
+        expect(tools.find(t => t.name === 'mcp_execute_python')).toBeDefined();
+        expect(tools.find(t => t.name === 'mcp_execute_isolate')).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_execute_typescript', context);
+        expect(schema).toBeDefined();
+        expect(schema?.name).toBe('mcp_execute_typescript');
+        expect(schema?.inputSchema.required).toContain('code');
+    });
+
     it('should route tool calls to correct upstream', async () => {
         gateway.registerUpstream({ id: 'u1', url: 'http://u1' });
 

package/tests/hardening.test.ts

@@ -92,7 +92,7 @@ describe('V1 Hardening Tests', () => {
         const response = await sendRequest({
             jsonrpc: '2.0',
             id: 1,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: { code: 'console.log("hi")' },
             auth: { bearerToken: sessionToken }
         });
@@ -114,7 +114,7 @@ describe('V1 Hardening Tests', () => {
         const response = await sendRequest({
             jsonrpc: '2.0',
             id: 2,
-            method: 'mcp.discoverTools',
+            method: 'mcp_discover_tools',
             params: {},
             auth: { bearerToken: sessionToken }
         });
@@ -127,7 +127,7 @@ describe('V1 Hardening Tests', () => {
         const response = await sendRequest({
             jsonrpc: '2.0',
             id: 3,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: { code: 'import * as os from "os"; console.log("hi")' },
             auth: { bearerToken: 'master-token' }
         });

package/tests/routing.test.ts

@@ -84,7 +84,7 @@ describe('RequestController Routing', () => {
         const result = await controller.handleRequest({
             jsonrpc: '2.0',
             id: 1,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: {
                 code: 'console.log("simple")',
                 limits: {}
@@ -101,7 +101,7 @@ describe('RequestController Routing', () => {
         const result = await controller.handleRequest({
             jsonrpc: '2.0',
             id: 1,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: {
                 code: 'import { foo } from "bar"; console.log(foo)',
                 limits: {}
@@ -118,7 +118,7 @@ describe('RequestController Routing', () => {
         const result = await controller.handleRequest({
             jsonrpc: '2.0',
             id: 1,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: {
                 code: 'export const foo = "bar"',
                 limits: {}
@@ -134,7 +134,7 @@ describe('RequestController Routing', () => {
         const result = await controller.handleRequest({
             jsonrpc: '2.0',
             id: 1,
-            method: 'mcp.executeTypeScript',
+            method: 'mcp_execute_typescript',
             params: {
                 code: 'console.log(Deno.version)',
                 limits: {}
@@ -145,4 +145,24 @@ describe('RequestController Routing', () => {
         expect(mockDenoExecutor.execute).toHaveBeenCalled();
         expect(mockIsolateExecutor.execute).not.toHaveBeenCalled();
     });
+
+    it('should route tools/call for built-in tools', async () => {
+        const result = await controller.handleRequest({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'tools/call',
+            params: {
+                name: 'mcp_execute_typescript',
+                arguments: {
+                    code: 'console.log("via tools/call")',
+                    limits: {}
+                }
+            },
+            auth: { bearerToken: 'master-token' }
+        }, mockContext);
+
+        expect(mockIsolateExecutor.execute).toHaveBeenCalled();
+        expect(result!.result.stdout).toBe('isolate');
+    });
+
 });

package/tests/socket.transport.test.ts

@@ -100,7 +100,7 @@ describe('SocketTransport', () => {
         });
     }
 
-    it('should handle mcp.executeTypeScript request', async () => {
+    it('should handle mcp_execute_typescript request', async () => {
         transport = new SocketTransport(logger, requestController, concurrencyService);
         const address = await transport.listen({ port: 0 });
         const portMatch = address.match(/:(\d+)$/);
@@ -112,7 +112,7 @@ describe('SocketTransport', () => {
                 const request = {
                     jsonrpc: '2.0',
                     id: 1,
-                    method: 'mcp.executeTypeScript',
+                    method: 'mcp_execute_typescript',
                     params: { code: 'console.log("hello E2E")' },
                     auth: { bearerToken: testToken }
                 };
@@ -153,7 +153,7 @@ describe('SocketTransport', () => {
                 const request = {
                     jsonrpc: '2.0',
                     id: 12345,
-                    method: 'mcp.executeTypeScript',
+                    method: 'mcp_execute_typescript',
                     params: { code: 'console.log("hello")' },
                     auth: { bearerToken: testToken }
                 };

package/tests/vscode_e2e.test.ts

@@ -24,7 +24,7 @@ describe('E2E: Native Stdio Mode', () => {
         const request = {
             jsonrpc: '2.0',
             id: '1',
-            method: 'mcp.discoverTools',
+            method: 'mcp_discover_tools',
             params: {},
             // Use a dummy token, security service might reject if auth is enabled but 
             // the default config generates a random token.