中文 | English

MCP Server For Java

⚠️ v0.0.3 重要更新

MCP 客户端配置需要从：

{
  "command": "npx",
  "args": ["vscode-as-mcp-server"]
}

或

{
  "url": "http://localhost:60100"
}

修改为：

{
  "command": "npx",
  "args": ["vscode-to-mcp-server"]
}

如果不修改配置，将无法自动在多工作区间切换，只能获取第一个打开的工作区的类。

简介

Cursor、Github Copilot、Windsurf 等基于 VSCode 开发的 AI Code Agent 在编写 Java 项目时，可以访问项目本身的源代码，但无法获取项目依赖的类定义与源码。

本插件将 VSCode/Cursor 转变为 MCP 服务器，让 AI Agent 能够：

• 搜索 Java 类型：通过名称或部分名称在项目、外部依赖和 JDK 中搜索类 ————对应mcp工具searchJavaTypes
• 获取源代码：通过全限定名获取任意可访问类的源码（包括依赖库和 JDK）————对应mcp工具getSourceCodeByFQN

多工作区支持

• v0.0.3 之前：通过点击状态栏在多个 VSCode/Cursor 工作区之间切换 MCP 服务器
• v0.0.3 起：支持同时连接多个工作区，除非用户指定 AI Agent 会自动选择当前活动窗口对应的工作区

首次安装与设置

1. 确认已经安装插件Extension Pack for Java微软插件商品版本或Open VSX 版本 且可正常运行java项目

2. 下载安装本插件。

3. 配置您的MCP客户端，重启并确认mcp工具加载完成：

   • 如Claude Desktop，Curosr，Winsurf，Vsocde，Cherry studio等客户端：添加以下内容到您的配置文件(claude_desktop_config.json)中：

   {
     "mcpServers": {
       "vscode-java": {
         "command": "npx",
         "args": [
           "vscode-to-mcp-server"
         ]
       }
     }
   }

4. 打开一个java项目，并确保项目完全加载完毕

提高工具调用率（推荐配置）

为了让 AI Agent 更主动地调用本插件提供的工具，建议在系统提示词中添加以下内容（如果你没有更好或者更适合自己应用场景的提示词）：

通过项目源代码找不到的类或类的定义或方法具体实现，且有类名或者部分类名时，可以使用工具 searchJavaTypes 与 getSourceCodeByFQN 判断其是否存在，或获取其源代码

💡 以 Cursor 为例，可以在 Settings → General → Rules for AI → User Rules 中添加

插件参数声明

参数	类型	默认值	说明
mcpServer.maxOutputLength	number	70000	最大输出 Java 源代码字符数。当要获取的类的源代码超过此限制时会报错。不建议设置过大，过大会导致模型 input token 过大无法请求模型，或无法将类的源代码放入上下文中。
mcpServer.enableRelayVersionCheck	boolean	true	是否启用 relay 版本更新检查和通知。设置为 false 可禁用版本更新提醒。

联系

非常欢迎大家对插件的问题，bug或新功能建议进行反馈！ 🙇

更新日志

• 0.0.7 多根工作区支持
• 0.0.5 获取源码时，支持按方法名过滤
• 0.0.4 支持获取工作区中存在的全限定名相同但版本不同的类
• 0.0.3 mcp指令执行在多个工作区自动路由，无需手动切换
• 0.0.2 修改了查询全限定名有时候会查出不符合条件的结果的bug

架构说明

整体架构

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP 客户端                                      │
│                  (Claude Desktop / Cursor / Windsurf 等)                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ stdio (JSON-RPC)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          Relay (vscode-to-mcp-server)                        │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  - 接收 MCP 客户端请求                                                │    │
│  │  - 读取路由表，查找目标 Extension                                      │    │
│  │  - 通过 Socket 转发请求到 Extension                                   │    │
│  │  - 返回响应给 MCP 客户端                                              │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                   ┌────────────────┼────────────────┐
                   │                │                │
                   ▼                ▼                ▼
          ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
          │   Named Pipe │  │   Named Pipe │  │   Named Pipe │
          │  (Windows)   │  │  (Windows)   │  │  (Windows)   │
          │    或        │  │    或        │  │    或        │
          │ Unix Socket  │  │ Unix Socket  │  │ Unix Socket  │
          │   (其他)     │  │   (其他)     │  │   (其他)     │
          └──────────────┘  └──────────────┘  └──────────────┘
                   │                │                │
                   ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      VSCode/Cursor Extension 实例                            │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐                        │
│  │ 工作区 A    │   │ 工作区 B    │   │ 工作区 C    │   ...                  │
│  │ PID: 12345  │   │ PID: 23456  │   │ PID: 34567  │                        │
│  └─────────────┘   └─────────────┘   └─────────────┘                        │
│         │                │                │                                  │
│         ▼                ▼                ▼                                  │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    Java Language Server (JDT.LS)                     │    │
│  │            搜索类型 / 获取源代码 / 解析 Java 项目                      │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘

核心组件

组件	包名	说明
Extension	packages/extension	VSCode/Cursor 插件，提供 MCP 服务器功能
Relay	packages/relay	命令行中继程序，桥接 MCP 客户端与 Extension

Socket 通信机制

平台差异

平台	通信方式	路径格式
Windows	Named Pipe (命名管道)	\\.\pipe\vscode-mcp-{pid}
macOS/Linux	Unix Domain Socket	~/.vscode-mcp-sockets/{pid}.sock

路由表

路由表文件存储在用户主目录：~/.vscode-mcp-router-v2.json

{
  "entries": [
    {
      "workspaces": ["d:\\project\\workspace-a"],
      "pid": 12345,
      "lastUpdated": 1700000000000
    }
  ]
}

通信协议

• 格式: JSON-RPC 2.0
• 分隔符: 换行符 \n
• 超时: 连接 5秒 / 请求 30秒

请求头

Header	说明
X-Relay-Version	Relay 版本号，用于兼容性检查
X-MCP-Client	MCP 客户端标识

数据流

1. MCP 客户端调用工具 (如 searchJavaTypes)
                    │
                    ▼
2. Relay 接收 stdio 请求
                    │
                    ▼
3. Relay 读取路由表，根据 workspacePaths 查找目标 PID
                    │
                    ▼
4. Relay 通过 Socket 发送 JSON-RPC 请求到 Extension
                    │
                    ▼
5. Extension 调用 Java Language Server 执行操作
                    │
                    ▼
6. Extension 返回结果给 Relay
                    │
                    ▼
7. Relay 返回结果给 MCP 客户端

关键文件

文件	说明
extension/src/extension.ts	插件入口，初始化 MCP 服务器
extension/src/mcp-server.ts	MCP 服务器实现，注册工具
extension/src/sock-transport.ts	Socket 服务端传输层
extension/src/utils/router-table.ts	路由表管理（读写）
relay/src/index.ts	Relay 入口，请求转发
relay/src/socket-client.ts	Socket 客户端
relay/src/router-table.ts	路由表读取（只读）

MCP Server For Java

⚠️ v0.0.3 Important Update

MCP client configuration needs to be changed from:

{
  "command": "npx",
  "args": ["vscode-as-mcp-server"]
}

or

{
  "url": "http://localhost:60100"
}

to:

{
  "command": "npx",
  "args": ["vscode-to-mcp-server"]
}

Without updating the configuration, automatic multi-workspace switching will not work, and only classes from the first opened workspace will be accessible.

Overview

AI Code Agents based on VSCode (such as Cursor, Github Copilot, Windsurf) can access a Java project's own source code, but cannot retrieve class definitions and source code from project dependencies.

This extension turns VSCode/Cursor into an MCP server, enabling AI Agents to:

• Search Java Types: Search for classes by name or partial name across your project, external dependencies, and JDK — corresponding MCP tool searchJavaTypes
• Get Source Code: Retrieve source code of any accessible class by fully qualified name (including dependency libraries and JDK) — corresponding MCP tool getSourceCodeByFQN

Multi-Workspace Support

• Before v0.0.3: Switch MCP server between multiple VSCode/Cursor workspaces by clicking the status bar
• From v0.0.3: Supports connecting to multiple workspaces simultaneously. Unless specified by the user, AI Agent will automatically select the workspace corresponding to the currently active window

Installation & Setup

1. Confirm that the Extension Pack for Java plugin is installed (VS Marketplace or Open VSX) and can run Java projects normally

2. Download and install this extension.

3. Configure your MCP client, restart and confirm MCP tools are loaded:

   • For clients like Claude Desktop, Cursor, Winsurf, VSCode, Cherry studio: Add the following to your configuration file (claude_desktop_config.json):

   {
     "mcpServers": {
       "vscode-java": {
         "command": "npx",
         "args": [
           "vscode-to-mcp-server"
         ]
       }
     }
   }

4. Open a Java project and make sure the project is fully loaded

Improve Tool Invocation Rate (Recommended Configuration)

To help AI Agents invoke the tools provided by this extension more proactively, it is recommended to add the following content to your system prompt (if you don't have a better or more suitable prompt for your use case):

When you cannot find the class, class definition, or specific implementation of methods through the project source code, and you have the class name or partial class name, you can use the tools searchJavaTypes and getSourceCodeByFQN to check if it exists or get its source code

💡 For example, in Cursor, you can add this in Settings → General → Rules for AI → User Rules

Extension Parameters

Parameter	Type	Default	Description
mcpServer.maxOutputLength	number	70000	Maximum number of characters for Java source code output. An error will be reported when the source code exceeds this limit. It is not recommended to set it too large, as excessive values may cause the model's input token to be too large or make it impossible to place the class source code in the context.
mcpServer.enableRelayVersionCheck	boolean	true	Whether to enable relay version update check and notification. Set to false to disable version update warnings.

Contact

Feedback on issues, bugs, or suggestions for new features is highly welcomed! 🙇

Changelog

• 0.0.7 Multi-root workspace support
• 0.0.5 Support filtering by method names when retrieving source code
• 0.0.4 Support for retrieving classes with the same fully qualified name from multiple versions
• 0.0.3 MCP commands auto-route to multiple workspaces without manual switching
• 0.0.2 Fixed a bug where querying fully qualified names sometimes returned non-matching results

Architecture

Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP Client                                      │
│                  (Claude Desktop / Cursor / Windsurf, etc.)                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │ stdio (JSON-RPC)
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                          Relay (vscode-to-mcp-server)                        │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │  - Receives MCP client requests                                      │    │
│  │  - Reads router table to find target Extension                       │    │
│  │  - Forwards requests to Extension via Socket                         │    │
│  │  - Returns responses to MCP client                                   │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                   ┌────────────────┼────────────────┐
                   │                │                │
                   ▼                ▼                ▼
          ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
          │   Named Pipe │  │   Named Pipe │  │   Named Pipe │
          │  (Windows)   │  │  (Windows)   │  │  (Windows)   │
          │     or       │  │     or       │  │     or       │
          │ Unix Socket  │  │ Unix Socket  │  │ Unix Socket  │
          │   (Others)   │  │   (Others)   │  │   (Others)   │
          └──────────────┘  └──────────────┘  └──────────────┘
                   │                │                │
                   ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                      VSCode/Cursor Extension Instances                       │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐                        │
│  │ Workspace A │   │ Workspace B │   │ Workspace C │   ...                  │
│  │ PID: 12345  │   │ PID: 23456  │   │ PID: 34567  │                        │
│  └─────────────┘   └─────────────┘   └─────────────┘                        │
│         │                │                │                                  │
│         ▼                ▼                ▼                                  │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    Java Language Server (JDT.LS)                     │    │
│  │          Search types / Get source code / Parse Java projects        │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘

Core Components

Component	Package	Description
Extension	packages/extension	VSCode/Cursor extension providing MCP server functionality
Relay	packages/relay	CLI relay program bridging MCP client and Extension

Socket Communication

Platform Differences

Platform	Method	Path Format
Windows	Named Pipe	\\.\pipe\vscode-mcp-{pid}
macOS/Linux	Unix Domain Socket	~/.vscode-mcp-sockets/{pid}.sock

Router Table

Router table file is stored in user home directory: ~/.vscode-mcp-router-v2.json

{
  "entries": [
    {
      "workspaces": ["d:\\project\\workspace-a"],
      "pid": 12345,
      "lastUpdated": 1700000000000
    }
  ]
}

Communication Protocol

• Format: JSON-RPC 2.0
• Delimiter: Newline \n
• Timeout: Connection 5s / Request 30s

Request Headers

Header	Description
X-Relay-Version	Relay version for compatibility check
X-MCP-Client	MCP client identifier

Data Flow

1. MCP client calls a tool (e.g., searchJavaTypes)
                    │
                    ▼
2. Relay receives stdio request
                    │
                    ▼
3. Relay reads router table, finds target PID by workspacePaths
                    │
                    ▼
4. Relay sends JSON-RPC request to Extension via Socket
                    │
                    ▼
5. Extension calls Java Language Server to execute operation
                    │
                    ▼
6. Extension returns result to Relay
                    │
                    ▼
7. Relay returns result to MCP client

Key Files

File	Description
extension/src/extension.ts	Extension entry point, initializes MCP server
extension/src/mcp-server.ts	MCP server implementation, registers tools
extension/src/sock-transport.ts	Socket server transport layer
extension/src/utils/router-table.ts	Router table management (read/write)
relay/src/index.ts	Relay entry point, request forwarding
relay/src/socket-client.ts	Socket client
relay/src/router-table.ts	Router table reading (read-only)