Invok Bridge (Go)

Un servidor MCP (Model Context Protocol) ligero escrito en Go que actúa como puente entre cualquier cliente IDE compatible con MCP y el backend de Spring Boot Invok.

Traduce JSON-RPC sobre stdio (el estándar MCP) a llamadas HTTP REST simples a la API de Invok, y viceversa.

La implementación anterior en Node.js/TypeScript ha sido obsoleta en favor de esta versión en Go debido a su compatibilidad universal con entornos de IDE restringidos (como Antigravity y Claude Desktop) donde las dependencias de tiempo de ejecución como node, npx o tsx a menudo no están disponibles.

¿Por qué Go?

• Cero dependencias de tiempo de ejecución — compila una vez, ejecuta en cualquier lugar. Sin Node, sin npm, sin problemas de PATH.

• Binario único — un archivo ejecutable, fácil de distribuir.

• Agnóstico al IDE — funciona de forma idéntica en Antigravity, Claude Desktop, VS Code y cualquier otro cliente MCP.

• Inicio rápido — sin calentamiento de JVM, sin carga de paquetes.

Requisitos previos

• Go 1.21+ — solo necesario para compilar desde el código fuente.

• Una instancia en ejecución de Invok (predeterminado: http://localhost:8080).

Inicio rápido

Opción A: Usar el binario precompilado

Se incluye un binario invok-mcp precompilado para macOS (darwin/arm64) en este repositorio. Solo hazlo ejecutable:

chmod +x invok-mcp

Opción B: Compilar desde el código fuente

git clone https://github.com/Vrivaans/handsai-bridge.git
cd handsai-bridge
go build -o invok-mcp main.go

Configuración

De forma predeterminada, el puente se conecta a http://localhost:8080.

Para cambiar el puerto o el host, crea un archivo config.json en el mismo directorio que el binario:

{
  "handsaiUrl": "http://localhost:9090"
}

Si el archivo no existe, se utiliza el valor predeterminado automáticamente.

Integración con IDE

Antigravity / Claude Desktop / Cualquier cliente MCP

Añade lo siguiente a tu mcp_config.json (Antigravity) o claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "invok": {
      "command": "/absolute/path/to/invok-mcp",
      "args": ["mcp"]
    }
  }
}

Importante: Usa la ruta absoluta al binario. El campo args: ["mcp"] es requerido por algunos clientes IDE para registrar correctamente el servidor.

Cómo funciona

IDE (MCP Client)  →  stdio JSON-RPC  →  invok-mcp (Go)  →  HTTP  →  Invok (Spring Boot)

1. El IDE inicia invok-mcp como un subproceso.

2. El puente lee los mensajes JSON-RPC desde stdin línea por línea.

3. Para tools/list, llama a GET /mcp/tools/list en Invok.

4. Para tools/call, llama a POST /mcp/tools/call en Invok.

5. Las respuestas se escriben de vuelta a stdout como JSON-RPC.

Compilación cruzada

Compila para otras plataformas desde macOS:

# Linux (amd64)
GOOS=linux GOARCH=amd64 go build -o invok-mcp-linux main.go

# Windows
GOOS=windows GOARCH=amd64 go build -o invok-mcp.exe main.go

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o invok-mcp-intel main.go

Proyectos relacionados

• Invok — El backend de Spring Boot al que se conecta este puente.