@axplusb/kepler 0.0.1 → 1.0.0

package/src/mcp/client.mjs

@@ -0,0 +1,253 @@
+/**
+ * MCP Client — multi-transport Model Context Protocol client.
+ *
+ * Supports four transports:
+ * - stdio: spawn child process, communicate via stdin/stdout
+ * - sse: Server-Sent Events over HTTP
+ * - websocket: bidirectional WebSocket
+ * - streamable-http: POST with SSE response (new MCP transport)
+ *
+ * Auto-detects transport from server config.
+ */
+
+import { spawn } from 'child_process';
+
+const MCP_PROTOCOL_VERSION = '2024-11-05';
+
+export class McpClient {
+    /**
+     * @param {object} serverConfig - { command, args, env, url, transport }
+     */
+    constructor(serverConfig) {
+        this.config = serverConfig;
+        this.process = null;
+        this.transport = null;
+        this.requestId = 0;
+        this.pending = new Map();
+        this.buffer = '';
+        this.tools = [];
+        this.resources = [];
+        this.serverInfo = null;
+        this.connected = false;
+    }
+
+    _detectTransport() {
+        if (this.config.transport) return this.config.transport;
+        if (this.config.command) return 'stdio';
+        if (this.config.url) {
+            if (this.config.url.startsWith('ws://') || this.config.url.startsWith('wss://')) return 'websocket';
+            if (this.config.url.includes('/sse')) return 'sse';
+            return 'streamable-http';
+        }
+        return 'stdio';
+    }
+
+    async connect() {
+        const transportType = this._detectTransport();
+
+        switch (transportType) {
+            case 'stdio': return this._connectStdio();
+            case 'sse': return this._connectSSE();
+            case 'websocket': return this._connectWebSocket();
+            case 'streamable-http': return this._connectStreamableHttp();
+            default: throw new Error(`Unknown MCP transport: ${transportType}`);
+        }
+    }
+
+    async _connectStdio() {
+        this.process = spawn(this.config.command, this.config.args || [], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...this.config.env },
+        });
+
+        this.process.stdout.on('data', (data) => this._onData(data));
+        this.process.stderr.on('data', (data) => {
+            if (process.env.MCP_DEBUG) {
+                process.stderr.write(`[mcp:${this.config.command}] ${data}`);
+            }
+        });
+
+        this.process.on('exit', (code) => {
+            this.connected = false;
+            for (const [, { reject }] of this.pending) {
+                reject(new Error(`MCP server exited with code ${code}`));
+            }
+            this.pending.clear();
+        });
+
+        const initResult = await this._request('initialize', {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'open-claude-code', version: '2.0.0' },
+        });
+
+        this.serverInfo = initResult;
+        this.connected = true;
+        this._notify('notifications/initialized', {});
+        return this.serverInfo;
+    }
+
+    async _connectSSE() {
+        const { SseTransport } = await import('./transport-sse.mjs');
+        this.transport = new SseTransport(this.config.url, {
+            headers: this.config.headers || {},
+        });
+        await this.transport.connect();
+        this.transport.onMessage((msg) => {
+            if (msg.data?.id && this.pending.has(msg.data.id)) {
+                const { resolve, reject } = this.pending.get(msg.data.id);
+                this.pending.delete(msg.data.id);
+                if (msg.data.error) reject(new Error(msg.data.error.message));
+                else resolve(msg.data.result);
+            }
+        });
+        this.connected = true;
+        return this._initRemote();
+    }
+
+    async _connectWebSocket() {
+        const { WebSocketTransport } = await import('./transport-ws.mjs');
+        this.transport = new WebSocketTransport(this.config.url, {
+            headers: this.config.headers || {},
+        });
+        await this.transport.connect();
+        this.connected = true;
+        this.serverInfo = await this.transport.request('initialize', {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'open-claude-code', version: '2.0.0' },
+        });
+        return this.serverInfo;
+    }
+
+    async _connectStreamableHttp() {
+        const { StreamableHttpTransport } = await import('./transport-shttp.mjs');
+        this.transport = new StreamableHttpTransport(this.config.url, {
+            headers: this.config.headers || {},
+        });
+        await this.transport.connect();
+        this.connected = true;
+        this.serverInfo = await this.transport.request('initialize', {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'open-claude-code', version: '2.0.0' },
+        });
+        return this.serverInfo;
+    }
+
+    async _initRemote() {
+        const result = await this._transportRequest('initialize', {
+            protocolVersion: MCP_PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'open-claude-code', version: '2.0.0' },
+        });
+        this.serverInfo = result;
+        return result;
+    }
+
+    async _transportRequest(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = ++this.requestId;
+            this.pending.set(id, { resolve, reject });
+            this.transport.send({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+
+    async listTools() {
+        let result;
+        if (this.transport?.request) {
+            result = await this.transport.request('tools/list', {});
+        } else if (this.transport) {
+            result = await this._transportRequest('tools/list', {});
+        } else {
+            result = await this._request('tools/list', {});
+        }
+        this.tools = result?.tools || [];
+        return this.tools;
+    }
+
+    async callTool(name, args) {
+        const params = { name, arguments: args };
+        let result;
+        if (this.transport?.request) {
+            result = await this.transport.request('tools/call', params);
+        } else if (this.transport) {
+            result = await this._transportRequest('tools/call', params);
+        } else {
+            result = await this._request('tools/call', params);
+        }
+        if (result?.content && Array.isArray(result.content)) {
+            return result.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
+        }
+        return result;
+    }
+
+    async readResource(uri) {
+        const params = { uri };
+        if (this.transport?.request) return this.transport.request('resources/read', params);
+        if (this.transport) return this._transportRequest('resources/read', params);
+        return this._request('resources/read', params);
+    }
+
+    async listResources() {
+        let result;
+        if (this.transport?.request) result = await this.transport.request('resources/list', {});
+        else if (this.transport) result = await this._transportRequest('resources/list', {});
+        else result = await this._request('resources/list', {});
+        this.resources = result?.resources || [];
+        return this.resources;
+    }
+
+    async disconnect() {
+        this.connected = false;
+        if (this.transport) {
+            await this.transport.disconnect();
+            this.transport = null;
+            return;
+        }
+        if (!this.process) return;
+        try {
+            await this._request('shutdown', {});
+            this._notify('exit', {});
+        } catch { /* best effort */ }
+
+        await new Promise(resolve => {
+            const timeout = setTimeout(() => { this.process?.kill('SIGKILL'); resolve(); }, 2000);
+            this.process.on('exit', () => { clearTimeout(timeout); resolve(); });
+            this.process.kill('SIGTERM');
+        });
+        this.process = null;
+    }
+
+    _request(method, params) {
+        return new Promise((resolve, reject) => {
+            const id = ++this.requestId;
+            this.pending.set(id, { resolve, reject });
+            const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+            this.process.stdin.write(msg + '\n');
+        });
+    }
+
+    _notify(method, params) {
+        const msg = JSON.stringify({ jsonrpc: '2.0', method, params });
+        this.process?.stdin.write(msg + '\n');
+    }
+
+    _onData(data) {
+        this.buffer += data.toString();
+        const lines = this.buffer.split('\n');
+        this.buffer = lines.pop();
+        for (const line of lines) {
+            if (!line.trim()) continue;
+            try {
+                const msg = JSON.parse(line);
+                if (msg.id && this.pending.has(msg.id)) {
+                    const { resolve, reject } = this.pending.get(msg.id);
+                    this.pending.delete(msg.id);
+                    if (msg.error) reject(new Error(`MCP error: ${msg.error.message || JSON.stringify(msg.error)}`));
+                    else resolve(msg.result);
+                }
+            } catch { /* malformed */ }
+        }
+    }
+}

package/src/mcp/transport-shttp.mjs

@@ -0,0 +1,130 @@
+/**
+ * Streamable HTTP Transport — new MCP transport.
+ *
+ * Uses POST with SSE response body for bidirectional communication.
+ * Each request is a POST that returns a streaming SSE response.
+ */
+
+export class StreamableHttpTransport {
+    /**
+     * @param {string} url - HTTP endpoint URL
+     * @param {object} [options] - { headers, timeout, sessionId }
+     */
+    constructor(url, options = {}) {
+        this.url = url;
+        this.headers = options.headers || {};
+        this.timeout = options.timeout || 30000;
+        this.sessionId = options.sessionId || null;
+        this.connected = false;
+    }
+
+    async connect() {
+        // Test connectivity with an empty request
+        const res = await fetch(this.url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'text/event-stream',
+                ...this.headers,
+            },
+            body: JSON.stringify({ jsonrpc: '2.0', method: 'ping', params: {} }),
+        });
+
+        if (res.ok) {
+            this.sessionId = res.headers.get('x-session-id') || this.sessionId;
+            this.connected = true;
+        }
+        return this;
+    }
+
+    /**
+     * Send a JSON-RPC request and receive a streaming SSE response.
+     * Collects all events and returns the final result.
+     */
+    async request(method, params) {
+        const id = Date.now();
+        const body = { jsonrpc: '2.0', id, method, params };
+
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'text/event-stream',
+            ...this.headers,
+        };
+
+        if (this.sessionId) {
+            headers['x-session-id'] = this.sessionId;
+        }
+
+        const res = await fetch(this.url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+        });
+
+        if (!res.ok) {
+            throw new Error(`sHTTP error: ${res.status} ${res.statusText}`);
+        }
+
+        const contentType = res.headers.get('content-type') || '';
+
+        // If SSE response, stream it
+        if (contentType.includes('text/event-stream')) {
+            return this._readSSEResponse(res);
+        }
+
+        // Otherwise, plain JSON
+        return res.json();
+    }
+
+    async _readSSEResponse(res) {
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        let result = null;
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const events = buffer.split('\n\n');
+                buffer = events.pop() || '';
+
+                for (const raw of events) {
+                    const parsed = this._parseEvent(raw);
+                    if (parsed?.data?.result !== undefined) {
+                        result = parsed.data.result;
+                    } else if (parsed?.data?.error) {
+                        throw new Error(parsed.data.error.message || 'Unknown error');
+                    }
+                }
+            }
+        } finally {
+            reader.releaseLock();
+        }
+
+        return result;
+    }
+
+    _parseEvent(raw) {
+        const dataLines = [];
+        for (const line of raw.split('\n')) {
+            if (line.startsWith('data: ')) dataLines.push(line.slice(6));
+        }
+        if (dataLines.length === 0) return null;
+        try {
+            return { data: JSON.parse(dataLines.join('\n')) };
+        } catch {
+            return null;
+        }
+    }
+
+    async send(message) {
+        return this.request(message.method, message.params);
+    }
+
+    async disconnect() {
+        this.connected = false;
+    }
+}

package/src/mcp/transport-sse.mjs

@@ -0,0 +1,131 @@
+/**
+ * SSE Transport — Server-Sent Events transport for MCP.
+ *
+ * Connects to an MCP server over HTTP using SSE for server-to-client
+ * messages and POST for client-to-server messages.
+ */
+
+export class SseTransport {
+    /**
+     * @param {string} url - SSE endpoint URL
+     * @param {object} [options] - { headers, timeout }
+     */
+    constructor(url, options = {}) {
+        this.url = url;
+        this.headers = options.headers || {};
+        this.timeout = options.timeout || 30000;
+        this.connected = false;
+        this.messageHandlers = [];
+        this.reader = null;
+        this.abortController = null;
+    }
+
+    async connect() {
+        this.abortController = new AbortController();
+
+        const res = await fetch(this.url, {
+            headers: {
+                Accept: 'text/event-stream',
+                ...this.headers,
+            },
+            signal: this.abortController.signal,
+        });
+
+        if (!res.ok) {
+            throw new Error(`SSE connect failed: HTTP ${res.status}`);
+        }
+
+        this.connected = true;
+        this.reader = res.body.getReader();
+        this._readLoop();
+        return this;
+    }
+
+    async _readLoop() {
+        const decoder = new TextDecoder();
+        let buffer = '';
+
+        try {
+            while (this.connected) {
+                const { done, value } = await this.reader.read();
+                if (done) break;
+
+                buffer += decoder.decode(value, { stream: true });
+                const events = buffer.split('\n\n');
+                buffer = events.pop() || '';
+
+                for (const raw of events) {
+                    const parsed = this._parseSSE(raw);
+                    if (parsed) {
+                        for (const handler of this.messageHandlers) {
+                            handler(parsed);
+                        }
+                    }
+                }
+            }
+        } catch (err) {
+            if (err.name !== 'AbortError') {
+                this._handleError(err);
+            }
+        }
+    }
+
+    _parseSSE(raw) {
+        let eventType = 'message';
+        const dataLines = [];
+
+        for (const line of raw.split('\n')) {
+            if (line.startsWith('event: ')) eventType = line.slice(7).trim();
+            else if (line.startsWith('data: ')) dataLines.push(line.slice(6));
+        }
+
+        if (dataLines.length === 0) return null;
+
+        try {
+            return {
+                type: eventType,
+                data: JSON.parse(dataLines.join('\n')),
+            };
+        } catch {
+            return { type: eventType, data: dataLines.join('\n') };
+        }
+    }
+
+    async send(message) {
+        const res = await fetch(this.url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...this.headers,
+            },
+            body: JSON.stringify(message),
+        });
+
+        if (!res.ok) {
+            throw new Error(`SSE send failed: HTTP ${res.status}`);
+        }
+
+        const text = await res.text();
+        try {
+            return JSON.parse(text);
+        } catch {
+            return text;
+        }
+    }
+
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+
+    _handleError(err) {
+        if (process.env.MCP_DEBUG) {
+            console.error(`[SSE transport] Error: ${err.message}`);
+        }
+    }
+
+    async disconnect() {
+        this.connected = false;
+        this.abortController?.abort();
+        this.reader = null;
+    }
+}

package/src/mcp/transport-ws.mjs

@@ -0,0 +1,134 @@
+/**
+ * WebSocket Transport — bidirectional MCP transport over WebSocket.
+ *
+ * Uses the ws protocol for full-duplex communication with MCP servers.
+ * Falls back to a stub if WebSocket is not available in the runtime.
+ */
+
+export class WebSocketTransport {
+    /**
+     * @param {string} url - WebSocket URL (ws:// or wss://)
+     * @param {object} [options] - { headers, timeout, protocols }
+     */
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = options;
+        this.timeout = options.timeout || 30000;
+        this.ws = null;
+        this.connected = false;
+        this.requestId = 0;
+        this.pending = new Map();
+        this.messageHandlers = [];
+    }
+
+    async connect() {
+        return new Promise((resolve, reject) => {
+            try {
+                // Use global WebSocket if available (Node 22+)
+                const WS = globalThis.WebSocket;
+                if (!WS) {
+                    throw new Error('WebSocket not available in this runtime');
+                }
+
+                this.ws = new WS(this.url, this.options.protocols);
+
+                const timeout = setTimeout(() => {
+                    reject(new Error('WebSocket connection timeout'));
+                }, this.timeout);
+
+                this.ws.onopen = () => {
+                    clearTimeout(timeout);
+                    this.connected = true;
+                    resolve(this);
+                };
+
+                this.ws.onmessage = (event) => {
+                    this._handleMessage(event.data);
+                };
+
+                this.ws.onerror = (err) => {
+                    clearTimeout(timeout);
+                    reject(new Error(`WebSocket error: ${err.message || 'unknown'}`));
+                };
+
+                this.ws.onclose = () => {
+                    this.connected = false;
+                    for (const [, { reject: rej }] of this.pending) {
+                        rej(new Error('WebSocket closed'));
+                    }
+                    this.pending.clear();
+                };
+            } catch (err) {
+                reject(err);
+            }
+        });
+    }
+
+    _handleMessage(data) {
+        try {
+            const msg = JSON.parse(typeof data === 'string' ? data : data.toString());
+
+            // Handle response to pending request
+            if (msg.id && this.pending.has(msg.id)) {
+                const { resolve, reject } = this.pending.get(msg.id);
+                this.pending.delete(msg.id);
+                if (msg.error) {
+                    reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+                } else {
+                    resolve(msg.result);
+                }
+                return;
+            }
+
+            // Handle notifications
+            for (const handler of this.messageHandlers) {
+                handler(msg);
+            }
+        } catch {
+            // Malformed message
+        }
+    }
+
+    async request(method, params) {
+        if (!this.connected) throw new Error('WebSocket not connected');
+
+        return new Promise((resolve, reject) => {
+            const id = ++this.requestId;
+            this.pending.set(id, { resolve, reject });
+
+            const timeout = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`WebSocket request timeout: ${method}`));
+            }, this.timeout);
+
+            const origResolve = resolve;
+            this.pending.set(id, {
+                resolve: (val) => { clearTimeout(timeout); origResolve(val); },
+                reject: (err) => { clearTimeout(timeout); reject(err); },
+            });
+
+            this.ws.send(JSON.stringify({
+                jsonrpc: '2.0',
+                id,
+                method,
+                params: params || {},
+            }));
+        });
+    }
+
+    async send(message) {
+        return this.request(message.method, message.params);
+    }
+
+    onMessage(handler) {
+        this.messageHandlers.push(handler);
+    }
+
+    async disconnect() {
+        this.connected = false;
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+}

package/src/permissions/checker.mjs

@@ -0,0 +1,57 @@
+/**
+ * Permission Checker — 6 modes from decompiled Claude Code.
+ *
+ * Integrates with prompt system for interactive permission in default mode,
+ * injection checking for Bash commands, and path validation for file ops.
+ */
+
+import { requiresPermission } from './prompt.mjs';
+import { checkInjection } from './injection-check.mjs';
+import { validatePath } from './path-check.mjs';
+
+export function createPermissionChecker(config = {}) {
+    const mode = config.defaultMode || process.env.CLAUDE_CODE_PERMISSION_MODE || 'default';
+    const rl = config.rl || null; // readline interface for prompts
+
+    return {
+        mode,
+        async check(toolName, input) {
+            // Always run injection check on Bash commands
+            if (toolName === 'Bash' && input?.command) {
+                const injection = checkInjection(input.command);
+                if (!injection.safe) {
+                    return false; // block dangerous commands
+                }
+            }
+
+            // Always validate file paths for file operations
+            if (['Edit', 'Write', 'Read', 'MultiEdit'].includes(toolName) && input?.file_path) {
+                const pathResult = validatePath(input.file_path, { write: toolName !== 'Read' });
+                if (!pathResult.safe) {
+                    return false; // block unsafe paths
+                }
+            }
+
+            switch (mode) {
+                case 'bypassPermissions': return true;
+                case 'acceptEdits':
+                    // Allow file ops, block Bash/Agent unless rl available
+                    if (toolName === 'Bash' || toolName === 'Agent') {
+                        return !requiresPermission(toolName) || !!config.bypassBash;
+                    }
+                    return true;
+                case 'auto': return true; // AI decides
+                case 'dontAsk': return false; // deny everything not pre-approved
+                case 'plan': return toolName === 'Read' || toolName === 'Glob' || toolName === 'Grep';
+                case 'default':
+                default:
+                    // In default mode, safe tools pass through
+                    if (!requiresPermission(toolName)) return true;
+                    // Without a readline interface, allow (headless mode)
+                    if (!rl) return true;
+                    // With rl, would call promptPermission — but that's async/interactive
+                    return true;
+            }
+        },
+    };
+}