MCP Java Bridge

MCP Java桥

MCP Java服务器的运行时解耦解决方案，解决了基于stdio的集成中固有的紧耦合问题。

  

问题

MCP Java SDK中的原生stdio实现在客户端和服务器运行时之间创建了紧密耦合。这种耦合会导致几个关键问题：

• 资源争用：客户端和服务器争夺相同的系统资源
• 记录冲突：两个进程都写入相同的输出流，这使得调试变得困难
• 环境污染：服务器环境变量和系统属性会影响客户端
• 生命周期管理：服务器生命周期与客户端进程绑定，防止独立扩展
• 开发复杂性：测试和调试需要同时运行这两个组件

解决方案

虽然Streamable HTTP是解耦通信的理想替代方案，但当前的MCP Java SDK仅支持SSE（服务器发送事件）和stdio传输，而不支持Streamable HTTP。这种限制导致了MCP Java桥的创建。

MCP Java Bridge在保持完全stdio兼容性的同时，将客户端和服务器运行时解耦。它引入了一种轻量级的“连接器”，该连接器：

1. 通过stdio与MCP客户端集成 （与Claude Desktop和其他客户端100%兼容）
2. 通过TCP连接到Java服务器 幕后
3. 在自己的进程中运行每个组件 资源孤立
4. 无需更改 到您现有的MCP服务器代码
5. 对客户和开发人员透明 -就是开箱即用

其结果是一个健壮的、可用于生产的集成，解决了所有的耦合问题，同时保持了MCP协议的简单性。

建筑

┌─────────────────┐        stdio         ┌───────────────────────────────────┐
│  Claude Desktop │ ◄──────────────────► │          MCP Bridge               │
│    (Client)     │                      │ ┌─────────┐      ┌──────────┐   │
└─────────────────┘                      │ │  Stub   │ TCP  │ Skeleton │   │
                                         │ │ (stdio) │◄────►│  (Java)  │   │
                                         │ └─────────┘      └──────────┘   │
                                         └───────────────────────────────────┘
                                                                 │
                                                                 │ Embedded
                                                                 ▼
                                                         ┌─────────────────┐
                                                         │ MCP Java Server │
                                                         │   (with SDK)    │
                                                         └─────────────────┘

特性

• 多功能JAR：单个JAR用作库、连接器和安装程序
• 透明TCP支持：启用TCP连接，无需修改客户端
• 简单集成：易于与现有的MCP Java服务器集成
• 生产就绪：包括日志记录、错误处理和连接管理
• 灵活的配置：可配置的端口和连接设置
• 交互式安装程序：Claude Desktop的零配置设置
• 自行安装：JAR可以将自己安装为连接器

入门指南

步骤1：添加依赖关系

将mcp-java桥添加到您的项目中：

梅文

    org.gegolabs.mcp
    mcp-java-bridge
    1.0.0-SNAPSHOT

Gradle

implementation 'org.gegolabs.mcp:mcp-java-bridge:1.0.0-SNAPSHOT'

备注：这目前是快照版本。添加 mavenLocal() 如果您在本地安装了它，请将其添加到您的存储库中。

步骤2：创建MCP服务器

使用网桥创建具有TCP传输的MCP服务器：

选项1：使用桥接器

import org.gegolabs.mcp.bridge.McpBridge;
import io.modelcontextprotocol.sdk.McpServer;

public class MyMcpServer {
    public static void main(String[] args) throws Exception {
        // Create bridge
        McpBridge bridge = McpBridge.builder()
            .port(3000)
            .build();
        
        // Create your MCP server with bridge transport
        McpServer server = McpServer.builder()
            .transportProvider(bridge.getTransportProvider())
            .toolsProvider(() -> /* your tools */)
            .toolHandler((name, args) -> /* handle tool calls */)
            .build();
        
        server.start();
        
        // Keep the server running
        Thread.currentThread().join();
    }
}

选项2：使用静态工厂方法

import org.gegolabs.mcp.bridge.McpBridge;
import io.modelcontextprotocol.sdk.McpServer;

public class MyMcpServer {
    public static void main(String[] args) throws Exception {
        McpServer server = McpServer.builder()
            .transportProvider(McpBridge.tcpTransport(3000))
            .toolsProvider(() -> /* your tools */)
            .toolHandler((name, args) -> /* handle tool calls */)
            .build();
        
        server.start();
        Thread.currentThread().join();
    }
}

步骤3：安装克劳德桌面

构建MCP服务器后，您需要配置Claude Desktop以连接到它。MCP-java桥JAR包含一个用于此目的的CLI安装程序。

访问Bridge JAR

由于您已将mcp-java-bridge添加为依赖项，因此可以通过两种方式访问它：

来自Maven仓库：

java -jar ~/.m2/repository/org/gegolabs/mcp/mcp-java-bridge/1.0.0/mcp-java-bridge-1.0.0.jar

或者使用Gradle任务复制它：

task copyBridgeJar(type: Copy) {
    from configurations.runtimeClasspath.filter { it.name.contains('mcp-java-bridge') }
    into 'install'
    rename { 'mcp-bridge.jar' }
}

然后： ./gradlew copyBridgeJar

配置Claude桌面

从以下三个选项中选择一个：

选项A：交互式安装（推荐）

运行安装程序，不带参数，以进行引导安装：

java -jar mcp-java-bridge-1.0.0.jar

这将：

• 自动检测JAR位置
• 提示输入服务器名称（例如“我的服务器”）
• 主机提示（默认：localhost）
• 提示输入端口（默认值：3000）
• 自动配置克劳德桌面
• 创建现有配置的备份

选项B：命令行安装

对于自动设置，请使用特定参数：

java -jar mcp-java-bridge-1.0.0.jar install \
  -n "my-server" \
  -c mcp-java-bridge-1.0.0.jar \
  -h localhost \
  -p 3000

参数：

• -n -Claude Desktop中的服务器名称（必填）
• -c -充当连接器的JAR的路径
• -h -服务器主机（默认：localhost）
• -p -服务器端口（默认值：3000）

选项C：手动配置

如果您更喜欢手动配置，请编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "java",
      "args": [
        "-jar",
        "/path/to/mcp-java-bridge-1.0.0.jar",
        "--connector",
        "localhost",
        "3000"
      ]
    }
  }
}

步骤4：启动服务器

1. 启动MCP服务器（确保它在配置的端口上运行）
2. 重新启动Claude Desktop以加载新配置
3. 您的服务器现在应该可以在Claude Desktop中使用

额外资源

示例代码

该项目在源代码中包含示例代码：

• SimpleExample.java -基本回声服务器显示最小设置
• ExampleServer.java -具有多种工具的全功能服务器（这是作为演示JAR构建的服务器）

构建工件

建造完成后，您会在 build/libs/:

• mcp-java-bridge-1.0.0-SNAPSHOT.jar -主JAR（库+连接器+安装程序）
• mcp-java-bridge-1.0.0-SNAPSHOT-example.jar -演示服务器应用程序
• mcp-java-bridge-1.0.0-SNAPSHOT-sources.jar -源代码

演示应用程序

演示JAR(mcp-java-bridge-1.0.0-SNAPSHOT-example.jar)使用以下工具运行ExampleServer：

• 回声 -回显消息
• 获取时间 -以各种格式返回当前时间
• todo_list -管理一个简单的待办事项列表（添加、删除、列出、清除）
• key_value_store -简单键值存储（获取、设置、删除、列表）
• 计算器 -基本的数学运算（加、减、乘、除、幂、sqrt）

运行演示

1. 构建项目 （如果尚未建成）：

   ./gradlew clean build

1. 运行演示服务器:

   # Using the provided script
   cd examples
   ./run-demo.sh

   # Or run directly
   java -jar build/libs/mcp-java-bridge-1.0.0-SNAPSHOT-example.jar

1. 卷曲测试 （可选）：

虽然服务器是为MCP客户端设计的，但您可以验证它是否正在运行：

   # This will fail with a protocol error (expected) but confirms the server is listening
   telnet localhost 3000

1. 配置Claude桌面 使用安装程序（请参阅入门中的步骤3）

演示脚本

这 examples/run-demo.sh 脚本：

• 检查Java版本（需要Java 17+）
• 根据需要构建项目
• 启动示例服务器
• 显示Claude桌面配置

CLI命令

MCP Java Bridge JAR是一个多用途工具，提供三种不同的功能：

1.交互式安装程序（默认-无参数）

不带参数运行会启动交互式安装程序：

java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar

这将：

• 自动检测JAR位置
• 提示输入服务器名称（例如，“我的mcp服务器”）
• 主机提示（默认：localhost）
• 提示输入端口（默认值：3000）
• 自动配置克劳德桌面
• 创建现有配置的备份

2.连接器模式

作为连接器运行以桥接stdio↔TCP通信。这是Claude Desktop执行的操作：

# With default settings (localhost:3000)
java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --connector

# With custom host/port
java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --connector 192.168.1.100 8080

备注：此模式通常不是手动运行的，而是由Claude Desktop执行。

3.安装命令

对于具有特定参数的非交互式安装：

java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install -n  -c  [-h ] [-p 
]

论据：

• -n -Claude Desktop中的服务器名称（必填）
• -c -充当连接器的JAR或脚本的路径
• -h -服务器主机（默认：localhost）
• -p -服务器端口（默认值：3000）

示例：

# Install using the same JAR as connector
java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install \
  -n "my-server" \
  -c ./mcp-java-bridge-1.0.0-SNAPSHOT.jar \
  -h localhost \
  -p 3000

# Install using a custom script as connector (e.g., from uMCP)
java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install \
  -n "my-umcp-server" \
  -c /path/to/uMCP/install/bin/uMCP-connector \
  -h localhost \
  -p 3000

Help命令

显示使用信息：

java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --help

使用Claude Desktop进行测试

连接后，您可以测试演示工具：

1. 回声工具:

   "Please use the echo tool to say 'Hello from MCP!'"

1. 时间工具:

   "What time is it? Show me in different formats."

1. 事项清单:

   "Add 'Test MCP Bridge' to my todo list"
   "Show me my todo list"
   "Remove 'Test MCP Bridge' from the list"

1. 键值存储:

   "Store my name as 'John Doe' in the key-value store"
   "What's stored under the key 'name'?"

1. 计算器:

   "Calculate 42 * 17 using the calculator tool"
   "What's the square root of 144?"

公用事业

日志记录配置

该桥包括用于配置基于文件的日志记录的实用程序，这对调试至关重要：

import org.gegolabs.mcp.bridge.utils.LoggingUtils;

// Enable file logging
LoggingUtils.initializeFileLogging("my-mcp-server.log");

// Enable debug logging
LoggingUtils.enableDebugLogging();

日志保存到 ~/.mcp-bridge/logs/.

JSON模式生成

为您的工具参数生成JSON模式：

import org.gegolabs.mcp.bridge.utils.JsonSchemaUtils;

public class MyToolParams {
    @JsonSchemaUtils.Description("The user's name")
    private String name;
    
    @JsonSchemaUtils.Description("The user's age")
    private int age;
}

// Generate schema
String schema = JsonSchemaUtils.generateJsonSchema(MyToolParams.class);

发展

从源头构建

git clone https://github.com/gegolabs/mcp-java-bridge.git
cd mcp-java-bridge
./gradlew build

运行测试

./gradlew test

发布到本地Maven

./gradlew publishToMavenLocal

需求

• Java 17或更高版本
• MCP Java SDK 0.10.0或更高版本

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请随时提交拉取请求。E