codex-java-lsp-mcp

codex-java-lsp-mcp 是一个用户级、Java-only 的 Codex MCP server。它给 Codex 提供低 token 的 Java 语义导航能力：先用源码索引和内部 rg 收敛影响面，再按需启动有界 JDT LS 做语义增强。

它不是完整 IDE，也不是通用多项目平台。项目边界以 canonical repoRoot 和 repoHash 为准，projectId 只作为 alias/display name。

目录

• 核心能力

• 设计边界

• 环境要求

• 快速开始

• 项目启用

• Codex Hook

• Public MCP Tools

• 配置

• 开发与验证

• 故障排查

• 安全说明

• 贡献规范

• 许可证

Related MCP server: java-jdtls-mcp-server

核心能力

• 注册一个 Codex MCP server：codex-java-lsp。

• 提供 7 个 public tools：java_status、java_impact、java_symbol、java_references、java_diagnostics、java_restart、java_shutdown。

• 默认推荐入口是 java_impact，用于生成影响面、候选文件、readPlan、证据缺口和指标。

• benchmark harness 固化 15 个真实 golden 场景，并输出 per-golden attribution、warm prepare/router/session phase timing 和 runtime build metadata。

• 未启用 LSP 的 Java repo 仍可走 fast path：repo/root/layout/JDK/generated-code 探测、SourceIndex、内部 rg 摘要。

• 启用 LSP 后，JDT LS 可为 symbol、references、diagnostics 和 documentSymbol warm-index 提供增强结果。

• 支持 Git worktree family 继承 LSP enablement，但每个 worktree 仍独立使用自己的 repoRoot、repoHash、workspace、日志和 SourceIndex。

• stdio 与后续 HTTP daemon 共用 canonical-root ownership；同一个 worktree 同一时刻只允许一个进程持有 JDT workspace、SourceIndex 和 cache。

设计边界

• public MCP surface 保持 7 个工具；除非有明确需求，不扩展工具面。

• 所有工具都不修改目标 Java repo；java_restart 和 java_shutdown 只影响本 MCP 管理的 JDT LS 进程。

• MCP stdio 对端实际结束或关闭时，服务会释放全部 runtime 并退出；保持打开的空闲 stdio 连接不会让服务自行退出。

• JDT LS 启动必须显式启用：lspEnabled=true，或命中同一 Git common-dir 的 worktree family 继承。

• SourceIndex 是冷启动事实来源；JDT LS 是可选增强，不是路由正确性的唯一来源。

• JDT LS runtime JDK 与项目 JDK 分开处理，避免把语言服务器运行环境误当成项目编译环境。

• resource 默认值按本机内存保守计算；多 repo 并行时优先保住可用性，而不是抢占更多 JDT LS。

• warm-required 仍是 precision/recall 可选增强，不是默认路径；profile-aware/default warm 需要先解决首触 textDocument/references P95。

环境要求

• macOS。目前 run.sh 和检查脚本会在非 macOS 平台直接退出。

• Node.js >=22 和 npm。

• Codex CLI，且可执行 codex mcp。

• Java runtime。

• Eclipse JDT Language Server，可用 Homebrew 安装：

brew install jdtls

快速开始

npm ci
npm run build
npm test
./install-runtime.sh
./check-codex-mcp.sh --fast

默认 runtime 目录：

~/Library/Application Support/codex-java-lsp-mcp

默认项目配置：

~/.config/codex-java-lsp/projects.json

install-runtime.sh 会构建新的 immutable release、在固定 loopback 端口启动 LaunchAgent 管理的 HTTP daemon，并保留至少一个前序 release。默认不改当前 Codex MCP 注册，因此已启用的 stdio MCP 和已有 task 不会被安装步骤切换。

npm test 同样会自动创建并清理独立的 cache、ownership、projects、XDG 配置、CODEX_HOME 和 HOME；即使从携带运行态环境变量的 shell 调用，也不会读写当前 MCP/daemon 的运行目录或 Codex 配置。

受管 HTTP daemon 与显式切换

安装过程先在独立 canary 端口运行 tools/list / java_status smoke，再原子更新 current symlink，最后通过 launchd 在固定端口启动。candidate 与 release 内的 npm test 分别使用 installer 创建的临时 cache、ownership、projects、XDG 配置、CODEX_HOME 和 HOME；两者都不会读取或写入受管 daemon 的状态目录。它不会 rsync --delete 覆盖运行中的 release。

./install-runtime.sh

"$HOME/Library/Application Support/codex-java-lsp-mcp/daemonctl.sh" status
"$HOME/Library/Application Support/codex-java-lsp-mcp/daemonctl.sh" smoke

只有完成隔离 canary、真实 Codex CLI/Desktop task、crash recovery 和 worktree 并发验证后，才显式切换同名 MCP 到 HTTP URL。生产切换会校验一个不超过七天、且绑定本次 build SHA 与 daemon instance ID 的 release-gate 凭据：

./install-runtime.sh --activate-http /absolute/path/to/http-activation-attestation.json

凭据必须记录真实 CLI 和 Desktop 的 taskId、七个工具可用、正常 restart 与 kill -9 recovery 后仍可调用、Desktop 跨过 idle 窗口后仍可调用、旧 stdio owner 已清退、以及 linked-worktree 隔离已确认；任何一项缺失，installer 保留已有 MCP registration。通过门禁后命令会先保存旧 stdio registration 的精确 rollback command；daemon health、build SHA、HTTP smoke 任一失败时不切换或恢复旧 registration。切换完成仍必须 Restart Codex/Desktop 后创建新 task，不能把已出现 Transport closed 的旧 task 当作已原地修复。

完整的隔离 CLI/Desktop canary、crash recovery、worktree 与回滚证据要求见 shared HTTP daemon canary runbook。 CLI canary 的 MCP URL 应通过 codex exec --ignore-user-config -c 'mcp_servers...={url="..."}' 作单次进程覆盖；临时 CODEX_HOME 可验证注册形状，但不应复制真实认证或用户配置来运行任务。

可单独开发/隔离验证 HTTP host；务必使用临时 cache、ownership 和未占用端口，不能指向当前被 stdio 使用的真实 worktree：

JAVA_LSP_HTTP_PORT=38457 \
JAVA_LSP_CACHE_BASE=/absolute/isolated/cache \
JAVA_LSP_OWNERSHIP_BASE=/absolute/isolated/ownership \
npm run start:http

npm run smoke:http -- --url http://127.0.0.1:38457/mcp

HTTP 模式固定绑定 127.0.0.1，只提供严格的 /mcp、/healthz、/readyz（拒绝大小写、尾斜杠和 query 变体）。MCP transport 是 stateless：每个 POST 使用独立 protocol/transport，但所有请求共享一个 application/runtime manager。请求或 client 关闭不会关闭其他 worktree runtime；daemon SIGINT/SIGTERM 进入 drain，超时则终止已拥有的 JDT、保留 canonical-root lease，避免 stdio/HTTP 交接时并发写 workspace 或 SourceIndex。

浏览器请求如果携带 Origin，默认全部拒绝；确需允许时通过 JAVA_LSP_HTTP_ALLOWED_ORIGINS 配置精确的 loopback origin。不要把 bearer token、源码或完整 tool payload写入配置和日志。

受管布局：

~/Library/Application Support/codex-java-lsp-mcp/
  releases/<build-id>/
  current -> releases/<build-id>
  state/
  run-daemon.sh
  daemonctl.sh
~/Library/LaunchAgents/com.lky.codex-java-lsp-mcp.plist
~/Library/Logs/codex-java-lsp-mcp/

release rollback 使用 daemonctl.sh rollback-release。它会先验证前一 release 的 daemon.env、LaunchAgent、稳定入口、daemon identity 与 predecessor pointer 均完整，随后确认 bootout 已真正卸载 LaunchAgent、等待 PID 退出，再原子恢复前一 release 与其配置；任一验证/卸载失败都 fail-closed，且不会停止当前 daemon。若已经切到 HTTP 而需恢复 stdio，使用 daemonctl.sh rollback-stdio：它同样会先确认 HTTP LaunchAgent 已卸载和 PID 已退出，再恢复已保存的 stdio MCP registration；随后手动 Restart Codex/Desktop。若 stdio registration 恢复命令本身失败，controller 会立即恢复保存的 HTTP URL、重新启动并 smoke managed daemon，之后以失败状态退出，避免留下“HTTP 已停且 MCP 缺失”的半切换状态。不要让 stdio 与 HTTP 同时针对同一个 canonical root 做 semantic 调用。

兼容入口：

./install-codex-mcp.sh

项目启用

启用一个 Java repo：

"$HOME/Library/Application Support/codex-java-lsp-mcp/register-alias.sh" \
  --enable-lsp my-java-app /absolute/path/to/my-java-app \
  --layout-profile maven-reactor

禁用 LSP 但保留 alias：

"$HOME/Library/Application Support/codex-java-lsp-mcp/register-alias.sh" \
  --disable-lsp my-java-app /absolute/path/to/my-java-app

可选 layoutProfile：

• ddd-gradle

• maven-reactor

• generic-java

每次使用前先确认当前 repo 解析结果：

{"tool":"java_status","arguments":{"repoRoot":"/absolute/current/worktree","start":false}}

只有返回的 repoRoot 等于当前 worktree，才继续信任 LSP 结果。

Worktree 规则

• 如果当前 worktree 与某个 lspEnabled=true 配置 root 共享同一个 Git common-dir，允许继承“可启动 LSP”的权限。

• 继承的只是 enablement，不继承主工作区的 runtime/cache。

• 当前 worktree 仍使用自己的 canonical repoRoot、repoHash、JDT LS workspace、日志和 SourceIndex。

• 独立 clone、复制目录、不同 Git common-dir 的 review worktree 不自动继承，需要单独注册绝对路径。

• 如果多个 enabled alias 共享同一 Git family 且无法唯一判断，hook 静默放行，java_status 返回 conflict。

Codex Hook

生成 Codex UserPromptSubmit advisory hook 配置：

"$HOME/Library/Application Support/codex-java-lsp-mcp/install-hook.sh"

hook 行为：

• 每次执行重新读取 projects.json。

• 只校验当前 cwd 是否命中 lspEnabled=true 或 Git worktree family 继承。

• 未启用、冲突、非 Java 语义提示时静默放行。

• 只追加短提示，不直接启动 JDT LS，不阻断 shell/rg。

• 提示 agent 先用 java_status(start=false) 校验 repoRoot；已配置项目不能只报告 LSP server 未启动，若返回 started=false，必须用 java_status(start=true) 主动启动。

Public MCP Tools

推荐默认调用顺序：

{"tool":"java_status","arguments":{"repoRoot":"/absolute/repo","start":true}}
{"tool":"java_impact","arguments":{"repoRoot":"/absolute/repo","anchors":[{"file":"src/main/java/demo/OrderService.java","line":42,"column":18}],"semanticPolicy":"auto"}}

排查 runtime、watcher roots、JDK candidates、raw LSP URI/range 或完整 diagnostics 时显式打开诊断字段：

{"tool":"java_status","arguments":{"repoRoot":"/absolute/repo","start":false,"detail":"diagnostic"}}

默认不要在每次查询后调用 java_shutdown；让 idle TTL 回收 JDT LS，才能复用 workspace import、JDT LS 内存索引和 SourceIndex 缓存。

需要强语义结果时：

{"tool":"java_symbol","arguments":{"repoRoot":"/absolute/repo","query":"OrderService"}}

配置

projects.json 示例：

{
  "aliases": [
    {
      "id": "my-java-app",
      "root": "/absolute/path/to/my-java-app",
      "lspEnabled": true,
      "layoutProfile": "maven-reactor"
    }
  ],
  "defaults": {}
}

常用环境变量：

streamable_http 模式拒绝 JDTLS_DATA_DIR / JDTLS_LOG_DIR 单例目录覆盖；stdio 兼容模式仅把它们视为 base，并强制追加 canonical repoHash。

32GB 内存机器的默认资源策略通常是：

• JAVA_LSP_MAX_ACTIVE_REPOS=3

• JAVA_LSP_JDTLS_XMX=2g

• JAVA_LSP_IDLE_TTL_MS=2700000

• JAVA_LSP_RUNTIME_ENTRY_TTL_MS=3600000

• JAVA_LSP_MAX_RUNTIME_ENTRIES=16

• JAVA_LSP_WORKTREE_CACHE_TTL_DAYS=2

• JAVA_LSP_IMPORT_CONCURRENCY=2

• JAVA_LSP_RG_CONCURRENCY=4

• JAVA_LSP_DOCUMENT_SYMBOL_GLOBAL_CONCURRENCY=2

• JAVA_LSP_DOCUMENT_SYMBOL_PER_REPO_CONCURRENCY=1

• JAVA_LSP_DOCUMENT_SYMBOL_TIMEOUT_MS=2000

开发与验证

本地开发：

npm ci
npm run build
npm test

MCP readiness：

./check-codex-mcp.sh --fast

HTTP 注册后的 smoke 只连接已运行的 LaunchAgent daemon，不会启动第二个 server：

./check-codex-mcp.sh --smoke --repo-root /absolute/path/to/java-repo

要求真实启动 LSP 的 smoke：

./check-codex-mcp.sh --smoke --repo-root /absolute/path/to/java-repo --require-lsp

需要验证 rollback stdio release 时显式使用：

./check-codex-mcp.sh --stdio-smoke --repo-root /absolute/path/to/java-repo

benchmark 入口：

npm run benchmark:agent-impact -- --repo-root /absolute/path/to/java-repo --project-id <id> --warm-state cold-nolsp --strategy impact --runs 5 --verbosity diagnostic
npm run benchmark:impact-attribution -- --repo-root /absolute/path/to/java-repo --project-id <id>

当前 benchmark 口径：

• hard gate 是 R_read_must=1.0000；side/test/SQL/config 证据只参与诊断，不进 hard gate。

• goldenAttribution[] 用于判断缺口是 absent、readplan-full 还是已命中 readPlan。

• timing.phaseMs/sessionPhaseMs 用于 warm 延迟归因；warm-auto 已去掉 no-seed semantic verify 固定成本，warm-required 仍因 first-touch references P95 超过 800ms 而不可默认化。

最新验证报告：

• docs/java-lsp-mcp-benchmark-guide-2026-06-23.md

• docs/java-lsp-mcp-readplan-semantic-gap-report-2026-06-26.md

• docs/java-lsp-mcp-warm-latency-report-2026-06-27.md

• docs/java-lsp-mcp-warm-instrumentation-report-2026-06-29.md

• docs/java-lsp-mcp-warm-optimization-test-report-2026-06-29.md

故障排查

• codex-java-lsp currently supports macOS only：当前平台不是 macOS，回退到 rg、build、日志证据。

• jdtls not found：执行 brew install jdtls，或设置 JDTLS_BIN。

• Missing dist/server.js：先运行 npm run build，用户级 runtime 则重新执行 ./install-runtime.sh。

• HTTP daemon down：运行 daemonctl.sh status 检查 LaunchAgent、固定端口与 daemon stderr log；不要直接再起一个随机端口的生产 daemon。

• HTTP daemon build SHA differs from current release：停止 daemon 后执行 daemonctl.sh restart；若仍失败执行 daemonctl.sh rollback-release。

• 需要回到 stdio：先执行 daemonctl.sh rollback-stdio，确认 HTTP PID 已退出后 Restart Codex/Desktop；如果命令报错，先检查它是否已经恢复 HTTP URL 和 daemon health，再排查 stdio registration；不要通过两个 MCP transport 并行兜底。

• Project root is not LSP-enabled：用 register-alias.sh --enable-lsp <id> <absolute-root> 显式启用。

• Multiple enabled aliases share this Git common-dir：为当前 worktree 单独注册绝对路径，消除 family 继承歧义。

• No idle Java LSP runtime available：降低并发、关闭空闲 repo，或调整 JAVA_LSP_MAX_ACTIVE_REPOS。

安全说明

• MCP tools 不会写入目标 Java repo。

• JDT LS 可能读取项目配置并执行语言服务器需要的导入流程；不要对不可信 repo 启用 LSP。

• 不要在公开 issue 中粘贴私有路径、源码片段、日志中的 token 或企业内部包名。

• 发现安全问题时，优先通过 GitHub Security Advisory 或私有渠道报告；不要先公开 PoC。

贡献规范

• 保持改动小而可审阅；不要为单次需求提前抽象。

• 不要扩大 7 个 public tools 的工具面，除非 issue 或设计说明给出明确需求。

• 优先补定向测试：repo 解析、worktree 继承、资源限制、JDK 解析、SourceIndex、tool handler 行为。

• 提交前至少运行：

npm run build
npm test

• 贡献代码默认按 Apache License 2.0 授权，除非贡献者在提交中明确说明更严格且兼容的授权边界。

许可证

本项目采用 Apache License 2.0。

使用、复制、修改、分发本项目时需要遵守 Apache-2.0 的核心约束：

• 保留版权声明、许可证文本和已有 NOTICE 内容。

• 修改过的文件应按许可证要求保留显著的变更说明。

• Apache-2.0 包含专利授权和专利诉讼终止条款。

• Apache-2.0 不授予项目名称、商标、服务标识或产品名的使用权。

• 本项目按 “AS IS” 提供，不提供明示或默示担保。

• 第三方依赖保留其各自许可证；分发时需要同时满足第三方许可证要求。