palaryn 0.1.0

package/dist/src/mcp/bridge.js

@@ -0,0 +1,734 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPBridge = void 0;
+exports.startMCPBridge = startMCPBridge;
+const crypto_1 = require("crypto");
+const gateway_1 = require("../server/gateway");
+const defaults_1 = require("../config/defaults");
+const DEFAULT_BRIDGE_CONFIG = {
+    workspace_id: 'ws_mcp_default',
+    actor: { type: 'agent', id: 'mcp-agent', display: 'MCP Agent' },
+    source: { platform: 'mcp' },
+    task_id: '',
+};
+// ---------------------------------------------------------------------------
+// MCP protocol constants
+// ---------------------------------------------------------------------------
+const LATEST_PROTOCOL_VERSION = '2025-03-26';
+const JSONRPC_VERSION = '2.0';
+const SERVER_INFO = {
+    name: 'palaryn-mcp-bridge',
+    version: '1.0.0',
+};
+// JSON-RPC error codes
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+// ---------------------------------------------------------------------------
+// Tool schemas (JSON Schema format for MCP tools/list)
+// ---------------------------------------------------------------------------
+const HTTP_REQUEST_SCHEMA = {
+    name: 'http_request',
+    description: 'Execute an HTTP request through the Palaryn gateway. ' +
+        'Supports all HTTP methods. The request goes through policy evaluation, ' +
+        'DLP scanning, budget checks, and rate limiting before execution.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'The target URL for the HTTP request' },
+            method: {
+                type: 'string',
+                enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
+                description: 'HTTP method (defaults to GET)',
+            },
+            headers: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'HTTP headers as key-value pairs',
+            },
+            body: {
+                type: 'string',
+                description: 'Request body (typically JSON string for POST/PUT/PATCH)',
+            },
+            timeout_ms: { type: 'number', description: 'Request timeout in milliseconds' },
+            max_cost_usd: {
+                type: 'number',
+                description: 'Maximum cost budget for this request in USD',
+            },
+            purpose: {
+                type: 'string',
+                description: 'Description of why this request is being made',
+            },
+            labels: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Classification labels for the request',
+            },
+        },
+        required: ['url'],
+    },
+    annotations: {
+        title: 'HTTP Request',
+        readOnlyHint: false,
+        destructiveHint: true,
+        openWorldHint: true,
+    },
+};
+const HTTP_GET_SCHEMA = {
+    name: 'http_get',
+    description: 'Execute an HTTP GET request through the Palaryn gateway. ' +
+        'Shorthand for http_request with method=GET. The request goes through ' +
+        'policy evaluation, DLP scanning, budget checks, and rate limiting.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'The target URL for the GET request' },
+            headers: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'HTTP headers as key-value pairs',
+            },
+            timeout_ms: { type: 'number', description: 'Request timeout in milliseconds' },
+            max_cost_usd: {
+                type: 'number',
+                description: 'Maximum cost budget for this request in USD',
+            },
+            purpose: {
+                type: 'string',
+                description: 'Description of why this request is being made',
+            },
+            labels: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Classification labels for the request',
+            },
+        },
+        required: ['url'],
+    },
+    annotations: {
+        title: 'HTTP GET',
+        readOnlyHint: true,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+};
+const HTTP_POST_SCHEMA = {
+    name: 'http_post',
+    description: 'Execute an HTTP POST request through the Palaryn gateway. ' +
+        'Shorthand for http_request with method=POST. The request goes through ' +
+        'policy evaluation, DLP scanning, budget checks, and rate limiting.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            url: { type: 'string', description: 'The target URL for the POST request' },
+            headers: {
+                type: 'object',
+                additionalProperties: { type: 'string' },
+                description: 'HTTP headers as key-value pairs',
+            },
+            body: { type: 'string', description: 'Request body (typically a JSON string)' },
+            timeout_ms: { type: 'number', description: 'Request timeout in milliseconds' },
+            max_cost_usd: {
+                type: 'number',
+                description: 'Maximum cost budget for this request in USD',
+            },
+            purpose: {
+                type: 'string',
+                description: 'Description of why this request is being made',
+            },
+            labels: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Classification labels for the request',
+            },
+        },
+        required: ['url'],
+    },
+    annotations: {
+        title: 'HTTP POST',
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true,
+    },
+};
+const ALL_TOOLS = [HTTP_REQUEST_SCHEMA, HTTP_GET_SCHEMA, HTTP_POST_SCHEMA];
+// ---------------------------------------------------------------------------
+// StdioTransport - line-delimited JSON-RPC over stdin/stdout
+// ---------------------------------------------------------------------------
+/**
+ * Reads line-delimited JSON-RPC messages from a readable stream
+ * and writes JSON-RPC responses to a writable stream.
+ * Follows the MCP stdio transport specification.
+ */
+class StdioTransport {
+    constructor(input, output) {
+        this.buffer = '';
+        this.onMessage = null;
+        this.bufferTimeoutHandle = null;
+        this.input = input || process.stdin;
+        this.output = output || process.stdout;
+    }
+    /** Start listening for messages on the input stream. */
+    start(handler) {
+        this.onMessage = handler;
+        this.input.setEncoding('utf8');
+        this.input.on('data', (chunk) => this.onData(chunk));
+    }
+    /** Send a JSON-RPC response to the output stream. */
+    send(response) {
+        const json = JSON.stringify(response);
+        this.output.write(json + '\n');
+    }
+    /** Stop listening and clean up. */
+    close() {
+        this.input.removeAllListeners('data');
+        this.onMessage = null;
+        this.clearBufferTimeout();
+    }
+    clearBufferTimeout() {
+        if (this.bufferTimeoutHandle) {
+            clearTimeout(this.bufferTimeoutHandle);
+            this.bufferTimeoutHandle = null;
+        }
+    }
+    /** Reset the inactivity timer for partial buffer data. */
+    resetBufferTimeout() {
+        this.clearBufferTimeout();
+        if (this.buffer.length > 0) {
+            this.bufferTimeoutHandle = setTimeout(() => {
+                if (this.buffer.length > 0) {
+                    console.error(`[mcp-bridge] Buffer inactivity timeout (${StdioTransport.BUFFER_INACTIVITY_TIMEOUT_MS}ms) with ${this.buffer.length} bytes pending, clearing`);
+                    this.buffer = '';
+                    const errorResponse = {
+                        jsonrpc: JSONRPC_VERSION,
+                        id: null,
+                        error: { code: PARSE_ERROR, message: 'Buffer inactivity timeout: incomplete message cleared' },
+                    };
+                    this.send(errorResponse);
+                }
+            }, StdioTransport.BUFFER_INACTIVITY_TIMEOUT_MS);
+        }
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        // Prevent unbounded buffer growth
+        if (this.buffer.length > StdioTransport.MAX_BUFFER_SIZE) {
+            console.error('[mcp-bridge] Buffer exceeded maximum size (10MB), clearing');
+            this.buffer = '';
+            this.clearBufferTimeout();
+            const errorResponse = {
+                jsonrpc: JSONRPC_VERSION,
+                id: null,
+                error: { code: PARSE_ERROR, message: 'Message too large: exceeded 10MB buffer limit' },
+            };
+            this.send(errorResponse);
+            return;
+        }
+        // Process complete lines
+        const lines = this.buffer.split('\n');
+        // Keep the last (possibly incomplete) line in the buffer
+        this.buffer = lines.pop() || '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (this.onMessage) {
+                    this.onMessage(parsed);
+                }
+            }
+            catch {
+                // Send parse error for invalid JSON
+                const errorResponse = {
+                    jsonrpc: JSONRPC_VERSION,
+                    id: null,
+                    error: { code: PARSE_ERROR, message: 'Parse error: invalid JSON' },
+                };
+                this.send(errorResponse);
+            }
+        }
+        // Reset inactivity timer if there's still partial data in the buffer
+        this.resetBufferTimeout();
+    }
+}
+StdioTransport.MAX_BUFFER_SIZE = 10 * 1024 * 1024; // 10MB
+StdioTransport.BUFFER_INACTIVITY_TIMEOUT_MS = 30000; // 30s
+// ---------------------------------------------------------------------------
+// MCPBridge - the main bridge class
+// ---------------------------------------------------------------------------
+/**
+ * MCPBridge wraps a Palaryn Gateway instance as an MCP server, exposing
+ * the gateway's tool execution capabilities through the Model Context Protocol.
+ *
+ * Communication uses JSON-RPC 2.0 over stdio (line-delimited).
+ *
+ * It exposes three MCP tools:
+ * - `http_request` - Execute any HTTP request through the gateway
+ * - `http_get` - Shorthand for GET requests
+ * - `http_post` - Shorthand for POST requests
+ *
+ * Each tool constructs a proper ToolCall, runs it through the full gateway
+ * pipeline (policy, DLP, budget, rate limiting, execution), and returns
+ * the ToolResult as the MCP response.
+ *
+ * Supported MCP methods:
+ * - `initialize` - Protocol handshake (returns server info and capabilities)
+ * - `notifications/initialized` - Client acknowledgment (no-op notification)
+ * - `tools/list` - List available tools with their JSON schemas
+ * - `tools/call` - Execute a tool through the gateway
+ * - `ping` - Health check
+ */
+class MCPBridge {
+    constructor(gateway, bridgeConfig) {
+        this.transport = null;
+        this.initialized = false;
+        this.gateway = gateway;
+        this.bridgeConfig = {
+            ...DEFAULT_BRIDGE_CONFIG,
+            ...bridgeConfig,
+        };
+    }
+    /**
+     * Connect via stdio transport (reads from stdin, writes to stdout).
+     * This is the standard way to run an MCP server for CLI-based clients.
+     * Optionally accepts custom input/output streams for testing.
+     */
+    async connectStdio(input, output) {
+        this.transport = new StdioTransport(input, output);
+        this.transport.start((msg) => this.handleMessage(msg));
+    }
+    /**
+     * Close the transport and shut down the gateway.
+     */
+    async close() {
+        if (this.transport) {
+            this.transport.close();
+            this.transport = null;
+        }
+        this.gateway.shutdown();
+    }
+    /**
+     * Returns the underlying Gateway instance.
+     */
+    getGateway() {
+        return this.gateway;
+    }
+    /**
+     * Whether the MCP handshake has been completed.
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    // ---------------------------------------------------------------------------
+    // Message dispatch
+    // ---------------------------------------------------------------------------
+    /** Handle an incoming JSON-RPC message (request or notification). */
+    handleMessage(msg) {
+        // Notifications have no 'id' field
+        if (!('id' in msg) || msg.id === undefined) {
+            this.handleNotification(msg);
+            return;
+        }
+        const request = msg;
+        this.handleRequest(request).catch((err) => {
+            this.sendError(request.id, INTERNAL_ERROR, `Internal error: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    /** Handle a JSON-RPC notification (no response expected). */
+    handleNotification(msg) {
+        // The only notification we handle is `notifications/initialized`
+        if (msg.method === 'notifications/initialized') {
+            // Client acknowledges initialization is complete; no action needed.
+            return;
+        }
+        // Unknown notifications are silently ignored per MCP spec.
+    }
+    /** Handle a JSON-RPC request and send a response. */
+    async handleRequest(request) {
+        switch (request.method) {
+            case 'initialize':
+                this.handleInitialize(request);
+                break;
+            case 'tools/list':
+                this.handleToolsList(request);
+                break;
+            case 'tools/call':
+                await this.handleToolsCall(request);
+                break;
+            case 'ping':
+                this.sendResult(request.id, {});
+                break;
+            default:
+                this.sendError(request.id, METHOD_NOT_FOUND, `Method not found: ${request.method}`);
+                break;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // MCP method handlers
+    // ---------------------------------------------------------------------------
+    /** Handle `initialize` - protocol handshake. */
+    handleInitialize(request) {
+        this.initialized = true;
+        this.sendResult(request.id, {
+            protocolVersion: LATEST_PROTOCOL_VERSION,
+            capabilities: {
+                tools: {
+                    listChanged: false,
+                },
+            },
+            serverInfo: SERVER_INFO,
+        });
+    }
+    /** Handle `tools/list` - return all registered tool definitions. */
+    handleToolsList(request) {
+        this.sendResult(request.id, {
+            tools: ALL_TOOLS,
+        });
+    }
+    /** Handle `tools/call` - execute a tool through the gateway. */
+    async handleToolsCall(request) {
+        const params = request.params;
+        if (!params || typeof params.name !== 'string') {
+            this.sendError(request.id, INVALID_PARAMS, 'Missing required parameter: name');
+            return;
+        }
+        const toolName = params.name;
+        const toolArgs = (params.arguments || {});
+        let result;
+        try {
+            switch (toolName) {
+                case 'http_request':
+                    result = await this.executeHttpRequest(toolArgs);
+                    break;
+                case 'http_get':
+                    result = await this.executeHttpGet(toolArgs);
+                    break;
+                case 'http_post':
+                    result = await this.executeHttpPost(toolArgs);
+                    break;
+                default:
+                    this.sendError(request.id, INVALID_PARAMS, `Unknown tool: ${toolName}`);
+                    return;
+            }
+        }
+        catch (err) {
+            result = {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: err instanceof Error ? err.message : String(err),
+                            status: 'error',
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        this.sendResult(request.id, result);
+    }
+    // ---------------------------------------------------------------------------
+    // Tool execution methods
+    // ---------------------------------------------------------------------------
+    /** Execute `http_request` tool - arbitrary HTTP method. */
+    async executeHttpRequest(args) {
+        if (!args.url || typeof args.url !== 'string') {
+            return this.toolError('Missing required argument: url');
+        }
+        const method = (typeof args.method === 'string' ? args.method : 'GET').toUpperCase();
+        const capability = this.methodToCapability(method);
+        const toolCall = this.buildToolCall({
+            toolName: 'http.request',
+            capability,
+            args: {
+                method,
+                url: args.url,
+                headers: args.headers,
+                body: typeof args.body === 'string' ? this.parseBody(args.body) : undefined,
+            },
+            constraints: {
+                timeout_ms: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+                max_cost_usd: typeof args.max_cost_usd === 'number' ? args.max_cost_usd : undefined,
+            },
+            context: {
+                purpose: typeof args.purpose === 'string' ? args.purpose : undefined,
+                labels: Array.isArray(args.labels) ? args.labels : undefined,
+            },
+        });
+        return this.executeAndFormat(toolCall);
+    }
+    /** Execute `http_get` tool - GET request shorthand. */
+    async executeHttpGet(args) {
+        if (!args.url || typeof args.url !== 'string') {
+            return this.toolError('Missing required argument: url');
+        }
+        const toolCall = this.buildToolCall({
+            toolName: 'http.get',
+            capability: 'read',
+            args: {
+                method: 'GET',
+                url: args.url,
+                headers: args.headers,
+            },
+            constraints: {
+                timeout_ms: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+                max_cost_usd: typeof args.max_cost_usd === 'number' ? args.max_cost_usd : undefined,
+            },
+            context: {
+                purpose: typeof args.purpose === 'string' ? args.purpose : undefined,
+                labels: Array.isArray(args.labels) ? args.labels : undefined,
+            },
+        });
+        return this.executeAndFormat(toolCall);
+    }
+    /** Execute `http_post` tool - POST request shorthand. */
+    async executeHttpPost(args) {
+        if (!args.url || typeof args.url !== 'string') {
+            return this.toolError('Missing required argument: url');
+        }
+        const toolCall = this.buildToolCall({
+            toolName: 'http.post',
+            capability: 'write',
+            args: {
+                method: 'POST',
+                url: args.url,
+                headers: args.headers,
+                body: typeof args.body === 'string' ? this.parseBody(args.body) : undefined,
+            },
+            constraints: {
+                timeout_ms: typeof args.timeout_ms === 'number' ? args.timeout_ms : undefined,
+                max_cost_usd: typeof args.max_cost_usd === 'number' ? args.max_cost_usd : undefined,
+            },
+            context: {
+                purpose: typeof args.purpose === 'string' ? args.purpose : undefined,
+                labels: Array.isArray(args.labels) ? args.labels : undefined,
+            },
+        });
+        return this.executeAndFormat(toolCall);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Build a ToolCall from MCP tool arguments, applying bridge defaults.
+     */
+    buildToolCall(params) {
+        const toolCall = {
+            tool_call_id: (0, crypto_1.randomUUID)(),
+            task_id: this.bridgeConfig.task_id || (0, crypto_1.randomUUID)(),
+            workspace_id: this.bridgeConfig.workspace_id,
+            actor: { ...this.bridgeConfig.actor },
+            source: { ...this.bridgeConfig.source },
+            tool: {
+                name: params.toolName,
+                version: '1.0.0',
+                capability: params.capability,
+            },
+            args: params.args,
+            timestamp: new Date().toISOString(),
+        };
+        // Add constraints if any are specified
+        if (params.constraints?.timeout_ms != null || params.constraints?.max_cost_usd != null) {
+            toolCall.constraints = {};
+            if (params.constraints.timeout_ms != null) {
+                toolCall.constraints.timeout_ms = params.constraints.timeout_ms;
+            }
+            if (params.constraints.max_cost_usd != null) {
+                toolCall.constraints.max_cost_usd = params.constraints.max_cost_usd;
+            }
+        }
+        // Add context if any is specified
+        if (params.context?.purpose || params.context?.labels) {
+            toolCall.context = {};
+            if (params.context.purpose) {
+                toolCall.context.purpose = params.context.purpose;
+            }
+            if (params.context.labels) {
+                toolCall.context.labels = params.context.labels;
+            }
+        }
+        return toolCall;
+    }
+    /**
+     * Execute a ToolCall through the gateway and format as MCP result.
+     */
+    async executeAndFormat(toolCall) {
+        try {
+            const result = await this.gateway.execute(toolCall);
+            return this.formatResult(result);
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            tool_call_id: toolCall.tool_call_id,
+                            status: 'error',
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    /**
+     * Convert a gateway ToolResult into an MCP CallToolResult.
+     *
+     * The result includes:
+     * - The tool output body (or error message) as the primary text content
+     * - Gateway metadata (status, policy decision, DLP report, budget, timing)
+     *   as a second text content block for transparency
+     */
+    formatResult(result) {
+        const isError = result.status === 'error' || result.status === 'blocked';
+        // Primary content: the actual output or error
+        let primaryText;
+        if (result.error) {
+            primaryText = result.error;
+        }
+        else if (result.output?.body !== undefined) {
+            primaryText =
+                typeof result.output.body === 'string'
+                    ? result.output.body
+                    : JSON.stringify(result.output.body, null, 2);
+        }
+        else {
+            primaryText = `Request completed with status: ${result.status}`;
+        }
+        // Metadata block for gateway transparency
+        const metadata = {
+            tool_call_id: result.tool_call_id,
+            task_id: result.task_id,
+            status: result.status,
+            policy: result.policy,
+            dlp: {
+                detected: result.dlp.detected,
+                severity: result.dlp.severity,
+                redaction_count: result.dlp.redactions.length,
+            },
+            budget: result.budget,
+            timing: result.timing,
+            http_status: result.output?.http_status,
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: primaryText,
+                },
+                {
+                    type: 'text',
+                    text: `--- Gateway Metadata ---\n${JSON.stringify(metadata, null, 2)}`,
+                },
+            ],
+            isError,
+        };
+    }
+    /**
+     * Map an HTTP method to a ToolInfo capability level.
+     */
+    methodToCapability(method) {
+        switch (method.toUpperCase()) {
+            case 'GET':
+            case 'HEAD':
+            case 'OPTIONS':
+                return 'read';
+            case 'POST':
+            case 'PUT':
+            case 'PATCH':
+                return 'write';
+            case 'DELETE':
+                return 'delete';
+            default:
+                return 'write';
+        }
+    }
+    /**
+     * Attempt to parse a body string as JSON, falling back to the raw string.
+     */
+    parseBody(body) {
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return body;
+        }
+    }
+    /**
+     * Create an MCP tool error result.
+     */
+    toolError(message) {
+        return {
+            content: [{ type: 'text', text: message }],
+            isError: true,
+        };
+    }
+    /**
+     * Send a successful JSON-RPC response.
+     */
+    sendResult(id, result) {
+        if (this.transport) {
+            this.transport.send({
+                jsonrpc: JSONRPC_VERSION,
+                id,
+                result,
+            });
+        }
+    }
+    /**
+     * Send a JSON-RPC error response.
+     */
+    sendError(id, code, message, data) {
+        if (this.transport) {
+            this.transport.send({
+                jsonrpc: JSONRPC_VERSION,
+                id,
+                error: { code, message, data },
+            });
+        }
+    }
+}
+exports.MCPBridge = MCPBridge;
+// ---------------------------------------------------------------------------
+// Convenience entry point
+// ---------------------------------------------------------------------------
+/**
+ * Create a Gateway instance with the given config (or defaults),
+ * wrap it in an MCPBridge, and connect via stdio transport.
+ *
+ * This is the main entry point for running Palaryn as an MCP server.
+ *
+ * @param gatewayConfig - Full gateway configuration (defaults to DEFAULT_CONFIG with auth disabled)
+ * @param bridgeConfig - MCP bridge defaults for workspace, actor, source
+ * @returns The connected MCPBridge instance
+ */
+async function startMCPBridge(gatewayConfig, bridgeConfig) {
+    // Merge with defaults, disabling auth for MCP (auth is handled by the MCP client/transport)
+    const config = {
+        ...defaults_1.DEFAULT_CONFIG,
+        ...gatewayConfig,
+        auth: {
+            ...defaults_1.DEFAULT_CONFIG.auth,
+            enabled: false,
+            ...gatewayConfig?.auth,
+        },
+        // Disable console audit output when running as MCP server
+        // to avoid polluting stdout (which is the MCP transport channel)
+        audit: {
+            ...defaults_1.DEFAULT_CONFIG.audit,
+            console_output: false,
+            ...gatewayConfig?.audit,
+        },
+    };
+    const gateway = new gateway_1.Gateway(config);
+    const bridge = new MCPBridge(gateway, bridgeConfig);
+    await bridge.connectStdio();
+    return bridge;
+}
+//# sourceMappingURL=bridge.js.map