{"id":29189896,"url":"https://github.com/cobach/mcp-java-bridge","last_synced_at":"2026-04-21T16:31:42.443Z","repository":{"id":302308054,"uuid":"1011490329","full_name":"cobach/mcp-java-bridge","owner":"cobach","description":"Runtime decoupling solution for MCP Java servers, solving the tight coupling issues inherent in stdio-based integration.","archived":false,"fork":false,"pushed_at":"2025-07-01T17:25:59.000Z","size":101,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-01T17:32:13.451Z","etag":null,"topics":["java","mcp","stdio"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cobach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T22:49:01.000Z","updated_at":"2025-07-01T17:26:02.000Z","dependencies_parsed_at":"2025-07-01T17:35:16.242Z","dependency_job_id":"163b3ca5-56de-4cb4-833c-2be03e9233f9","html_url":"https://github.com/cobach/mcp-java-bridge","commit_stats":null,"previous_names":["cobach/mcp-java-bridge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cobach/mcp-java-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cobach%2Fmcp-java-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cobach%2Fmcp-java-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cobach%2Fmcp-java-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cobach%2Fmcp-java-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cobach","download_url":"https://codeload.github.com/cobach/mcp-java-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cobach%2Fmcp-java-bridge/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263047686,"owners_count":23405280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","mcp","stdio"],"created_at":"2025-07-01T23:18:19.001Z","updated_at":"2026-04-21T16:31:37.416Z","avatar_url":"https://github.com/cobach.png","language":"Java","readme":"# MCP Java Bridge\n\nRuntime decoupling solution for MCP Java servers, solving the tight coupling issues inherent in stdio-based integration.\n\n[![Java 17+](https://img.shields.io/badge/Java-17%2B-blue.svg)](https://openjdk.java.net/projects/jdk/17/)\n[![MCP SDK](https://img.shields.io/badge/MCP%20SDK-0.10.0-green.svg)](https://github.com/modelcontextprotocol/java-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## The Problem\n\nThe native stdio implementation in the MCP Java SDK creates a tight coupling between the client and server runtimes. This coupling causes several critical issues:\n\n- **Resource contention**: Client and server compete for the same system resources\n- **Logging conflicts**: Both processes write to the same output streams, making debugging difficult\n- **Context pollution**: Server environment variables and system properties affect the client\n- **Lifecycle management**: Server lifecycle is tied to client process, preventing independent scaling\n- **Development complexity**: Testing and debugging require running both components together\n\n## The Solution\n\nWhile Streamable HTTP would be the ideal alternative for decoupled communication, the current MCP Java SDK only supports SSE (Server-Sent Events) and stdio transports - not Streamable HTTP. This limitation led to the creation of MCP Java Bridge.\n\nMCP Java Bridge decouples the client and server runtimes while maintaining full stdio compatibility. It introduces a lightweight \"connector\" that:\n\n1. **Integrates with MCP clients via stdio** (100% compatible with Claude Desktop and other clients)\n2. **Connects to your Java server via TCP** behind the scenes\n3. **Runs each component in its own process** with isolated resources\n4. **Requires zero changes** to your existing MCP server code\n5. **Transparent to both client and developer** - just works out of the box\n\nThe result is a robust, production-ready integration that solves all the coupling issues while maintaining the simplicity of the MCP protocol.\n\n## Architecture\n\n```\n┌─────────────────┐        stdio         ┌───────────────────────────────────┐\n│  Claude Desktop │ ◄──────────────────► │          MCP Bridge               │\n│    (Client)     │                      │ ┌─────────┐      ┌──────────┐   │\n└─────────────────┘                      │ │  Stub   │ TCP  │ Skeleton │   │\n                                         │ │ (stdio) │◄────►│  (Java)  │   │\n                                         │ └─────────┘      └──────────┘   │\n                                         └───────────────────────────────────┘\n                                                                 │\n                                                                 │ Embedded\n                                                                 ▼\n                                                         ┌─────────────────┐\n                                                         │ MCP Java Server │\n                                                         │   (with SDK)    │\n                                                         └─────────────────┘\n```\n\n## Features\n\n- **All-in-One JAR**: Single JAR serves as library, connector, and installer\n- **Transparent TCP Support**: Enables TCP connectivity without client modifications\n- **Simple Integration**: Easy to integrate with existing MCP Java servers\n- **Production Ready**: Includes logging, error handling, and connection management\n- **Flexible Configuration**: Configurable ports and connection settings\n- **Interactive Installer**: Zero-configuration setup for Claude Desktop\n- **Self-Installing**: The JAR can install itself as a connector\n\n## Getting Started\n\n### Step 1: Add Dependency\n\nAdd mcp-java-bridge to your project:\n\n#### Maven\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.gegolabs.mcp\u003c/groupId\u003e\n    \u003cartifactId\u003emcp-java-bridge\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### Gradle\n```groovy\nimplementation 'org.gegolabs.mcp:mcp-java-bridge:1.0.0-SNAPSHOT'\n```\n\n**Note**: This is currently a SNAPSHOT version. Add `mavenLocal()` to your repositories if you've installed it locally.\n\n### Step 2: Create Your MCP Server\n\nUse the bridge to create your MCP server with TCP transport:\n\n#### Option 1: Using the Bridge Builder\n\n```java\nimport org.gegolabs.mcp.bridge.McpBridge;\nimport io.modelcontextprotocol.sdk.McpServer;\n\npublic class MyMcpServer {\n    public static void main(String[] args) throws Exception {\n        // Create bridge\n        McpBridge bridge = McpBridge.builder()\n            .port(3000)\n            .build();\n        \n        // Create your MCP server with bridge transport\n        McpServer server = McpServer.builder()\n            .transportProvider(bridge.getTransportProvider())\n            .toolsProvider(() -\u003e /* your tools */)\n            .toolHandler((name, args) -\u003e /* handle tool calls */)\n            .build();\n        \n        server.start();\n        \n        // Keep the server running\n        Thread.currentThread().join();\n    }\n}\n```\n\n### Option 2: Using Static Factory Method\n\n```java\nimport org.gegolabs.mcp.bridge.McpBridge;\nimport io.modelcontextprotocol.sdk.McpServer;\n\npublic class MyMcpServer {\n    public static void main(String[] args) throws Exception {\n        McpServer server = McpServer.builder()\n            .transportProvider(McpBridge.tcpTransport(3000))\n            .toolsProvider(() -\u003e /* your tools */)\n            .toolHandler((name, args) -\u003e /* handle tool calls */)\n            .build();\n        \n        server.start();\n        Thread.currentThread().join();\n    }\n}\n```\n\n### Step 3: Instalación en Claude Desktop\n\nAfter building your MCP server, you need to configure Claude Desktop to connect to it. The mcp-java-bridge JAR includes a CLI installer for this purpose.\n\n#### Access the Bridge JAR\n\nSince you've added mcp-java-bridge as a dependency, you can access it in two ways:\n\n**From Maven Repository:**\n```bash\njava -jar ~/.m2/repository/org/gegolabs/mcp/mcp-java-bridge/1.0.0/mcp-java-bridge-1.0.0.jar\n```\n\n**Or copy it using a Gradle task:**\n```gradle\ntask copyBridgeJar(type: Copy) {\n    from configurations.runtimeClasspath.filter { it.name.contains('mcp-java-bridge') }\n    into 'install'\n    rename { 'mcp-bridge.jar' }\n}\n```\n\nThen: `./gradlew copyBridgeJar`\n\n#### Configure Claude Desktop\n\nChoose one of these three options:\n\n##### Option A: Interactive Installation (Recommended)\n\nRun the installer without arguments for a guided setup:\n\n```bash\njava -jar mcp-java-bridge-1.0.0.jar\n```\n\nThis will:\n- Auto-detect the JAR location\n- Prompt for server name (e.g., \"my-server\")\n- Prompt for host (default: localhost)\n- Prompt for port (default: 3000)\n- Automatically configure Claude Desktop\n- Create a backup of existing configuration\n\n##### Option B: Command Line Installation\n\nFor automated setups, use specific parameters:\n\n```bash\njava -jar mcp-java-bridge-1.0.0.jar install \\\n  -n \"my-server\" \\\n  -c mcp-java-bridge-1.0.0.jar \\\n  -h localhost \\\n  -p 3000\n```\n\n**Parameters:**\n- `-n` - Server name in Claude Desktop (required)\n- `-c` - Path to the JAR that will act as connector\n- `-h` - Server host (default: localhost)\n- `-p` - Server port (default: 3000)\n\n##### Option C: Manual Configuration\n\nIf you prefer to configure manually, edit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"java\",\n      \"args\": [\n        \"-jar\",\n        \"/path/to/mcp-java-bridge-1.0.0.jar\",\n        \"--connector\",\n        \"localhost\",\n        \"3000\"\n      ]\n    }\n  }\n}\n```\n\n### Step 4: Start Your Server\n\n1. Start your MCP server (make sure it's running on the configured port)\n2. Restart Claude Desktop to load the new configuration\n3. Your server should now be available in Claude Desktop\n\n## Additional Resources\n\n### Example Code\n\nThe project includes example code in the source:\n- `SimpleExample.java` - Basic echo server showing minimal setup\n- `ExampleServer.java` - Full-featured server with multiple tools (this is the one built as the demo JAR)\n\n## Build Artifacts\n\nAfter building, you'll find these JARs in `build/libs/`:\n- `mcp-java-bridge-1.0.0-SNAPSHOT.jar` - Main JAR (library + connector + installer)\n- `mcp-java-bridge-1.0.0-SNAPSHOT-example.jar` - Demo server application\n- `mcp-java-bridge-1.0.0-SNAPSHOT-sources.jar` - Source code\n\n## Demo Application\n\nThe demo JAR (`mcp-java-bridge-1.0.0-SNAPSHOT-example.jar`) runs the ExampleServer with these tools:\n- **echo** - Echoes back messages\n- **get_time** - Returns current time in various formats\n- **todo_list** - Manage a simple todo list (add, remove, list, clear)\n- **key_value_store** - Simple key-value storage (get, set, delete, list)\n- **calculator** - Basic math operations (add, subtract, multiply, divide, power, sqrt)\n\n### Running the Demo\n\n1. **Build the project** (if not already built):\n   ```bash\n   ./gradlew clean build\n   ```\n\n2. **Run the demo server**:\n   ```bash\n   # Using the provided script\n   cd examples\n   ./run-demo.sh\n   \n   # Or run directly\n   java -jar build/libs/mcp-java-bridge-1.0.0-SNAPSHOT-example.jar\n   ```\n\n3. **Test with curl** (optional):\n   While the server is designed for MCP clients, you can verify it's running:\n   ```bash\n   # This will fail with a protocol error (expected) but confirms the server is listening\n   telnet localhost 3000\n   ```\n\n4. **Configure Claude Desktop** using the installer (see Step 3 in Getting Started)\n\n### Demo Script\n\nThe `examples/run-demo.sh` script:\n- Checks Java version (requires Java 17+)\n- Builds the project if needed\n- Starts the example server\n- Shows Claude Desktop configuration\n\n## CLI Commands\n\nThe MCP Java Bridge JAR is a multi-purpose tool that serves three different functions:\n\n### 1. Interactive Installer (Default - No Arguments)\n\nRunning without arguments starts an interactive installer:\n\n```bash\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar\n```\n\nThis will:\n- Auto-detect the JAR location\n- Prompt for server name (e.g., \"my-mcp-server\")\n- Prompt for host (default: localhost)\n- Prompt for port (default: 3000)\n- Automatically configure Claude Desktop\n- Create a backup of existing configuration\n\n### 2. Connector Mode\n\nRun as a connector to bridge stdio↔TCP communication. This is what Claude Desktop executes:\n\n```bash\n# With default settings (localhost:3000)\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --connector\n\n# With custom host/port\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --connector 192.168.1.100 8080\n```\n\n**Note**: This mode is typically not run manually - it's executed by Claude Desktop.\n\n### 3. Install Command\n\nFor non-interactive installation with specific parameters:\n\n```bash\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install -n \u003cserver-name\u003e -c \u003cjar-path\u003e [-h \u003chost\u003e] [-p \u003cport\u003e]\n```\n\n**Arguments:**\n- `-n` - Server name in Claude Desktop (required)\n- `-c` - Path to the JAR or script that will act as connector\n- `-h` - Server host (default: localhost)\n- `-p` - Server port (default: 3000)\n\n**Examples:**\n\n```bash\n# Install using the same JAR as connector\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install \\\n  -n \"my-server\" \\\n  -c ./mcp-java-bridge-1.0.0-SNAPSHOT.jar \\\n  -h localhost \\\n  -p 3000\n\n# Install using a custom script as connector (e.g., from uMCP)\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install \\\n  -n \"my-umcp-server\" \\\n  -c /path/to/uMCP/install/bin/uMCP-connector \\\n  -h localhost \\\n  -p 3000\n```\n\n### Help Command\n\nDisplay usage information:\n\n```bash\njava -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --help\n```\n\n### Testing with Claude Desktop\n\nOnce connected, you can test the demo tools:\n\n1. **Echo Tool**:\n   ```\n   \"Please use the echo tool to say 'Hello from MCP!'\"\n   ```\n\n2. **Time Tool**:\n   ```\n   \"What time is it? Show me in different formats.\"\n   ```\n\n3. **Todo List**:\n   ```\n   \"Add 'Test MCP Bridge' to my todo list\"\n   \"Show me my todo list\"\n   \"Remove 'Test MCP Bridge' from the list\"\n   ```\n\n4. **Key-Value Store**:\n   ```\n   \"Store my name as 'John Doe' in the key-value store\"\n   \"What's stored under the key 'name'?\"\n   ```\n\n5. **Calculator**:\n   ```\n   \"Calculate 42 * 17 using the calculator tool\"\n   \"What's the square root of 144?\"\n   ```\n\n## Utilities\n\n### Logging Configuration\n\nThe bridge includes utilities for configuring file-based logging, essential for debugging:\n\n```java\nimport org.gegolabs.mcp.bridge.utils.LoggingUtils;\n\n// Enable file logging\nLoggingUtils.initializeFileLogging(\"my-mcp-server.log\");\n\n// Enable debug logging\nLoggingUtils.enableDebugLogging();\n```\n\nLogs are saved to `~/.mcp-bridge/logs/`.\n\n### JSON Schema Generation\n\nGenerate JSON schemas for your tool parameters:\n\n```java\nimport org.gegolabs.mcp.bridge.utils.JsonSchemaUtils;\n\npublic class MyToolParams {\n    @JsonSchemaUtils.Description(\"The user's name\")\n    private String name;\n    \n    @JsonSchemaUtils.Description(\"The user's age\")\n    private int age;\n}\n\n// Generate schema\nString schema = JsonSchemaUtils.generateJsonSchema(MyToolParams.class);\n```\n\n## Development\n\n### Building from Source\n\n```bash\ngit clone https://github.com/gegolabs/mcp-java-bridge.git\ncd mcp-java-bridge\n./gradlew build\n```\n\n### Running Tests\n\n```bash\n./gradlew test\n```\n\n### Publishing to Local Maven\n\n```bash\n./gradlew publishToMavenLocal\n```\n\n## Requirements\n\n- Java 17 or higher\n- MCP Java SDK 0.10.0 or higher\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.E","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcobach%2Fmcp-java-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcobach%2Fmcp-java-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcobach%2Fmcp-java-bridge/lists"}