Java语言智能服务器

jons mcp java

MCP服务器，通过Eclipse JDT提供Java语言智能。LS。

发布的软件包可从PyPI获得。开发版本也可以运行 从源代码签出或直接从GitHub。

当前公共API与 jons-mcp-typescript：公共职位 基于一个成功的工具响应是否使用结构化 items 和分页 形状和重构预览是只读的。

需求

• Python 3.10+
• Java 21+
• Eclipse JDT。LS
• 包含Gradle项目标记的目标Java工作区： settings.gradle, settings.gradle.kts, build.gradle，或 build.gradle.kts

在macOS上使用Homebrew：

brew install openjdk@21 jdtls

如果Java不在您的PATH中，请设置 JAVA_HOME如果JDT。LS安装在某个地方 自定义，设置 JDTLS_HOME。服务器还尝试解析 jdtls 可在PATH上执行。

如果 JDTLS_HOME 指向只读安装，如Nix存储、服务器 复制小平台 config_<os> 将目录放入可写缓存中 $XDG_CACHE_HOME/jons-mcp-java 或 ~/.cache/jons-mcp-java.Set JDTLS_CONFIG_DIR 选择特定的可写配置目录。这 即使源存档或 该软件包附带只读模式位。

安装并运行

来自PyPI：

uvx jons-mcp-java /path/to/java-workspace

从源代码检查：

git clone git@github.com:jonmmease/jons-mcp-java.git
cd jons-mcp-java
uv sync
uv run jons-mcp-java /path/to/java-workspace

来自GitHub，无需持续签出：

uvx --from git+https://github.com/jonmmease/jons-mcp-java.git \
  jons-mcp-java /path/to/java-workspace

将Java工作区根作为可选位置参数传递，或设置 JONS_MCP_JAVA_WORKSPACE。位置论证优先。如果两者都没有 服务器使用MCP进程当前工作目录。全部 从该工作区根解析相对刀具路径。

MCP客户端示例

使用PyPI的Claude代码：

claude mcp add jons-mcp-java \
  -- uvx jons-mcp-java /path/to/java-workspace

Claude代码使用源代码签出：

claude mcp add jons-mcp-java \
  -- uv run --project /path/to/jons-mcp-java \
  jons-mcp-java /path/to/java-workspace

使用GitHub编写Claude代码：

claude mcp add jons-mcp-java \
  -- uvx --from git+https://github.com/jonmmease/jons-mcp-java.git \
  jons-mcp-java /path/to/java-workspace

使用PyPI的Codex CLI：

codex mcp add jons-mcp-java \
  -- uvx jons-mcp-java /path/to/java-workspace

使用GitHub的Codex CLI：

codex mcp add jons-mcp-java \
  -- uvx --from git+https://github.com/jonmmease/jons-mcp-java.git \
  jons-mcp-java /path/to/java-workspace

.mcp.json:

{
  "mcpServers": {
    "jons-mcp-java": {
      "command": "uvx",
      "args": [
        "jons-mcp-java",
        "/path/to/java-workspace"
      ]
    }
  }
}

TOML食品法典：

[mcp_servers.jons-mcp-java]
command = "uvx"
args = [
  "jons-mcp-java",
  "/path/to/java-workspace",
]

工作空间和路径行为

配置的工作区根是文件系统安全边界。

• 刀具路径可以是工作空间相对路径、工作空间内绝对路径或 file:// URI。
• 相对路径是从配置的工作区根解析的，而不是从 MCP服务器进程cwd。
• 路径包含 ..、工作区外的路径、非文件URI、格式错误 URI、丢失的文件和符号链接转义在任何文件系统或 JDT。LS访问。
• 工作区外的LSP位置仍可能返回 "inWorkspace": false，但服务器不打开或读取外部文件。

路径和启动失败使用稳定的错误形状：

{
  "status": "error",
  "error": {
    "type": "path_outside_workspace",
    "message": "Path resolves outside the configured workspace root.",
    "path": "../outside.java"
  }
}

可用工具

项目的第一个文件支持调用将启动JDT。LS懒散而平常 返回：

{
  "status": "initializing",
  "message": "Starting project initialization; please retry shortly.",
  "project": "/path/to/java-workspace/app"
}

初始化完成后重试相同的工具。

工具行为

接受或退回的工具 line 和 character 使用基于一个的位置， 匹配编辑器和代理 Read 输出。如果编辑器显示第28行，请传递 line=28；返回的范围使用相同的约定。使用 document_symbols 到 当你还不知道位置时，发现一个基于符号的范围。

成功的导航工具返回标准化项目：

{
  "items": [
    {
      "uri": "file:///path/to/Main.java",
      "range": {
        "start": { "line": 12, "character": 8 },
        "end": { "line": 12, "character": 12 }
      },
      "inWorkspace": true
    }
  ],
  "totalItems": 1
}

references, document_symbols, workspace_symbols，以及 diagnostics 返回 分页结果 items, totalItems, offset, limit, hasMore，以及 nextOffset.

导航工具保留了JDT。LS结果排序和返回 items 加 totalItems. references、诊断和符号列表已排序 在分页之前确定。

preview_rename 检查是安全的。它返回文件URI的平面列表， 基于一个替换范围， newText，以及 inWorkspace 值，加 totalEdits。它不会写入磁盘。

新鲜与重启

服务器跟踪打开的LSP文档，并比较磁盘元数据和内容 在读取样式工具调用之前进行哈希。如果文件在JDT之外更改。LS 服务器发送完整文档 didChange 和 didSave 在要求新鲜之前 语言数据。

diagnostics 是文件范围的，并且始终在之前刷新目标文件 返回编译器诊断。

使用 restart_server 仅作为后备方案：

{ "file_path": "app/src/main/java/example/Main.java" }

没有 file_path, restart_server 停止所有活动的JDT。LS客户。服务器 在下一次文件备份工具调用时延迟重新启动。

故障排除

• JDT.LS not found：安装JDT。LS，放 jdtls 在PATH上，或设置 JDTLS_HOME.
• Java 21+ required：安装Java 21+或设置 JAVA_HOME.
• project_not_found：文件位于工作区内，但不在 发现了Gradle根。
• path_outside_workspace：路径在外部解析 配置的工作区根。
• project_startup_failed：项目导入失败；检查JDT。LS标准错误 在生成的工作区数据目录下登录 ~/.cache/jdtls-workspaces.
• 只读 JDTLS_HOME：set JDTLS_CONFIG_DIR 到可写目录，或让 服务器会自动创建并修复其缓存的配置副本。