codex-workspace-codegraph-mcp 0.2.0

package/docs/ARCHITECTURE.md

@@ -0,0 +1,70 @@
+# Architecture
+
+```text
+MCP client
+  ├─ newline-delimited JSON-RPC over stdio
+  └─ token-authenticated JSON-RPC POST over HTTP
+          │
+          ▼
+McpServer
+  ├─ initialize / ping / tools / prompts / resources
+  ├─ Codex-inspired local ToolRegistry
+  │    ├─ Workspace path + realpath confinement
+  │    ├─ Reads, search, metadata and directory traversal
+  │    ├─ Atomic writes, exact edits and transactional apply_patch
+  │    ├─ Exec risk classification and approval routing
+  │    ├─ Git read tools
+  │    └─ In-memory plan state
+  ├─ FeedbackManager
+  │    ├─ Simplified Chinese Web UI
+  │    ├─ text and image feedback
+  │    ├─ validation commands
+  │    └─ high-risk approvals
+  └─ CodeGraphProxy
+       └─ codegraph serve --mcp over newline-delimited stdio
+```
+
+## No Codex dependency
+
+There is no Codex adapter, Codex child process, account state, API client, model call, thread, turn, or authentication code. The term “Codex-inspired” refers only to local coding-agent tool design and workflow conventions studied from the Apache-2.0 repository.
+
+## Transports
+
+### stdio
+
+Each JSON-RPC message is one UTF-8 JSON line. stdout is reserved for protocol messages; diagnostics use stderr.
+
+### HTTP
+
+The server exposes:
+
+```text
+POST /mcp/<random-token>
+GET  /health
+```
+
+The token may alternatively be supplied as a Bearer token. Incoming browser origins are checked against same-origin/loopback values plus the optional `CWMCP_ALLOWED_ORIGINS` allowlist, and unsupported MCP protocol-version headers are rejected. The HTTP implementation is stateless and returns JSON responses rather than SSE streams. This is deliberate because TryCloudflare Quick Tunnels do not support SSE.
+
+## Tool aggregation
+
+Local tools are defined by `ToolRegistry`. CodeGraph tools are requested dynamically with `tools/list`; name collisions are exposed as `codegraph__<name>`. Tool calls are forwarded unchanged through `tools/call`.
+
+If CodeGraph cannot start, local tools remain available. A later `tools/list` retries startup.
+
+## Workspace safety
+
+Every user path resolves against a configured real workspace root. Existing targets use `realpath`; new targets validate their nearest existing ancestor. Both lexical and real paths must remain inside the workspace.
+
+`apply_patch` parses all operations first, builds a virtual final file state, validates contexts and path transitions, then writes final files through temporary files. Original file snapshots are retained in memory for best-effort rollback.
+
+## Feedback state
+
+The WebUI starts once and shows all pending sessions. MCP feedback calls wait on an in-memory Promise for up to 172800 seconds. Browser polling retrieves pending sessions and submits text, image attachments, approval decisions, or validation-command requests.
+
+Attachments are stored outside the repository under the user's home directory.
+
+## Tunnel launcher
+
+The launcher starts one HTTP MCP process and two `cloudflared tunnel --url` processes, because Quick Tunnel assigns one random hostname to one local origin. It parses both `trycloudflare.com` URLs from process output and appends tokenized MCP/WebUI paths.
+
+An explicit empty temporary cloudflared config is used to avoid interference from a user-level named-tunnel configuration.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "codex-workspace-codegraph-mcp",
+  "version": "0.2.0",
+  "description": "Codex-inspired local workspace tools, Chinese interactive feedback, CodeGraph retrieval, and Cloudflare tunnel launcher for MCP.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "bin": {
+    "codex-workspace-codegraph-mcp": "bin/codex-workspace-mcp.js",
+    "codex-workspace-mcp": "bin/codex-workspace-mcp.js",
+    "codex-workspace-mcp-tunnel": "bin/start-tunnel.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "docs",
+    "AGENTS.md",
+    "README.md",
+    "README.en.md",
+    "SECURITY.md",
+    "THIRD_PARTY_NOTICES.md",
+    "VALIDATION.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/codex-workspace-mcp.js",
+    "start:http": "node bin/codex-workspace-mcp.js --transport http",
+    "tunnel": "node bin/start-tunnel.js",
+    "check": "find bin src test -name '*.js' -type f -exec node --check {} +",
+    "test": "node --test test/*.test.js",
+    "smoke": "node test/smoke.js",
+    "verify": "npm run check && npm test && npm run smoke && npm pack --dry-run"
+  },
+  "dependencies": {
+    "@colbymchenry/codegraph": "^1.4.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lllli223/codex-workspace-codegraph-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "codex",
+    "codegraph",
+    "interactive-feedback",
+    "cloudflared",
+    "coding-agent"
+  ]
+}

package/scripts/start.ps1

@@ -0,0 +1,2 @@
+$ErrorActionPreference = "Stop"
+node (Join-Path $PSScriptRoot "..\bin\start-tunnel.js") @args

package/scripts/start.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+set -eu
+exec node "$(dirname "$0")/../bin/start-tunnel.js" "$@"

package/src/codegraph.js

@@ -0,0 +1,236 @@
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileExists, randomToken } from './utils.js';
+import { runProcess } from './process.js';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+function localCodegraphBinary() {
+  return path.resolve(MODULE_DIR, '..', 'node_modules', '.bin', process.platform === 'win32' ? 'codegraph.cmd' : 'codegraph');
+}
+
+export class CodeGraphProxy {
+  constructor(config, workspace, feedback) {
+    this.config = config;
+    this.workspace = workspace;
+    this.feedback = feedback;
+    this.child = null;
+    this.buffer = '';
+    this.pending = new Map();
+    this.nextId = 1;
+    this.startPromise = null;
+    this.tools = [];
+    this.lastError = null;
+  }
+
+  async resolveCommand() {
+    const local = localCodegraphBinary();
+    if (await fileExists(local)) return local;
+    return this.config.codegraphCommand;
+  }
+
+  async start() {
+    if (!this.config.codegraphEnabled) return false;
+    if (this.child && !this.child.killed) return true;
+    if (this.startPromise) return this.startPromise;
+    this.startPromise = this.#startInternal().finally(() => { this.startPromise = null; });
+    return this.startPromise;
+  }
+
+  async #startInternal() {
+    const command = await this.resolveCommand();
+    this.lastError = null;
+    const child = spawn(command, this.config.codegraphArgs, {
+      cwd: this.workspace.root,
+      env: { ...process.env, CODEGRAPH_MCP_TOOLS: this.config.codegraphTools },
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child = child;
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => this.#onStdout(chunk));
+    child.stderr.on('data', (chunk) => {
+      if (!this.config.quiet) process.stderr.write(`[codegraph] ${chunk}`);
+    });
+    child.on('error', (error) => this.#failAll(error));
+    child.on('close', (code, signal) => {
+      const error = new Error(`CodeGraph 子进程退出: code=${code} signal=${signal}`);
+      this.#failAll(error);
+      this.child = null;
+    });
+
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error(`无法启动 CodeGraph 命令: ${command}`)), 5000);
+      child.once('spawn', () => { clearTimeout(timer); resolve(); });
+      child.once('error', (error) => { clearTimeout(timer); reject(error); });
+    });
+
+    const initialize = await this.request('initialize', {
+      protocolVersion: '2025-11-25',
+      capabilities: { roots: { listChanged: false } },
+      clientInfo: { name: 'codex-workspace-codegraph-mcp', version: '0.2.0' },
+    }, 20_000);
+    this.notify('notifications/initialized', {});
+    if (!initialize?.serverInfo && !this.config.quiet) console.error('[codegraph] 初始化响应未包含 serverInfo');
+    await this.refreshTools();
+    return true;
+  }
+
+  #onStdout(chunk) {
+    this.buffer += chunk;
+    while (true) {
+      const newline = this.buffer.indexOf('\n');
+      if (newline < 0) break;
+      const line = this.buffer.slice(0, newline).trim();
+      this.buffer = this.buffer.slice(newline + 1);
+      if (!line) continue;
+      let message;
+      try { message = JSON.parse(line); }
+      catch (error) {
+        this.lastError = `CodeGraph 输出无效 JSON: ${error.message}`;
+        continue;
+      }
+      this.#onMessage(message);
+    }
+  }
+
+  #onMessage(message) {
+    if (message.id !== undefined && (message.result !== undefined || message.error !== undefined)) {
+      const pending = this.pending.get(String(message.id));
+      if (!pending) return;
+      this.pending.delete(String(message.id));
+      clearTimeout(pending.timer);
+      if (message.error) pending.reject(new Error(message.error.message || JSON.stringify(message.error)));
+      else pending.resolve(message.result);
+      return;
+    }
+    if (message.id !== undefined && message.method) {
+      this.#handleChildRequest(message).catch((error) => {
+        this.#send({ jsonrpc: '2.0', id: message.id, error: { code: -32603, message: error.message } });
+      });
+    }
+  }
+
+  async #handleChildRequest(message) {
+    if (message.method === 'roots/list') {
+      return this.#send({
+        jsonrpc: '2.0', id: message.id,
+        result: { roots: [{ uri: pathToFileURL(this.workspace.root).href, name: path.basename(this.workspace.root) }] },
+      });
+    }
+    if (message.method === 'ping') return this.#send({ jsonrpc: '2.0', id: message.id, result: {} });
+    if (message.method === 'elicitation/create') {
+      const result = await this.feedback.requestFeedback({
+        summary: message.params?.message || 'CodeGraph 请求用户输入',
+        details: JSON.stringify(message.params || {}, null, 2),
+      });
+      return this.#send({ jsonrpc: '2.0', id: message.id, result: { action: 'accept', content: { feedback: result.feedback } } });
+    }
+    this.#send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `未支持的 CodeGraph 客户端请求: ${message.method}` } });
+  }
+
+  #send(message) {
+    if (!this.child?.stdin?.writable) throw new Error('CodeGraph 子进程不可写');
+    this.child.stdin.write(`${JSON.stringify(message)}\n`);
+  }
+
+  notify(method, params) {
+    this.#send({ jsonrpc: '2.0', method, params });
+  }
+
+  request(method, params = {}, timeoutMs = 30_000) {
+    return new Promise((resolve, reject) => {
+      const id = this.nextId++;
+      const timer = setTimeout(() => {
+        this.pending.delete(String(id));
+        reject(new Error(`CodeGraph RPC 超时: ${method}`));
+      }, timeoutMs);
+      timer.unref();
+      this.pending.set(String(id), { resolve, reject, timer });
+      try { this.#send({ jsonrpc: '2.0', id, method, params }); }
+      catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(String(id));
+        reject(error);
+      }
+    });
+  }
+
+  async refreshTools() {
+    try {
+      if (!this.child) await this.start();
+      const result = await this.request('tools/list', {}, 30_000);
+      this.tools = Array.isArray(result?.tools) ? result.tools : [];
+      return this.tools;
+    } catch (error) {
+      this.lastError = error.message;
+      this.tools = [];
+      return [];
+    }
+  }
+
+  async listTools() {
+    if (!this.config.codegraphEnabled) return [];
+    if (!this.child) await this.start().catch((error) => { this.lastError = error.message; });
+    if (!this.tools.length && this.child) await this.refreshTools();
+    return this.tools;
+  }
+
+  async callTool(name, args) {
+    if (!this.child) await this.start();
+    return this.request('tools/call', { name, arguments: args || {} }, 10 * 60 * 1000);
+  }
+
+  async runCli(args, options = {}) {
+    const command = await this.resolveCommand();
+    const cwd = options.cwd ? await this.workspace.resolve(options.cwd) : this.workspace.root;
+    const result = await runProcess(command, args, {
+      cwd,
+      env: { ...process.env, CODEGRAPH_MCP_TOOLS: this.config.codegraphTools },
+      timeoutMs: options.timeoutMs || 10 * 60 * 1000,
+      maxOutputBytes: this.config.maxOutputBytes,
+    });
+    return {
+      command: [command, ...args],
+      cwd: this.workspace.relative(cwd),
+      exit_code: result.code,
+      timed_out: result.timedOut,
+      truncated: result.truncated,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  }
+
+  status() {
+    return {
+      enabled: this.config.codegraphEnabled,
+      running: Boolean(this.child && !this.child.killed),
+      tools: this.tools.map((tool) => tool.name),
+      last_error: this.lastError,
+      command: this.config.codegraphCommand,
+      args: this.config.codegraphArgs,
+    };
+  }
+
+  #failAll(error) {
+    this.lastError = error.message;
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  async close() {
+    if (!this.child) return;
+    const child = this.child;
+    this.child = null;
+    child.kill('SIGTERM');
+    await new Promise((resolve) => {
+      const timer = setTimeout(resolve, 2000);
+      child.once('close', () => { clearTimeout(timer); resolve(); });
+    });
+  }
+}

package/src/config.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { asBoolean, clampInteger, parseArgs, randomToken } from './utils.js';
+
+export function loadConfig(argv = []) {
+  const args = parseArgs(argv);
+  const workspace = path.resolve(String(args.workspace || process.env.CWMCP_WORKSPACE || process.cwd()));
+  const transport = String(args.transport || process.env.CWMCP_TRANSPORT || 'stdio').toLowerCase();
+  if (!['stdio', 'http'].includes(transport)) {
+    throw new Error(`不支持的 transport: ${transport}`);
+  }
+
+  const accessToken = String(args.token || process.env.CWMCP_ACCESS_TOKEN || randomToken());
+  return {
+    workspace,
+    transport,
+    host: String(args.host || process.env.CWMCP_HOST || '127.0.0.1'),
+    mcpPort: clampInteger(args['mcp-port'] || process.env.CWMCP_MCP_PORT, 1, 65535, 8765),
+    webHost: String(args['web-host'] || process.env.CWMCP_WEB_HOST || '127.0.0.1'),
+    webPort: clampInteger(args['web-port'] || process.env.CWMCP_WEB_PORT, 1, 65535, 8766),
+    accessToken,
+    allowedOrigins: String(args['allowed-origins'] || process.env.CWMCP_ALLOWED_ORIGINS || '')
+      .split(',').map((value) => value.trim()).filter(Boolean),
+    quiet: asBoolean(args.quiet || process.env.CWMCP_QUIET, false),
+    openBrowser: !asBoolean(args['no-browser'] || process.env.CWMCP_NO_BROWSER, false),
+    sandboxMode: String(args.sandbox || process.env.CWMCP_SANDBOX || 'workspace-write'),
+    approvalPolicy: String(args['approval-policy'] || process.env.CWMCP_APPROVAL_POLICY || 'on-request'),
+    commandTimeoutMs: clampInteger(process.env.CWMCP_COMMAND_TIMEOUT_MS, 1000, 3_600_000, 120_000),
+    maxOutputBytes: clampInteger(process.env.CWMCP_MAX_OUTPUT_BYTES, 32_768, 8_388_608, 1_048_576),
+    maxReadBytes: clampInteger(process.env.CWMCP_MAX_READ_BYTES, 4096, 16_777_216, 2_097_152),
+    codegraphEnabled: !asBoolean(args['disable-codegraph'] || process.env.CWMCP_DISABLE_CODEGRAPH, false),
+    codegraphCommand: String(process.env.CWMCP_CODEGRAPH_COMMAND || 'codegraph'),
+    codegraphArgs: ['serve', '--mcp'],
+    codegraphTools: String(process.env.CODEGRAPH_MCP_TOOLS || 'explore,node,search,callers,callees,impact,files,status'),
+  };
+}

package/src/exec.js

@@ -0,0 +1,119 @@
+import path from 'node:path';
+import { runProcess } from './process.js';
+import { clampInteger, redactEnvironment } from './utils.js';
+
+const HIGH_RISK_PATTERNS = [
+  /(^|\s)rm\s+-[^\n]*r[^\n]*f/i,
+  /(^|\s)(sudo\s+)?(shutdown|reboot|halt|poweroff|mkfs|fdisk|parted)\b/i,
+  /(^|\s)dd\s+[^\n]*\bof=/i,
+  /git\s+(reset\s+--hard|clean\s+-|push\s+[^\n]*--force|checkout\s+--)/i,
+  /(^|\s)(npm|pnpm|yarn)\s+publish\b/i,
+  /(^|\s)(curl|wget)[^\n|]*\|\s*(sh|bash|zsh|pwsh|powershell)\b/i,
+  /(^|\s)(chmod|chown)\s+-R\b/i,
+  /(^|\s)(del|rmdir)\s+\/s\b/i,
+  /Remove-Item\b[^\n]*-Recurse[^\n]*-Force/i,
+];
+
+const READ_ONLY_COMMANDS = new Set(['rg', 'grep', 'find', 'ls', 'dir', 'cat', 'head', 'tail', 'pwd', 'which', 'where', 'git']);
+
+function displayCommand(command, shell) {
+  if (Array.isArray(command)) return command.map((value) => JSON.stringify(String(value))).join(' ');
+  return String(command || '');
+}
+
+function assessRisk(command, shell) {
+  const display = displayCommand(command, shell);
+  if (HIGH_RISK_PATTERNS.some((pattern) => pattern.test(display))) {
+    return { level: 'high', reason: '命令包含破坏性、系统级或不可逆操作模式' };
+  }
+  const executable = Array.isArray(command) ? path.basename(String(command[0] || '')).toLowerCase() : '';
+  if (executable === 'git') {
+    const subcommand = String(command[1] || '').toLowerCase();
+    if (['status', 'diff', 'log', 'show', 'rev-parse', 'branch'].includes(subcommand)) return { level: 'low', reason: '只读 Git 命令' };
+    return { level: 'medium', reason: 'Git 命令可能修改仓库状态' };
+  }
+  if (!shell && READ_ONLY_COMMANDS.has(executable)) return { level: 'low', reason: '常见只读命令' };
+  if (shell) return { level: 'medium', reason: '通过 shell 执行，可能包含组合副作用' };
+  return { level: 'medium', reason: '通用进程可能修改工作区或访问外部资源' };
+}
+
+export class ExecService {
+  constructor(config, workspace, feedback) {
+    this.config = config;
+    this.workspace = workspace;
+    this.feedback = feedback;
+  }
+
+  async execute(input = {}) {
+    const shell = input.shell === true || typeof input.command === 'string';
+    const command = input.command;
+    if (!(typeof command === 'string' && command.trim()) && !(Array.isArray(command) && command.length > 0)) {
+      throw new Error('command 必须是非空字符串或 argv 数组');
+    }
+    const cwd = await this.workspace.resolve(input.cwd || '.');
+    const risk = assessRisk(command, shell);
+
+    if (this.config.sandboxMode === 'read-only' && risk.level !== 'low') {
+      throw new Error('当前 sandbox=read-only，拒绝可能修改状态的命令');
+    }
+
+    const needsApproval = this.config.approvalPolicy === 'always'
+      || (this.config.approvalPolicy === 'on-request' && risk.level === 'high')
+      || (this.config.approvalPolicy === 'untrusted' && risk.level !== 'low');
+    if (needsApproval) {
+      const approval = await this.feedback.requestApproval({
+        summary: `是否批准执行命令：${displayCommand(command, shell)}`,
+        details: `风险级别：${risk.level}\n判断原因：${risk.reason}\n执行目录：${this.workspace.relative(cwd)}`,
+        cwd: this.workspace.relative(cwd),
+      });
+      if (approval.decision !== 'approve') throw new Error(`用户未批准命令执行：${approval.feedback || approval.status}`);
+    } else if (this.config.approvalPolicy === 'never' && risk.level === 'high') {
+      throw new Error(`approval-policy=never，拒绝高风险命令：${risk.reason}`);
+    }
+
+    const timeoutMs = clampInteger(input.timeout_ms, 1000, 3_600_000, this.config.commandTimeoutMs);
+    const environment = { ...process.env };
+    if (input.env && typeof input.env === 'object' && !Array.isArray(input.env)) {
+      for (const [key, value] of Object.entries(input.env)) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new Error(`环境变量名无效: ${key}`);
+        environment[key] = String(value);
+      }
+    }
+
+    let executable;
+    let args;
+    if (Array.isArray(command)) {
+      executable = String(command[0]);
+      args = command.slice(1).map(String);
+    } else if (process.platform === 'win32') {
+      executable = process.env.ComSpec || 'cmd.exe';
+      args = ['/d', '/s', '/c', command];
+    } else {
+      executable = process.env.SHELL || '/bin/sh';
+      args = ['-lc', command];
+    }
+
+    const startedAt = Date.now();
+    const result = await runProcess(executable, args, {
+      cwd,
+      env: environment,
+      timeoutMs,
+      maxOutputBytes: this.config.maxOutputBytes,
+      input: input.stdin === undefined ? undefined : String(input.stdin),
+    });
+    return {
+      command: displayCommand(command, shell),
+      argv: [executable, ...args],
+      cwd: this.workspace.relative(cwd),
+      risk,
+      exit_code: result.code,
+      signal: result.signal,
+      timed_out: result.timedOut,
+      truncated: result.truncated,
+      duration_ms: Date.now() - startedAt,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      environment_overrides: redactEnvironment(input.env || {}),
+    };
+  }
+}