MCP Java Bridge

Uma ponte para o MCP Java SDK que permite suporte a transporte TCP, mantendo compatibilidade stdio para clientes.

GitHubExperimente este MCPPatrocinado

Documentação

MCP Java Bridge

Solução de desacoplamento em tempo de execução para servidores MCP Java, resolvendo os problemas de acoplamento rígido inerentes à integração baseada em stdio.

Java 17+ MCP SDK License: MIT

O Problema

A implementação nativa de stdio no SDK MCP Java cria um acoplamento rígido entre os runtimes do cliente e do servidor. Esse acoplamento causa vários problemas críticos:

  • Contenção de recursos: Cliente e servidor competem pelos mesmos recursos do sistema
  • Conflitos de logging: Ambos os processos escrevem nos mesmos fluxos de saída, dificultando a depuração
  • Poluição de contexto: Variáveis de ambiente e propriedades do sistema do servidor afetam o cliente
  • Gerenciamento do ciclo de vida: O ciclo de vida do servidor está vinculado ao processo do cliente, impedindo escalonamento independente
  • Complexidade de desenvolvimento: Testes e depuração exigem executar ambos os componentes juntos

A Solução

Embora o HTTP Streamable fosse a alternativa ideal para comunicação desacoplada, o SDK MCP Java atual só suporta SSE (Server-Sent Events) e transportes stdio — não HTTP Streamable. Essa limitação levou à criação do MCP Java Bridge.

O MCP Java Bridge desacopla os runtimes do cliente e do servidor mantendo total compatibilidade com stdio. Ele introduz um "conector" leve que:

  1. Integra-se com clientes MCP via stdio (100% compatível com Claude Desktop e outros clientes)
  2. Conecta-se ao seu servidor Java via TCP nos bastidores
  3. Executa cada componente em seu próprio processo com recursos isolados
  4. Exige zero alterações no código do seu servidor MCP existente
  5. É transparente para cliente e desenvolvedor — simplesmente funciona

O resultado é uma integração robusta e pronta para produção que resolve todos os problemas de acoplamento, mantendo a simplicidade do protocolo MCP.

Arquitetura

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

Recursos

  • JAR Tudo-em-Um: Um único JAR serve como biblioteca, conector e instalador
  • Suporte TCP Transparente: Habilita conectividade TCP sem modificações no cliente
  • Integração Simples: Fácil de integrar com servidores MCP Java existentes
  • Pronto para Produção: Inclui logging, tratamento de erros e gerenciamento de conexões
  • Configuração Flexível: Portas e configurações de conexão configuráveis
  • Instalador Interativo: Configuração sem intervenção para Claude Desktop
  • Autoinstalável: O JAR pode se instalar como conector

Começando

Passo 1: Adicionar Dependência

Adicione mcp-java-bridge ao seu projeto:

Maven

<dependency>
    <groupId>org.gegolabs.mcp</groupId>
    <artifactId>mcp-java-bridge</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Gradle

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

Nota: Esta é atualmente uma versão SNAPSHOT. Adicione mavenLocal() aos seus repositórios se você o instalou localmente.

Passo 2: Criar Seu Servidor MCP

Use o bridge para criar seu servidor MCP com transporte TCP:

Opção 1: Usando o Bridge Builder

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();
    }
}

Opção 2: Usando Método de Fábrica Estático

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();
    }
}

Passo 3: Instalação no Claude Desktop

Após construir seu servidor MCP, você precisa configurar o Claude Desktop para conectar-se a ele. O JAR mcp-java-bridge inclui um instalador CLI para esse fim.

Acessar o JAR do Bridge

Como você adicionou mcp-java-bridge como dependência, pode acessá-lo de duas maneiras:

Do Repositório Maven:

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

Ou copie-o usando uma tarefa Gradle:

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

Então: ./gradlew copyBridgeJar

Configurar o Claude Desktop

Escolha uma destas três opções:

Opção A: Instalação Interativa (Recomendada)

Execute o instalador sem argumentos para uma configuração guiada:

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

Isso irá:

  • Detectar automaticamente a localização do JAR
  • Solicitar o nome do servidor (ex.: "my-server")
  • Solicitar o host (padrão: localhost)
  • Solicitar a porta (padrão: 3000)
  • Configurar automaticamente o Claude Desktop
  • Criar um backup da configuração existente
Opção B: Instalação via Linha de Comando

Para configurações automatizadas, use parâmetros específicos:

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

Parâmetros:

  • -n - Nome do servidor no Claude Desktop (obrigatório)
  • -c - Caminho para o JAR que atuará como conector
  • -h - Host do servidor (padrão: localhost)
  • -p - Porta do servidor (padrão: 3000)
Opção C: Configuração Manual

Se preferir configurar manualmente, edite ~/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"
      ]
    }
  }
}

Passo 4: Iniciar Seu Servidor

  1. Inicie seu servidor MCP (certifique-se de que está rodando na porta configurada)
  2. Reinicie o Claude Desktop para carregar a nova configuração
  3. Seu servidor agora deve estar disponível no Claude Desktop

Recursos Adicionais

Código de Exemplo

O projeto inclui código de exemplo no código-fonte:

  • SimpleExample.java - Servidor echo básico mostrando configuração mínima
  • ExampleServer.java - Servidor completo com múltiplas ferramentas (este é o que é compilado como JAR de demonstração)

Artefatos de Build

Após a compilação, você encontrará estes JARs em build/libs/:

  • mcp-java-bridge-1.0.0-SNAPSHOT.jar - JAR principal (biblioteca + conector + instalador)
  • mcp-java-bridge-1.0.0-SNAPSHOT-example.jar - Aplicação de servidor de demonstração
  • mcp-java-bridge-1.0.0-SNAPSHOT-sources.jar - Código-fonte

Aplicação de Demonstração

O JAR de demonstração (mcp-java-bridge-1.0.0-SNAPSHOT-example.jar) executa o ExampleServer com estas ferramentas:

  • echo - Retorna mensagens de volta
  • get_time - Retorna a hora atual em vários formatos
  • todo_list - Gerencia uma lista de tarefas simples (adicionar, remover, listar, limpar)
  • key_value_store - Armazenamento simples de chave-valor (get, set, delete, list)
  • calculator - Operações matemáticas básicas (soma, subtração, multiplicação, divisão, potência, raiz quadrada)

Executando a Demonstração

  1. Compile o projeto (se ainda não compilado):

    ./gradlew clean build

  2. Execute o servidor de demonstração:

    # 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

  3. Teste com curl (opcional): Embora o servidor seja projetado para clientes MCP, você pode verificar se está rodando:

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

  4. Configure o Claude Desktop usando o instalador (veja o Passo 3 em Começando)

Script de Demonstração

O script examples/run-demo.sh:

  • Verifica a versão do Java (requer Java 17+)
  • Compila o projeto se necessário
  • Inicia o servidor de exemplo
  • Mostra a configuração do Claude Desktop

Comandos CLI

O JAR do MCP Java Bridge é uma ferramenta multiuso que serve três funções diferentes:

1. Instalador Interativo (Padrão - Sem Argumentos)

Executar sem argumentos inicia um instalador interativo:

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

Isso irá:

  • Detectar automaticamente a localização do JAR
  • Solicitar o nome do servidor (ex.: "my-mcp-server")
  • Solicitar o host (padrão: localhost)
  • Solicitar a porta (padrão: 3000)
  • Configurar automaticamente o Claude Desktop
  • Criar um backup da configuração existente

2. Modo Conector

Execute como conector para fazer a ponte de comunicação stdio↔TCP. É isso que o Claude Desktop executa:

# 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

Nota: Este modo normalmente não é executado manualmente — é executado pelo Claude Desktop.

3. Comando de Instalação

Para instalação não interativa com parâmetros específicos:

java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar install -n <server-name> -c <jar-path> [-h <host>] [-p <port>]

Argumentos:

  • -n - Nome do servidor no Claude Desktop (obrigatório)
  • -c - Caminho para o JAR ou script que atuará como conector
  • -h - Host do servidor (padrão: localhost)
  • -p - Porta do servidor (padrão: 3000)

Exemplos:

# 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

Comando de Ajuda

Exibe informações de uso:

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

Testando com Claude Desktop

Uma vez conectado, você pode testar as ferramentas de demonstração:

  1. Ferramenta Echo:

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

  2. Ferramenta de Hora:

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

  3. Lista de Tarefas:

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

  4. Armazenamento Chave-Valor:

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

  5. Calculadora:

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

Utilitários

Configuração de Logging

O bridge inclui utilitários para configurar logging baseado em arquivo, essencial para depuração:

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

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

// Enable debug logging
LoggingUtils.enableDebugLogging();

Os logs são salvos em ~/.mcp-bridge/logs/.

Geração de Schema JSON

Gere schemas JSON para os parâmetros das suas ferramentas:

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);

Desenvolvimento

Compilando a partir do Código-Fonte

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

Executando Testes

./gradlew test

Publicando no Maven Local

./gradlew publishToMavenLocal

Requisitos

  • Java 17 ou superior
  • MCP Java SDK 0.10.0 ou superior

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.