MCP Java Bridge
Un puente para el MCP Java SDK que permite soporte de transporte TCP mientras mantiene
Documentación
MCP Java Bridge
Solución de desacoplamiento en tiempo de ejecución para servidores MCP Java, resolviendo los problemas de acoplamiento estricto inherentes a la integración basada en stdio.
El Problema
La implementación nativa de stdio en el SDK de MCP Java crea un acoplamiento estricto entre los tiempos de ejecución del cliente y del servidor. Este acoplamiento causa varios problemas críticos:
- Contención de recursos: El cliente y el servidor compiten por los mismos recursos del sistema
- Conflictos de registro: Ambos procesos escriben en los mismos flujos de salida, dificultando la depuración
- Contaminación del contexto: Las variables de entorno y propiedades del sistema del servidor afectan al cliente
- Gestión del ciclo de vida: El ciclo de vida del servidor está vinculado al proceso del cliente, impidiendo la escalabilidad independiente
- Complejidad de desarrollo: Las pruebas y la depuración requieren ejecutar ambos componentes juntos
La Solución
Aunque HTTP Streamable sería la alternativa ideal para la comunicación desacoplada, el SDK actual de MCP Java solo admite transportes SSE (Server-Sent Events) y stdio, no HTTP Streamable. Esta limitación llevó a la creación de MCP Java Bridge.
MCP Java Bridge desacopla los tiempos de ejecución del cliente y del servidor manteniendo la compatibilidad total con stdio. Introduce un "conector" ligero que:
- Se integra con clientes MCP mediante stdio (100% compatible con Claude Desktop y otros clientes)
- Se conecta a su servidor Java mediante TCP en segundo plano
- Ejecuta cada componente en su propio proceso con recursos aislados
- Requiere cero cambios en el código existente de su servidor MCP
- Es transparente tanto para el cliente como para el desarrollador: simplemente funciona sin configuración adicional
El resultado es una integración robusta y lista para producción que resuelve todos los problemas de acoplamiento manteniendo la simplicidad del protocolo MCP.
Arquitectura
┌─────────────────┐ stdio ┌───────────────────────────────────┐
│ Claude Desktop │ ◄──────────────────► │ MCP Bridge │
│ (Client) │ │ ┌─────────┐ ┌──────────┐ │
└─────────────────┘ │ │ Stub │ TCP │ Skeleton │ │
│ │ (stdio) │◄────►│ (Java) │ │
│ └─────────┘ └──────────┘ │
└───────────────────────────────────┘
│
│ Embedded
▼
┌─────────────────┐
│ MCP Java Server │
│ (with SDK) │
└─────────────────┘
Características
- JAR Todo-en-Uno: Un solo JAR sirve como biblioteca, conector e instalador
- Soporte TCP Transparente: Habilita la conectividad TCP sin modificaciones del cliente
- Integración Simple: Fácil de integrar con servidores MCP Java existentes
- Listo para Producción: Incluye registro, manejo de errores y gestión de conexiones
- Configuración Flexible: Puertos y ajustes de conexión configurables
- Instalador Interactivo: Configuración sin intervención para Claude Desktop
- Autoinstalable: El JAR puede instalarse a sí mismo como conector
Primeros Pasos
Paso 1: Agregar la Dependencia
Agregue mcp-java-bridge a su proyecto:
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: Actualmente es una versión SNAPSHOT. Agregue mavenLocal() a sus repositorios si lo ha instalado localmente.
Paso 2: Crear su Servidor MCP
Use el puente para crear su servidor MCP con transporte TCP:
Opción 1: Usando el Constructor del Puente
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();
}
}
Opción 2: Usando el 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();
}
}
Paso 3: Instalación en Claude Desktop
Después de construir su servidor MCP, debe configurar Claude Desktop para conectarse a él. El JAR de mcp-java-bridge incluye un instalador CLI para este propósito.
Acceder al JAR del Puente
Dado que ha agregado mcp-java-bridge como dependencia, puede acceder a él de dos maneras:
Desde el Repositorio Maven:
java -jar ~/.m2/repository/org/gegolabs/mcp/mcp-java-bridge/1.0.0/mcp-java-bridge-1.0.0.jar
O copiarlo usando una tarea de Gradle:
task copyBridgeJar(type: Copy) {
from configurations.runtimeClasspath.filter { it.name.contains('mcp-java-bridge') }
into 'install'
rename { 'mcp-bridge.jar' }
}
Luego: ./gradlew copyBridgeJar
Configurar Claude Desktop
Elija una de estas tres opciones:
Opción A: Instalación Interactiva (Recomendada)
Ejecute el instalador sin argumentos para una configuración guiada:
java -jar mcp-java-bridge-1.0.0.jar
Esto:
- Detectará automáticamente la ubicación del JAR
- Solicitará el nombre del servidor (por ejemplo, "my-server")
- Solicitará el host (predeterminado: localhost)
- Solicitará el puerto (predeterminado: 3000)
- Configurará automáticamente Claude Desktop
- Creará una copia de seguridad de la configuración existente
Opción B: Instalación por Línea de Comandos
Para configuraciones 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- Nombre del servidor en Claude Desktop (obligatorio)-c- Ruta al JAR que actuará como conector-h- Host del servidor (predeterminado: localhost)-p- Puerto del servidor (predeterminado: 3000)
Opción C: Configuración Manual
Si prefiere 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"
]
}
}
}
Paso 4: Iniciar su Servidor
- Inicie su servidor MCP (asegúrese de que se esté ejecutando en el puerto configurado)
- Reinicie Claude Desktop para cargar la nueva configuración
- Su servidor ahora debería estar disponible en Claude Desktop
Recursos Adicionales
Código de Ejemplo
El proyecto incluye código de ejemplo en el código fuente:
SimpleExample.java- Servidor de eco básico que muestra la configuración mínimaExampleServer.java- Servidor con todas las funciones y múltiples herramientas (este es el que se construye como JAR de demostración)
Artefactos de Compilación
Después de compilar, encontrará estos JAR en build/libs/:
mcp-java-bridge-1.0.0-SNAPSHOT.jar- JAR principal (biblioteca + conector + instalador)mcp-java-bridge-1.0.0-SNAPSHOT-example.jar- Aplicación de servidor de demostraciónmcp-java-bridge-1.0.0-SNAPSHOT-sources.jar- Código fuente
Aplicación de Demostración
El JAR de demostración (mcp-java-bridge-1.0.0-SNAPSHOT-example.jar) ejecuta el ExampleServer con estas herramientas:
- echo - Devuelve mensajes
- get_time - Devuelve la hora actual en varios formatos
- todo_list - Gestiona una lista de tareas simple (agregar, eliminar, listar, limpiar)
- key_value_store - Almacenamiento simple de clave-valor (obtener, establecer, eliminar, listar)
- calculator - Operaciones matemáticas básicas (sumar, restar, multiplicar, dividir, potencia, raíz cuadrada)
Ejecutar la Demostración
-
Compile el proyecto (si aún no está compilado):
./gradlew clean build -
Ejecute el servidor de demostración:
# 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 -
Pruebe con curl (opcional): Aunque el servidor está diseñado para clientes MCP, puede verificar que se está ejecutando:
# This will fail with a protocol error (expected) but confirms the server is listening telnet localhost 3000 -
Configure Claude Desktop usando el instalador (consulte el Paso 3 en Primeros Pasos)
Script de Demostración
El script examples/run-demo.sh:
- Verifica la versión de Java (requiere Java 17+)
- Compila el proyecto si es necesario
- Inicia el servidor de ejemplo
- Muestra la configuración de Claude Desktop
Comandos CLI
El JAR de MCP Java Bridge es una herramienta multipropósito que cumple tres funciones diferentes:
1. Instalador Interactivo (Predeterminado - Sin Argumentos)
Ejecutar sin argumentos inicia un instalador interactivo:
java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar
Esto:
- Detectará automáticamente la ubicación del JAR
- Solicitará el nombre del servidor (por ejemplo, "my-mcp-server")
- Solicitará el host (predeterminado: localhost)
- Solicitará el puerto (predeterminado: 3000)
- Configurará automáticamente Claude Desktop
- Creará una copia de seguridad de la configuración existente
2. Modo Conector
Ejecútelo como conector para puentear la comunicación stdio↔TCP. Esto es lo que ejecuta 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
Nota: Este modo normalmente no se ejecuta manualmente; lo ejecuta Claude Desktop.
3. Comando de Instalación
Para instalación no interactiva con 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- Nombre del servidor en Claude Desktop (obligatorio)-c- Ruta al JAR o script que actuará como conector-h- Host del servidor (predeterminado: localhost)-p- Puerto del servidor (predeterminado: 3000)
Ejemplos:
# 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 Ayuda
Muestra información de uso:
java -jar mcp-java-bridge-1.0.0-SNAPSHOT.jar --help
Pruebas con Claude Desktop
Una vez conectado, puede probar las herramientas de demostración:
-
Herramienta de Eco:
"Please use the echo tool to say 'Hello from MCP!'" -
Herramienta de Hora:
"What time is it? Show me in different formats." -
Lista de Tareas:
"Add 'Test MCP Bridge' to my todo list" "Show me my todo list" "Remove 'Test MCP Bridge' from the list" -
Almacén de Clave-Valor:
"Store my name as 'John Doe' in the key-value store" "What's stored under the key 'name'?" -
Calculadora:
"Calculate 42 * 17 using the calculator tool" "What's the square root of 144?"
Utilidades
Configuración de Registro
El puente incluye utilidades para configurar el registro basado en archivos, esencial para la depuración:
import org.gegolabs.mcp.bridge.utils.LoggingUtils;
// Enable file logging
LoggingUtils.initializeFileLogging("my-mcp-server.log");
// Enable debug logging
LoggingUtils.enableDebugLogging();
Los registros se guardan en ~/.mcp-bridge/logs/.
Generación de Esquemas JSON
Genere esquemas JSON para los parámetros de sus herramientas:
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);
Desarrollo
Compilar desde el Código Fuente
git clone https://github.com/gegolabs/mcp-java-bridge.git
cd mcp-java-bridge
./gradlew build
Ejecutar Pruebas
./gradlew test
Publicar en Maven Local
./gradlew publishToMavenLocal
Requisitos
- Java 17 o superior
- MCP Java SDK 0.10.0 o superior
Licencia
Licencia MIT: consulte el archivo LICENSE para más detalles.
Contribuciones
¡Las contribuciones son bienvenidas! No dude en enviar una Solicitud de Extracción (Pull Request).