Local Coder + CodeGraph + Serena + Interactive Feedback MCP

一个完全本地、无模型后端的编码工具 MCP。模型由 MCP 客户端提供；本项目不调用 OpenAI/Codex API，也不需要账号、API Key 或订阅。

1.0.0 将工具面从 36 个收敛为约 14 个高价值工具：通用命令统一进入 exec_command，普通文件修改统一进入 apply_patch，代码理解由进程内 CodeGraph 与受管 Serena 分工，所有任务仍强制通过中文 interactive_feedback 收尾。

非 OpenAI 官方项目。“Codex-inspired”仅表示参考其公开的工具分层和工作流设计。

架构

MCP client model
    |
    | stdio or Streamable HTTP JSON
    v
LocalCoderCore
    |-- safe workspace layer
    |-- exec_command / write_stdin
    |-- transactional apply_patch
    |-- embedded @colbymchenry/codegraph 1.4.1
    |-- managed Serena 1.5.3 MCP child (uv, context=codex)
    `-- mcp-feedback-enhanced 2.6.0 WebSocket UI

CodeGraph

CodeGraph 是固定 npm 依赖，直接通过进程内 SDK 使用：

• 自动 init/open 当前项目；
• 启动时严格建立或打开索引；
• 文件修改后自动 sync；
• 只向模型提供一个高层工具 codegraph_explore；
• 不再依赖 PATH 中的 codegraph.cmd，也不再启动第二层 CodeGraph MCP。

Serena

Serena 由本项目使用固定版本 serena-agent==1.5.3 管理：

uv run --isolated --python 3.13 --with serena-agent==1.5.3 \
  serena start-mcp-server \
  --project <workspace> \
  --context codex \
  --transport stdio \
  --enable-web-dashboard false \
  --open-web-dashboard false

codex context 会排除 Serena 自带的普通文件、目录与 shell 工具。本项目只代理：

• 符号概览、搜索、引用、实现、声明和诊断；
• 符号重命名、符号体替换、前后插入和安全删除；
• 项目 Markdown 记忆。

Serena 首次启动需要联网下载到 uv 缓存。缓存完成后可复用。

严格依赖策略

CodeGraph 或 Serena 初始化失败时，MCP 初始化失败并返回结构化诊断，不静默退回低质量检索路径。

可通过以下变量使用预安装或测试运行时：

LCM_SERENA_COMMAND
LCM_SERENA_ARGS_JSON
LCM_SERENA_PACKAGE_SPEC
LCM_SERENA_HOME

默认工具

单项目工作区默认提供 14 个工具：

workspace_info
read_file
workspace_search
update_plan
apply_patch
exec_command
write_stdin
codegraph_explore
code_symbol
semantic_edit
project_memory
view_image
interactive_feedback
request_user_input

存在多个授权项目根时额外提供：

set_workspace_root

工具分工

| 工具 | 职责 | |---|---| | exec_command | Git、构建、测试、包管理器、ls、rg 等通用命令 | | write_stdin | 命令会话轮询、输入、关闭 stdin、终止进程 | | apply_patch | 普通文件 Add/Update/Move/Delete、dry-run、diff、哈希并发保护和原子回滚 | | read_file | 一个或多个工作区文件片段，带行号、SHA-256 和路径安全检查 | | workspace_search | 目录、glob 文件名和文本/正则搜索 | | codegraph_explore | 架构、调用链、影响范围和跨文件上下文 | | code_symbol | Serena 精确符号、引用、实现、声明和诊断 | | semantic_edit | Serena 语义重构；强制审批、内部快照、最终 diff 和失败恢复 | | project_memory | Serena 项目 Markdown 记忆 | | interactive_feedback | 强制任务收尾、阶段反馈和审批 UI |

Git 不单独拆分为多组工具，统一使用：

{
  "name": "exec_command",
  "arguments": {
    "cmd": ["git", "status", "--short", "--branch"],
    "workdir": ".",
    "read_only": true
  }
}

文件和命令安全

普通文件工具：

• 只接受工作区相对路径；
• 拒绝 .. 越界；
• 解析真实路径并阻止符号链接逃逸；
• 原子写入；
• apply_patch 支持审批后重新校验和多文件失败回滚。

命令工具仍使用运行账户的系统权限，因此公网部署必须使用低权限账户、容器或虚拟机。默认 smart 策略会自动允许普通开发命令，并要求高风险命令、删除和恢复操作通过反馈 UI 审批。

Interactive Feedback

interactive_feedback 必须在每次回答结束前调用，固定超时 172800 秒（48 小时）。基础页面、图片、会话和 WebSocket 能力来自 mcp-feedback-enhanced 2.6.0；Node 网关在其页面上增加一层本地交互扩展：

• 最新请求优先：新请求立即使旧请求失效，旧请求不能再提交；
• 草稿持久化：WebSocket 重连、页面重建或新请求到来时不清空未提交文字；
• 审批按钮：直接点击“批准”或“拒绝”；
• 结构化问题按钮：直接点击选项，可在反馈框补充说明；
• 状态通过 SSE 推送，不使用轮询刷新表单。

提示词要求模型只发送包含具体结果、完整建议、必要问题或审批对象的有效反馈。不得用 feedback 发送“好的，我将开始”“接下来我会处理”等确认、预告或过渡语。超时后由模型使用完全相同内容重试，总计最多 5 次；网关本身不强制重试次数，也不做内容语义门禁。

{
  "summary": "阶段结果、问题或完成说明",
  "timeout": 172800
}

运行要求

• Node.js 22.5 或更高版本；
• npm/npx；
• uv，用于固定版本 Serena 和反馈运行时；
• Git，建议所有项目都使用 Git 管理；
• 各项目语言对应的 Serena/LSP 运行要求。

安装并启动：

npm install
npm run start:tunnel -- --workspace .

发布后：

npx -y [email protected] --workspace .

stdio 配置

{
  "mcpServers": {
    "local-coder": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "--workspace",
        "/absolute/path/to/project"
      ],
      "env": {
        "LCM_APPROVAL_POLICY": "smart"
      }
    }
  }
}

HTTP 与 Tunnel

HTTP MCP 默认监听 127.0.0.1，要求随机 token 并验证 Origin。Tunnel 启动器可提供 Quick Tunnel，也支持一条 named Tunnel 发布 MCP 和 WebUI 两个 hostname。

Quick Tunnel 仅适合临时测试。长期部署应使用命名 Tunnel、Cloudflare Access、独立应用 token 和低权限运行环境。

关键环境变量

| 变量 | 默认值 | 说明 | |---|---:|---| | LCM_WORKSPACE | 当前目录 | 初始工作区 | | LCM_WORKSPACE_SCOPE_ROOT | 未设置 | 可切换项目的共同父目录 | | LCM_WORKSPACE_ALLOWED_ROOTS | 未设置 | 额外授权根目录 | | LCM_APPROVAL_POLICY | smart | smart/never/commands/mutations/always | | LCM_SERENA_PACKAGE_SPEC | serena-agent==1.5.3 | Serena 固定包规格 | | LCM_SERENA_COMMAND | 自动查找 uv | 自定义 Serena 启动命令 | | LCM_SERENA_ARGS_JSON | 自动生成 | 自定义 Serena 参数数组 | | LCM_SERENA_HOME | 用户缓存目录 | Serena 全局数据和缓存根 | | LCM_SERENA_TOOL_TIMEOUT_SECONDS | 172800 | Serena 工具超时 | | LCM_SERENA_START_TIMEOUT_MS | 900000 | 首次安装和 MCP 握手的最大等待时间；超时后严格启动失败 | | LCM_SEMANTIC_SNAPSHOT_MAX_FILES | 10000 | 语义编辑内部快照文件上限 | | LCM_SEMANTIC_SNAPSHOT_MAX_BYTES | 268435456 | 语义编辑内部快照字节上限 | | LCM_MCP_PORT | 8787 | HTTP MCP 端口 | | LCM_WEB_PORT | 8788 | Feedback 网关端口 |

开发验证

npm run verify
npm run validate:feedback

测试使用可注入的严格 CodeGraph/Serena 后端；smoke 测试使用真实进程内 CodeGraph 和固定的本地 Serena MCP fixture。

Git 基线

1.0.0 重构前基线提交：

3c2ea4b chore: baseline before tool architecture refactor

许可证

本项目使用 MIT License。CodeGraph、Serena 和 mcp-feedback-enhanced 保留各自许可证及版权；详见 THIRD_PARTY_NOTICES.md。