codex-workspace-codegraph-mcp 0.2.0

package/src/plan.js

@@ -0,0 +1,29 @@
+export class PlanStore {
+  constructor() {
+    this.steps = [];
+    this.explanation = '';
+    this.updatedAt = null;
+  }
+
+  update(input = {}) {
+    if (!Array.isArray(input.steps) || input.steps.length === 0) throw new Error('steps 必须是非空数组');
+    const allowed = new Set(['pending', 'in_progress', 'completed']);
+    const steps = input.steps.map((step, index) => {
+      if (!step || typeof step.step !== 'string' || !step.step.trim()) throw new Error(`第 ${index + 1} 个步骤缺少 step`);
+      if (!allowed.has(step.status)) throw new Error(`第 ${index + 1} 个步骤状态无效`);
+      return { step: step.step.trim(), status: step.status };
+    });
+    const inProgress = steps.filter((step) => step.status === 'in_progress').length;
+    const allCompleted = steps.every((step) => step.status === 'completed');
+    if (!allCompleted && inProgress !== 1) throw new Error('计划未全部完成时必须且只能有一个 in_progress 步骤');
+    if (allCompleted && inProgress !== 0) throw new Error('全部完成时不能存在 in_progress 步骤');
+    this.steps = steps;
+    this.explanation = String(input.explanation || '');
+    this.updatedAt = new Date().toISOString();
+    return this.read();
+  }
+
+  read() {
+    return { steps: this.steps, explanation: this.explanation, updated_at: this.updatedAt };
+  }
+}

package/src/process.js

@@ -0,0 +1,65 @@
+import { spawn } from 'node:child_process';
+
+export function runProcess(command, args = [], options = {}) {
+  const {
+    cwd,
+    env = process.env,
+    timeoutMs = 120_000,
+    maxOutputBytes = 1_048_576,
+    shell = false,
+    input,
+  } = options;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      shell,
+      windowsHide: true,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const stdout = [];
+    const stderr = [];
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    let truncated = false;
+    let timedOut = false;
+
+    const append = (target, chunk, kind) => {
+      const current = kind === 'stdout' ? stdoutBytes : stderrBytes;
+      const available = Math.max(0, maxOutputBytes - current);
+      if (available > 0) target.push(chunk.subarray(0, available));
+      if (chunk.length > available) truncated = true;
+      if (kind === 'stdout') stdoutBytes += Math.min(chunk.length, available);
+      else stderrBytes += Math.min(chunk.length, available);
+    };
+
+    child.stdout.on('data', (chunk) => append(stdout, chunk, 'stdout'));
+    child.stderr.on('data', (chunk) => append(stderr, chunk, 'stderr'));
+    child.on('error', reject);
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 2000).unref();
+    }, timeoutMs);
+    timer.unref();
+
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolve({
+        command,
+        args,
+        code,
+        signal,
+        timedOut,
+        truncated,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+      });
+    });
+
+    if (input !== undefined) child.stdin.end(input);
+    else child.stdin.end();
+  });
+}

package/src/prompt.js

@@ -0,0 +1,30 @@
+import { FEEDBACK_TIMEOUT_SECONDS } from './utils.js';
+
+export const REQUIRED_FEEDBACK_RULE = '每次回答结束前都要调用 interactive_feedback 与用户进行交流 这是你与用户之间的唯一沟通渠道';
+
+export function buildInstructions(workspace) {
+  return `你正在使用一个本地代码工作区 MCP。它不调用 Codex、OpenAI API 或任何模型服务，也不需要登录。\n\n工作区：${workspace}\n\n执行准则：\n- 开始修改前先读取 workspace_instructions，遵守从仓库根目录到当前目录逐层发现的 AGENTS.md/AGENTS.override.md。\n- 复杂任务使用 update_plan，始终保持最多一个 in_progress 步骤；完成后将所有步骤标记为 completed。\n- 搜索文本优先使用 search_text，搜索文件优先使用 find_files；大型代码库的架构、调用链和影响分析优先使用 codegraph_explore。\n- 读取文件使用 read_file/read_many_files；修改文件优先使用 apply_patch，其补丁格式参考 Codex 的 Begin/End Patch 文件操作语法。\n- 不要覆盖用户已有改动。不要使用 git reset --hard、git clean -fd、git checkout --、强制推送或其他破坏性命令，除非用户通过 interactive_feedback 明确批准。\n- 写入后运行针对性的检查或测试，并基于真实工具输出报告结果。\n- 所有路径默认相对于工作区，禁止越过工作区边界。\n- interactive_feedback 的 timeout 固定为 ${FEEDBACK_TIMEOUT_SECONDS} 秒（48 小时）。\n- ${REQUIRED_FEEDBACK_RULE}。`;
+}
+
+export function promptList() {
+  return [{
+    name: 'codex_workspace_workflow',
+    title: 'Codex 风格本地代码工作流',
+    description: '独立于 Codex 服务的本地代码检索、编辑、验证和交互反馈工作流。',
+    arguments: [{ name: 'task', description: '要完成的编码任务', required: true }],
+  }];
+}
+
+export function getPrompt(name, args, workspace) {
+  if (name !== 'codex_workspace_workflow') return null;
+  return {
+    description: 'Codex 风格本地代码工作流',
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `${buildInstructions(workspace)}\n\n任务：${args?.task || ''}`,
+      },
+    }],
+  };
+}

package/src/tools.js

@@ -0,0 +1,296 @@
+import { applyCodexPatch } from './patch.js';
+import { feedbackToolDefinition } from './feedback.js';
+import { FEEDBACK_TIMEOUT_SECONDS, toolError, toolText } from './utils.js';
+
+const objectSchema = (properties, required = [], additionalProperties = false) => ({
+  type: 'object', properties, required, additionalProperties,
+});
+
+function localToolDefinitions() {
+  return [
+    {
+      name: 'workspace_info', title: '工作区信息',
+      description: '返回工作区根目录、沙箱模式、审批策略和服务状态。',
+      inputSchema: objectSchema({}), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'workspace_instructions', title: '读取项目指令',
+      description: '按照 Codex 风格，从工作区根目录到目标目录逐层加载 AGENTS.override.md 或 AGENTS.md。修改代码前应先调用。',
+      inputSchema: objectSchema({ cwd: { type: 'string', default: '.' } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'read_file', title: '读取文件',
+      description: '读取工作区内文本文件，可指定行范围并返回行号。',
+      inputSchema: objectSchema({
+        path: { type: 'string' }, start_line: { type: 'integer', minimum: 1, default: 1 },
+        end_line: { type: 'integer', minimum: 1 }, line_numbers: { type: 'boolean', default: true },
+        max_bytes: { type: 'integer', minimum: 1 },
+      }, ['path']), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'read_many_files', title: '批量读取文件',
+      description: '一次读取多个工作区文本文件。单次最多 20 个。',
+      inputSchema: objectSchema({ paths: { type: 'array', minItems: 1, maxItems: 20, items: { type: 'string' } }, max_bytes_per_file: { type: 'integer', minimum: 1 } }, ['paths']),
+      annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'list_directory', title: '列出目录',
+      description: '列出工作区目录的直接子项。',
+      inputSchema: objectSchema({ path: { type: 'string', default: '.' }, include_hidden: { type: 'boolean', default: false } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'file_metadata', title: '文件元数据',
+      description: '返回文件或目录的类型、大小、修改时间和权限。',
+      inputSchema: objectSchema({ path: { type: 'string' } }, ['path']), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'find_files', title: '查找文件',
+      description: '按路径片段和扩展名递归查找文件；自动跳过常见构建目录。',
+      inputSchema: objectSchema({
+        path: { type: 'string', default: '.' }, pattern: { type: 'string' },
+        extensions: { type: 'array', items: { type: 'string' } }, limit: { type: 'integer', minimum: 1, maximum: 5000, default: 500 },
+      }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'search_text', title: '搜索文本',
+      description: '在工作区搜索文本。优先使用 ripgrep，缺失时使用 Node 回退实现。',
+      inputSchema: objectSchema({
+        query: { type: 'string' }, path: { type: 'string', default: '.' }, regex: { type: 'boolean', default: false },
+        case_sensitive: { type: 'boolean', default: false }, glob: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
+        limit: { type: 'integer', minimum: 1, maximum: 2000, default: 200 },
+      }, ['query']), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'write_file', title: '写入文件',
+      description: '以原子替换方式创建或完整写入文本文件。已有文件默认允许覆盖；精确修改优先使用 edit_file 或 apply_patch。',
+      inputSchema: objectSchema({ path: { type: 'string' }, content: { type: 'string' }, create_only: { type: 'boolean', default: false }, overwrite: { type: 'boolean', default: true } }, ['path', 'content']),
+      annotations: { readOnlyHint: false, destructiveHint: true },
+    },
+    {
+      name: 'edit_file', title: '精确替换文件内容',
+      description: '仅在 old_text 出现次数与 expected_occurrences 完全一致时替换，避免误改。',
+      inputSchema: objectSchema({
+        path: { type: 'string' }, old_text: { type: 'string' }, new_text: { type: 'string' },
+        expected_occurrences: { type: 'integer', minimum: 1, default: 1 },
+      }, ['path', 'old_text', 'new_text']), annotations: { readOnlyHint: false, destructiveHint: true },
+    },
+    {
+      name: 'apply_patch', title: '应用 Codex 风格补丁',
+      description: '应用以 *** Begin Patch / *** End Patch 包裹的 Add、Delete、Update、Move 文件补丁。路径只能相对工作区；所有操作先验证，失败时尝试回滚。',
+      inputSchema: objectSchema({ patch: { type: 'string' } }, ['patch']), annotations: { readOnlyHint: false, destructiveHint: true },
+    },
+    {
+      name: 'create_directory', title: '创建目录',
+      description: '递归创建工作区目录。',
+      inputSchema: objectSchema({ path: { type: 'string' } }, ['path']), annotations: { readOnlyHint: false },
+    },
+    {
+      name: 'move_path', title: '移动或重命名',
+      description: '在工作区内移动或重命名文件/目录。覆盖目标时需要用户在 interactive_feedback 中批准。',
+      inputSchema: objectSchema({ from: { type: 'string' }, to: { type: 'string' }, overwrite: { type: 'boolean', default: false } }, ['from', 'to']),
+      annotations: { readOnlyHint: false, destructiveHint: true },
+    },
+    {
+      name: 'delete_path', title: '删除路径',
+      description: '删除工作区内文件或目录。始终通过 interactive_feedback 请求批准。禁止删除工作区根目录。',
+      inputSchema: objectSchema({ path: { type: 'string' }, recursive: { type: 'boolean', default: false } }, ['path']),
+      annotations: { readOnlyHint: false, destructiveHint: true },
+    },
+    {
+      name: 'exec_command', title: '执行命令',
+      description: '在工作区执行前台命令。优先传 argv 数组；字符串命令通过系统 shell 执行。高风险命令通过 interactive_feedback 审批。',
+      inputSchema: objectSchema({
+        command: { oneOf: [{ type: 'string' }, { type: 'array', minItems: 1, items: { type: 'string' } }] },
+        cwd: { type: 'string', default: '.' }, shell: { type: 'boolean', default: false }, stdin: { type: 'string' },
+        timeout_ms: { type: 'integer', minimum: 1000, maximum: 3600000 },
+        env: { type: 'object', additionalProperties: { type: ['string', 'number', 'boolean'] } },
+      }, ['command']), annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    {
+      name: 'git_status', title: 'Git 状态', description: '返回 git status --short --branch。',
+      inputSchema: objectSchema({ cwd: { type: 'string', default: '.' } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'git_diff', title: 'Git 差异', description: '返回工作树或暂存区差异，可限制路径。',
+      inputSchema: objectSchema({ cwd: { type: 'string', default: '.' }, staged: { type: 'boolean', default: false }, path: { type: 'string' }, stat: { type: 'boolean', default: false } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'git_log', title: 'Git 日志', description: '返回最近提交日志。',
+      inputSchema: objectSchema({ cwd: { type: 'string', default: '.' }, limit: { type: 'integer', minimum: 1, maximum: 100, default: 20 }, path: { type: 'string' } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'git_show', title: '查看 Git 对象', description: '查看指定提交或对象，可限制文件路径。',
+      inputSchema: objectSchema({ revision: { type: 'string', default: 'HEAD' }, cwd: { type: 'string', default: '.' }, path: { type: 'string' } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'update_plan', title: '更新执行计划',
+      description: '维护 Codex 风格任务计划。未全部完成时必须且只能有一个 in_progress；完成后所有步骤为 completed。',
+      inputSchema: objectSchema({
+        explanation: { type: 'string' },
+        steps: { type: 'array', minItems: 1, maxItems: 20, items: objectSchema({ step: { type: 'string' }, status: { enum: ['pending', 'in_progress', 'completed'] } }, ['step', 'status']) },
+      }, ['steps']), annotations: { readOnlyHint: false, idempotentHint: true },
+    },
+    {
+      name: 'get_plan', title: '读取执行计划', description: '返回当前内存中的执行计划。',
+      inputSchema: objectSchema({}), annotations: { readOnlyHint: true },
+    },
+    feedbackToolDefinition(),
+    {
+      name: 'codegraph_project_init', title: '初始化 CodeGraph',
+      description: '在工作区或其子目录执行 codegraph init .，建立本地代码知识图谱索引。',
+      inputSchema: objectSchema({ path: { type: 'string', default: '.' } }), annotations: { readOnlyHint: false },
+    },
+    {
+      name: 'codegraph_project_sync', title: '同步 CodeGraph',
+      description: '在指定目录执行 codegraph sync，同步已有索引。',
+      inputSchema: objectSchema({ path: { type: 'string', default: '.' } }), annotations: { readOnlyHint: false },
+    },
+    {
+      name: 'codegraph_project_status', title: 'CodeGraph 状态',
+      description: '执行 codegraph status，并返回 MCP 子进程状态。',
+      inputSchema: objectSchema({ path: { type: 'string', default: '.' } }), annotations: { readOnlyHint: true },
+    },
+    {
+      name: 'integration_status', title: '集成状态', description: '返回本地工作区、反馈 Web UI 和 CodeGraph 集成状态。',
+      inputSchema: objectSchema({}), annotations: { readOnlyHint: true },
+    },
+  ];
+}
+
+export class ToolRegistry {
+  constructor({ config, workspace, feedback, execService, planStore, codegraph }) {
+    this.config = config;
+    this.workspace = workspace;
+    this.feedback = feedback;
+    this.execService = execService;
+    this.planStore = planStore;
+    this.codegraph = codegraph;
+    this.localTools = localToolDefinitions();
+    this.codegraphToolNames = new Map();
+  }
+
+  async listTools() {
+    const tools = [...this.localTools];
+    const existing = new Set(tools.map((tool) => tool.name));
+    const remoteTools = await this.codegraph.listTools().catch(() => []);
+    this.codegraphToolNames.clear();
+    for (const tool of remoteTools) {
+      const exposedName = existing.has(tool.name) ? `codegraph__${tool.name}` : tool.name;
+      existing.add(exposedName);
+      this.codegraphToolNames.set(exposedName, tool.name);
+      tools.push({ ...tool, name: exposedName, title: tool.title || `CodeGraph: ${tool.name}` });
+    }
+    return tools;
+  }
+
+  #ensureWritable() {
+    if (this.config.sandboxMode === 'read-only') throw new Error('当前 sandbox=read-only，拒绝文件修改');
+  }
+
+  async #approve(summary, details, cwd = '.') {
+    if (this.config.approvalPolicy === 'never') throw new Error('approval-policy=never，拒绝需要批准的操作');
+    const result = await this.feedback.requestApproval({ summary, details, cwd });
+    if (result.decision !== 'approve') throw new Error(`用户未批准：${result.feedback || result.status}`);
+  }
+
+  async call(name, args = {}) {
+    try {
+      if (this.codegraphToolNames.has(name)) return await this.codegraph.callTool(this.codegraphToolNames.get(name), args);
+      switch (name) {
+        case 'workspace_info':
+          return toolText({
+            workspace: this.workspace.root,
+            sandbox: this.config.sandboxMode,
+            approval_policy: this.config.approvalPolicy,
+            feedback_url_local: this.feedback.localUrl,
+            feedback_timeout_seconds: FEEDBACK_TIMEOUT_SECONDS,
+            codex_dependency: false,
+            openai_api_dependency: false,
+            codegraph: this.codegraph.status(),
+          });
+        case 'workspace_instructions': return toolText(await this.workspace.discoverInstructions(args.cwd));
+        case 'read_file': return toolText(await this.workspace.readFile(args.path, { startLine: args.start_line, endLine: args.end_line, lineNumbers: args.line_numbers, maxBytes: args.max_bytes }));
+        case 'read_many_files': {
+          const files = [];
+          for (const filePath of args.paths || []) {
+            try { files.push(await this.workspace.readFile(filePath, { maxBytes: args.max_bytes_per_file })); }
+            catch (error) { files.push({ path: filePath, error: error.message }); }
+          }
+          return toolText({ files });
+        }
+        case 'list_directory': return toolText({ path: args.path || '.', entries: await this.workspace.listDirectory(args.path, { includeHidden: args.include_hidden }) });
+        case 'file_metadata': return toolText(await this.workspace.metadata(args.path));
+        case 'find_files': return toolText(await this.workspace.findFiles({ path: args.path, pattern: args.pattern, extensions: args.extensions, limit: args.limit }));
+        case 'search_text': return toolText(await this.workspace.searchText({ query: args.query, path: args.path, regex: args.regex, caseSensitive: args.case_sensitive, glob: args.glob, limit: args.limit }));
+        case 'write_file':
+          this.#ensureWritable();
+          return toolText(await this.workspace.writeFile(args.path, args.content, { createOnly: args.create_only, overwrite: args.overwrite !== false }));
+        case 'edit_file':
+          this.#ensureWritable();
+          return toolText(await this.workspace.editFile(args.path, args.old_text, args.new_text, args.expected_occurrences || 1));
+        case 'apply_patch':
+          this.#ensureWritable();
+          return toolText(await applyCodexPatch(this.workspace, args.patch));
+        case 'create_directory':
+          this.#ensureWritable();
+          return toolText(await this.workspace.createDirectory(args.path));
+        case 'move_path':
+          this.#ensureWritable();
+          if (args.overwrite) await this.#approve(`批准覆盖移动目标：${args.to}`, `来源：${args.from}\n目标：${args.to}`);
+          return toolText(await this.workspace.movePath(args.from, args.to, args.overwrite === true));
+        case 'delete_path':
+          this.#ensureWritable();
+          await this.#approve(`批准删除：${args.path}`, `recursive=${args.recursive === true}\n该操作可能不可逆。`);
+          return toolText(await this.workspace.deletePath(args.path, args.recursive === true));
+        case 'exec_command': return toolText(await this.execService.execute(args));
+        case 'git_status': return toolText(await this.execService.execute({ command: ['git', 'status', '--short', '--branch'], cwd: args.cwd }));
+        case 'git_diff': {
+          const command = ['git', 'diff'];
+          if (args.staged) command.push('--staged');
+          if (args.stat) command.push('--stat');
+          if (args.path) command.push('--', args.path);
+          return toolText(await this.execService.execute({ command, cwd: args.cwd }));
+        }
+        case 'git_log': {
+          const command = ['git', 'log', `-${Math.max(1, Math.min(100, Number(args.limit || 20)))}`, '--date=iso-strict', '--pretty=format:%h%x09%ad%x09%an%x09%s'];
+          if (args.path) command.push('--', args.path);
+          return toolText(await this.execService.execute({ command, cwd: args.cwd }));
+        }
+        case 'git_show': {
+          const command = ['git', 'show', '--stat', '--oneline', String(args.revision || 'HEAD')];
+          if (args.path) command.push('--', args.path);
+          return toolText(await this.execService.execute({ command, cwd: args.cwd }));
+        }
+        case 'update_plan': return toolText(this.planStore.update(args));
+        case 'get_plan': return toolText(this.planStore.read());
+        case 'interactive_feedback':
+          if (Number(args.timeout) !== FEEDBACK_TIMEOUT_SECONDS) throw new Error(`timeout 必须固定为 ${FEEDBACK_TIMEOUT_SECONDS}`);
+          return toolText(await this.feedback.requestFeedback(args));
+        case 'codegraph_project_init': {
+          this.#ensureWritable();
+          return toolText(await this.codegraph.runCli(['init', '.'], { cwd: args.path || '.', timeoutMs: 30 * 60 * 1000 }));
+        }
+        case 'codegraph_project_sync': {
+          this.#ensureWritable();
+          return toolText(await this.codegraph.runCli(['sync'], { cwd: args.path || '.', timeoutMs: 30 * 60 * 1000 }));
+        }
+        case 'codegraph_project_status': {
+          const cli = await this.codegraph.runCli(['status'], { cwd: args.path || '.', timeoutMs: 120_000 });
+          return toolText({ cli, mcp: this.codegraph.status() });
+        }
+        case 'integration_status': return toolText({
+          workspace: this.workspace.root,
+          transport: this.config.transport,
+          mcp_local_url: this.config.transport === 'http' ? `http://${this.config.host}:${this.config.mcpPort}/mcp/${this.config.accessToken}` : null,
+          feedback_local_url: this.feedback.localUrl,
+          feedback_timeout_seconds: FEEDBACK_TIMEOUT_SECONDS,
+          codex_or_openai_required: false,
+          codegraph: this.codegraph.status(),
+        });
+        default: throw new Error(`未知工具: ${name}`);
+      }
+    } catch (error) {
+      return toolError(error.message);
+    }
+  }
+}

package/src/transports.js

@@ -0,0 +1,177 @@
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { readJsonBody, writeJson } from './utils.js';
+
+const SUPPORTED_PROTOCOLS = new Set(['2025-11-25', '2025-06-18', '2025-03-26']);
+
+function authorized(request, url, token) {
+  const pathToken = url.pathname.startsWith('/mcp/') ? decodeURIComponent(url.pathname.slice('/mcp/'.length)) : '';
+  const queryToken = url.searchParams.get('token') || '';
+  const bearer = String(request.headers.authorization || '').replace(/^Bearer\s+/i, '');
+  const supplied = pathToken || queryToken || bearer;
+  const left = Buffer.from(supplied);
+  const right = Buffer.from(token);
+  return left.length === right.length && crypto.timingSafeEqual(left, right);
+}
+
+function requestOriginAllowed(request, config) {
+  const rawOrigin = request.headers.origin;
+  if (!rawOrigin) return { allowed: true, origin: null };
+  let origin;
+  try {
+    origin = new URL(String(rawOrigin)).origin;
+  } catch {
+    return { allowed: false, origin: String(rawOrigin) };
+  }
+
+  if (config.allowedOrigins.includes('*') || config.allowedOrigins.includes(origin)) {
+    return { allowed: true, origin };
+  }
+
+  const forwardedProto = String(request.headers['x-forwarded-proto'] || '').split(',')[0].trim();
+  const socketProto = request.socket.encrypted ? 'https' : 'http';
+  const proto = forwardedProto || socketProto;
+  const host = String(request.headers['x-forwarded-host'] || request.headers.host || '').split(',')[0].trim();
+  const sameOrigin = host ? `${proto}://${host}` : '';
+  const localOrigins = new Set([
+    sameOrigin,
+    `http://127.0.0.1:${config.mcpPort}`,
+    `http://localhost:${config.mcpPort}`,
+  ]);
+  return { allowed: localOrigins.has(origin), origin };
+}
+
+function corsHeaders(originResult) {
+  return {
+    ...(originResult.origin && originResult.allowed
+      ? { 'access-control-allow-origin': originResult.origin, vary: 'Origin' }
+      : {}),
+    'access-control-allow-methods': 'POST, GET, DELETE, OPTIONS',
+    'access-control-allow-headers': 'content-type, authorization, mcp-protocol-version, mcp-session-id',
+    'access-control-expose-headers': 'mcp-protocol-version',
+    'mcp-protocol-version': '2025-11-25',
+  };
+}
+
+function acceptsJson(request) {
+  const accept = String(request.headers.accept || '').toLowerCase();
+  return !accept || accept.includes('*/*') || accept.includes('application/json');
+}
+
+function contentTypeIsJson(request) {
+  const contentType = String(request.headers['content-type'] || '').toLowerCase();
+  return contentType.startsWith('application/json');
+}
+
+export async function runStdioTransport(server, onClose) {
+  process.stdin.setEncoding('utf8');
+  let buffer = '';
+  let chain = Promise.resolve();
+  process.stdin.on('data', (chunk) => {
+    buffer += chunk;
+    while (true) {
+      const newline = buffer.indexOf('\n');
+      if (newline < 0) break;
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      if (!line) continue;
+      chain = chain.then(async () => {
+        let request;
+        try { request = JSON.parse(line); }
+        catch {
+          process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } })}\n`);
+          return;
+        }
+        const response = await server.handle(request);
+        if (response !== null) process.stdout.write(`${JSON.stringify(response)}\n`);
+      }).catch((error) => {
+        process.stderr.write(`[stdio] ${error.stack || error}\n`);
+      });
+    }
+  });
+  process.stdin.on('end', async () => { await chain; await onClose(); });
+  process.stdin.resume();
+}
+
+export async function runHttpTransport(server, config, onClose) {
+  const httpServer = http.createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url, `http://${request.headers.host || 'localhost'}`);
+      const originResult = requestOriginAllowed(request, config);
+      const commonHeaders = corsHeaders(originResult);
+
+      if (!originResult.allowed) {
+        writeJson(response, 403, {
+          jsonrpc: '2.0',
+          id: null,
+          error: { code: -32000, message: 'Origin 不被允许。请使用同源请求或配置 CWMCP_ALLOWED_ORIGINS。' },
+        }, commonHeaders);
+        return;
+      }
+      if (request.method === 'OPTIONS') {
+        response.writeHead(204, commonHeaders); response.end(); return;
+      }
+      if (request.method === 'GET' && url.pathname === '/health') {
+        writeJson(response, 200, { ok: true, server: 'codex-workspace-codegraph-mcp', version: '0.2.0' }, commonHeaders); return;
+      }
+      if (!url.pathname.startsWith('/mcp')) {
+        writeJson(response, 404, { error: 'Not found' }, commonHeaders); return;
+      }
+      if (!authorized(request, url, config.accessToken)) {
+        writeJson(response, 401, { error: 'Unauthorized' }, commonHeaders); return;
+      }
+      if (request.method === 'GET') {
+        response.writeHead(405, { ...commonHeaders, allow: 'POST, DELETE' });
+        response.end('Quick Tunnel 模式不使用 SSE；请通过 POST 发送 JSON-RPC。');
+        return;
+      }
+      if (request.method === 'DELETE') {
+        response.writeHead(204, commonHeaders); response.end(); return;
+      }
+      if (request.method !== 'POST') {
+        writeJson(response, 405, { error: 'Method not allowed' }, commonHeaders); return;
+      }
+
+      const protocolVersion = String(request.headers['mcp-protocol-version'] || '');
+      if (protocolVersion && !SUPPORTED_PROTOCOLS.has(protocolVersion)) {
+        writeJson(response, 400, {
+          jsonrpc: '2.0', id: null,
+          error: { code: -32600, message: `不支持的 MCP-Protocol-Version: ${protocolVersion}` },
+        }, commonHeaders);
+        return;
+      }
+      if (!acceptsJson(request)) {
+        writeJson(response, 406, { error: 'Accept 必须允许 application/json' }, commonHeaders); return;
+      }
+      if (!contentTypeIsJson(request)) {
+        writeJson(response, 415, { error: 'Content-Type 必须是 application/json' }, commonHeaders); return;
+      }
+
+      const body = await readJsonBody(request);
+      if (Array.isArray(body)) {
+        writeJson(response, 400, {
+          jsonrpc: '2.0', id: null,
+          error: { code: -32600, message: '当前 Streamable HTTP MCP 不接受 JSON-RPC batch' },
+        }, commonHeaders);
+        return;
+      }
+      const result = await server.handle(body);
+      if (result === null) {
+        response.writeHead(202, commonHeaders); response.end(); return;
+      }
+      writeJson(response, 200, result, commonHeaders);
+    } catch (error) {
+      writeJson(response, error.statusCode || 500, { error: error.message });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(config.mcpPort, config.host, resolve);
+  });
+  const close = async () => {
+    await new Promise((resolve) => httpServer.close(resolve));
+    await onClose();
+  };
+  return { httpServer, close };
+}