claude-simple 0.2.9 → 0.2.10

package/src/mcp.js

@@ -0,0 +1,275 @@
+import crypto from 'crypto';
+
+// A deliberately small MCP implementation.  The Streamable HTTP transport is
+// JSON-RPC over POST; none of the tools need a long-lived server-side session.
+export const MCP_PROTOCOL_VERSION = '2025-03-26';
+
+const MAX_EVENTS = 100;
+const MAX_OUTPUT_CHARS = 12_000;
+const MAX_HISTORY_MESSAGES = 2_000;
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+function digest(value) {
+  return crypto.createHash('sha256').update(JSON.stringify(value)).digest('base64url');
+}
+
+export function encodeSessionCursor({ sessionId, agent, count, prefix }) {
+  return Buffer.from(JSON.stringify({ v: 1, sessionId, agent, count, prefix })).toString('base64url');
+}
+
+export function decodeSessionCursor(cursor) {
+  if (typeof cursor !== 'string' || cursor.length > 2_000) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+    if (parsed?.v !== 1 || typeof parsed.sessionId !== 'string' || typeof parsed.agent !== 'string'
+      || !Number.isInteger(parsed.count) || parsed.count < 0 || typeof parsed.prefix !== 'string') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function jsonText(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+
+function toolError(message) {
+  return { content: [{ type: 'text', text: message }], isError: true };
+}
+
+function stringArg(args, key, { required = false, max = 0 } = {}) {
+  const value = args?.[key];
+  if (value == null || value === '') {
+    if (required) throw new Error(`${key} is required`);
+    return undefined;
+  }
+  if (typeof value !== 'string') throw new Error(`${key} must be a string`);
+  const result = value.trim();
+  if (required && !result) throw new Error(`${key} is required`);
+  if (max && result.length > max) throw new Error(`${key} is too long (max ${max})`);
+  return result;
+}
+
+function boundedInt(value, fallback, min, max) {
+  if (value == null) return fallback;
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new Error(`must be an integer between ${min} and ${max}`);
+  }
+  return value;
+}
+
+function sessionIdArg(args) {
+  const sessionId = stringArg(args, 'sessionId', { required: true, max: 200 });
+  if (!SESSION_ID_RE.test(sessionId)) throw new Error('sessionId must be a UUID');
+  return sessionId;
+}
+
+function conciseEvent(event) {
+  const out = {
+    type: event?.type || 'unknown',
+    agent: event?.agent,
+    sessionId: event?.sessionId,
+  };
+  if (typeof event?.message === 'string') out.message = event.message.slice(0, 2_000);
+  if (typeof event?.result === 'string') out.result = event.result.slice(0, 4_000);
+  if (typeof event?.data === 'string') out.data = event.data.slice(0, 4_000);
+  if (event?.exitCode != null) out.exitCode = event.exitCode;
+  if (event?.aborted) out.aborted = true;
+  return out;
+}
+
+export const MCP_TOOLS = [
+  {
+    name: 'session_list',
+    description: 'List saved Claude, Codex, Grok, Gemini, and Cursor sessions. Use updatedSince for inexpensive polling.',
+    inputSchema: {
+      type: 'object', properties: {
+        agent: { type: 'string', enum: ['claude', 'codex', 'grok', 'gemini', 'cursor'] },
+        cwd: { type: 'string' }, updatedSince: { type: 'number' }, limit: { type: 'integer', minimum: 1, maximum: 800 },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_get',
+    description: 'Read a session history. Returns a cursor that can be supplied to session_changes for append-only incremental updates.',
+    inputSchema: {
+      type: 'object', required: ['sessionId'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, tail: { type: 'integer', minimum: 0, maximum: 50000 },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_changes',
+    description: 'Get changes since a cursor from session_get/session_changes. It returns only added messages when history is append-only; mode=reset means old history changed and should be fetched again.',
+    inputSchema: {
+      type: 'object', required: ['sessionId', 'cursor'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, cursor: { type: 'string' }, limit: { type: 'integer', minimum: 1, maximum: 2000 },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_create',
+    description: 'Create a real agent session by running its first prompt. Waits for the turn to finish and returns the newly assigned sessionId.',
+    inputSchema: {
+      type: 'object', required: ['prompt'], properties: {
+        agent: { type: 'string', enum: ['claude', 'codex', 'grok', 'gemini', 'cursor'] }, prompt: { type: 'string', minLength: 1 }, cwd: { type: 'string' },
+        model: { type: 'string' }, effort: { type: 'string' }, permissionMode: { type: 'string', enum: ['default', 'acceptEdits', 'auto', 'bypassPermissions'] },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_run',
+    description: 'Run one more prompt in an existing session. This is synchronous and returns a compact event transcript.',
+    inputSchema: {
+      type: 'object', required: ['sessionId', 'prompt'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, prompt: { type: 'string', minLength: 1 }, cwd: { type: 'string' },
+        model: { type: 'string' }, effort: { type: 'string' }, permissionMode: { type: 'string', enum: ['default', 'acceptEdits', 'auto', 'bypassPermissions'] },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_resume',
+    description: 'Alias of session_run with an explicit resume intent. Use it to continue a session with a new prompt.',
+    inputSchema: {
+      type: 'object', required: ['sessionId', 'prompt'], properties: {
+        sessionId: { type: 'string' }, agent: { type: 'string' }, prompt: { type: 'string', minLength: 1 }, cwd: { type: 'string' },
+        model: { type: 'string' }, effort: { type: 'string' }, permissionMode: { type: 'string', enum: ['default', 'acceptEdits', 'auto', 'bypassPermissions'] },
+      }, additionalProperties: false,
+    },
+  },
+  {
+    name: 'session_abort',
+    description: 'Interrupt the active run for a session.',
+    inputSchema: { type: 'object', required: ['sessionId'], properties: { sessionId: { type: 'string' } }, additionalProperties: false },
+  },
+];
+
+/**
+ * Create the MCP domain layer. Dependencies are injected so the protocol and
+ * cursor rules are testable without a running HTTP server or installed CLIs.
+ */
+export function createMcpService({ listSessions, readSession, dispatchAgent, abortSession, isSessionBusy, enabledAgents, toClientSession = (s) => s }) {
+  const validAgents = new Set(enabledAgents || []);
+
+  function agentArg(args, fallback = 'claude') {
+    const agent = (stringArg(args, 'agent', { max: 32 }) || fallback).toLowerCase();
+    if (!validAgents.has(agent)) throw new Error(`agent must be one of: ${[...validAgents].join(', ')}`);
+    return agent;
+  }
+
+  async function sessionSnapshot(sessionId, preferredAgent) {
+    const bundle = await readSession(sessionId, preferredAgent);
+    if (!bundle) throw new Error('Session not found');
+    const messages = Array.isArray(bundle.messages) ? bundle.messages : [];
+    const agent = bundle.agent || preferredAgent || 'claude';
+    return { ...bundle, agent, messages };
+  }
+
+  async function run(args, { creating = false, resumed = false } = {}) {
+    const prompt = stringArg(args, 'prompt', { required: true, max: 200_000 });
+    const agent = agentArg(args);
+    const sessionId = creating ? undefined : sessionIdArg(args);
+    if (sessionId && isSessionBusy(sessionId)) throw new Error('Session is already running');
+    const options = { sessionId, cwd: stringArg(args, 'cwd', { max: 4_000 }), model: stringArg(args, 'model', { max: 200 }), effort: stringArg(args, 'effort', { max: 100 }) };
+    // Codex otherwise defaults to yolo when no mode is supplied. MCP callers
+    // must explicitly opt into a broader permissionMode.
+    options.mode = agent === 'codex' ? 'suggest' : undefined;
+    options.permissionMode = stringArg(args, 'permissionMode', { max: 64 }) || 'acceptEdits';
+    const events = [];
+    let eventCount = 0;
+    let createdSessionId = sessionId || null;
+    let output = '';
+    await dispatchAgent(agent, prompt, options, (event) => {
+      if (event?.sessionId) createdSessionId = event.sessionId;
+      if (event?.type === 'assistant_delta' && typeof event.data === 'string') output += event.data;
+      if (event?.type === 'result' && typeof event.result === 'string') output += event.result;
+      eventCount++;
+      if (events.length < MAX_EVENTS) events.push(conciseEvent(event));
+    });
+    return {
+      created: creating, resumed, agent, sessionId: createdSessionId || sessionId,
+      output: output.slice(-MAX_OUTPUT_CHARS), events, eventsTruncated: eventCount > MAX_EVENTS,
+    };
+  }
+
+  async function call(name, args = {}) {
+    switch (name) {
+      case 'session_list': {
+        const agent = args.agent == null ? null : agentArg(args);
+        const cwd = stringArg(args, 'cwd', { max: 4_000 });
+        const since = args.updatedSince == null ? 0 : Number(args.updatedSince);
+        if (!Number.isFinite(since) || since < 0) throw new Error('updatedSince must be a Unix millisecond timestamp');
+        const limit = boundedInt(args.limit, 100, 1, 800);
+        let sessions = await listSessions(cwd || null, agent);
+        if (since) sessions = sessions.filter((s) => Number(s.updatedAt || 0) > since);
+        sessions.sort((a, b) => Number(b.updatedAt || 0) - Number(a.updatedAt || 0));
+        return { sessions: sessions.slice(0, limit).map(toClientSession), nextUpdatedSince: sessions[0]?.updatedAt || since || Date.now(), truncated: sessions.length > limit };
+      }
+      case 'session_get': {
+        const sessionId = sessionIdArg(args);
+        const snapshot = await sessionSnapshot(sessionId, stringArg(args, 'agent', { max: 32 }));
+        const tail = boundedInt(args.tail, 0, 0, 50_000);
+        const all = snapshot.messages;
+        const messages = tail > 0 ? all.slice(-tail) : all.slice(-MAX_HISTORY_MESSAGES);
+        const returnedFrom = all.length - messages.length;
+        return {
+          sessionId, agent: snapshot.agent, context: snapshot.context || null, total: all.length, returnedFrom, messages,
+          truncated: returnedFrom > 0,
+          cursor: encodeSessionCursor({ sessionId, agent: snapshot.agent, count: all.length, prefix: digest(all) }),
+        };
+      }
+      case 'session_changes': {
+        const sessionId = sessionIdArg(args);
+        const cursor = decodeSessionCursor(stringArg(args, 'cursor', { required: true, max: 2_000 }));
+        if (!cursor || cursor.sessionId !== sessionId) throw new Error('cursor is invalid for this session');
+        const requestedAgent = stringArg(args, 'agent', { max: 32 });
+        if (requestedAgent && requestedAgent !== cursor.agent) throw new Error('cursor agent does not match agent');
+        const snapshot = await sessionSnapshot(sessionId, cursor.agent);
+        const limit = boundedInt(args.limit, MAX_HISTORY_MESSAGES, 1, MAX_HISTORY_MESSAGES);
+        const prefixMatches = snapshot.agent === cursor.agent && cursor.count <= snapshot.messages.length
+          && digest(snapshot.messages.slice(0, cursor.count)) === cursor.prefix;
+        const nextCursor = encodeSessionCursor({ sessionId, agent: snapshot.agent, count: snapshot.messages.length, prefix: digest(snapshot.messages) });
+        if (!prefixMatches) {
+          return { mode: 'reset', sessionId, agent: snapshot.agent, total: snapshot.messages.length, cursor: nextCursor,
+            reason: 'session history was rewritten or the cursor is stale; call session_get again' };
+        }
+        const added = snapshot.messages.slice(cursor.count, cursor.count + limit);
+        return { mode: 'diff', sessionId, agent: snapshot.agent, from: cursor.count, total: snapshot.messages.length,
+          added, hasMore: cursor.count + added.length < snapshot.messages.length, cursor: nextCursor };
+      }
+      case 'session_create': return run(args, { creating: true });
+      case 'session_run': return run(args);
+      case 'session_resume': return run(args, { resumed: true });
+      case 'session_abort': {
+        const sessionId = sessionIdArg(args);
+        return { sessionId, aborted: !!abortSession(sessionId) };
+      }
+      default: throw new Error(`Unknown tool: ${name}`);
+    }
+  }
+
+  return { call };
+}
+
+export function createMcpHttpHandler({ service, authenticate }) {
+  return async (req, res) => {
+    const rpc = req.body;
+    const id = rpc?.id;
+    const reply = (result) => res.json({ jsonrpc: '2.0', id: id ?? null, result });
+    const rpcError = (code, message) => res.status(code === -32600 ? 400 : 200).json({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+    if (!rpc || rpc.jsonrpc !== '2.0' || typeof rpc.method !== 'string') return rpcError(-32600, 'Invalid JSON-RPC request');
+    if (!authenticate(req)) return res.status(401).json({ jsonrpc: '2.0', id: id ?? null, error: { code: -32001, message: 'Valid MCP bearer token required' } });
+    if (rpc.method === 'initialize') {
+      return reply({ protocolVersion: MCP_PROTOCOL_VERSION, capabilities: { tools: { listChanged: false } }, serverInfo: { name: 'claude-simple-sessions', version: '0.2.9' } });
+    }
+    if (rpc.method === 'notifications/initialized') return res.status(202).end();
+    if (rpc.method === 'ping') return reply({});
+    if (rpc.method === 'tools/list') return reply({ tools: MCP_TOOLS });
+    if (rpc.method === 'tools/call') {
+      if (typeof rpc.params?.name !== 'string') return rpcError(-32602, 'tools/call requires params.name');
+      try { return reply(await service.call(rpc.params.name, rpc.params.arguments || {})); }
+      catch (error) { return reply(toolError(error instanceof Error ? error.message : String(error))); }
+    }
+    return rpcError(-32601, `Method not found: ${rpc.method}`);
+  };
+}