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。

设计边界

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

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

• 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 会把当前项目复制到用户级 runtime、安装依赖、构建 dist/，并注册 Codex MCP server codex-java-lsp。

兼容入口：

./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": {}
}

常用环境变量：

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

• JAVA_LSP_MAX_ACTIVE_REPOS=3

• JAVA_LSP_JDTLS_XMX=2g

• JAVA_LSP_IDLE_TTL_MS=2700000

• 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

fast-path smoke：

./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

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。

• 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” 提供，不提供明示或默示担保。

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