Invok 브리지 (Go)

모든 MCP 호환 IDE 클라이언트와 Invok Spring Boot 백엔드 사이의 브리지 역할을 하는 Go 언어 기반의 경량 MCP(Model Context Protocol) 서버입니다.

이 서버는 JSON-RPC over stdio(MCP 표준)를 Invok API를 위한 일반 HTTP REST 호출로 변환하며, 그 반대의 과정도 수행합니다.

이전의 Node.js/TypeScript 구현은 node, npx, tsx와 같은 런타임 의존성을 사용할 수 없는 제한된 IDE 환경(Antigravity 및 Claude Desktop 등)과의 범용적인 호환성을 위해 이 Go 버전으로 대체되었습니다.

왜 Go인가요?

• 제로 런타임 의존성 — 한 번 컴파일하면 어디서든 실행 가능합니다. Node, npm, PATH 문제로부터 자유롭습니다.

• 단일 바이너리 — 실행 파일 하나로 구성되어 배포가 쉽습니다.

• IDE 독립적 — Antigravity, Claude Desktop, VS Code 및 기타 모든 MCP 클라이언트에서 동일하게 작동합니다.

• 빠른 시작 — JVM 예열이나 패키지 로딩 시간이 없습니다.

사전 요구 사항

• Go 1.21+ — 소스에서 빌드할 때만 필요합니다.

• 실행 중인 Invok 인스턴스 (기본값: http://localhost:8080).

빠른 시작

옵션 A: 사전 컴파일된 바이너리 사용

macOS(darwin/arm64)용 사전 컴파일된 invok-mcp 바이너리가 이 저장소에 포함되어 있습니다. 실행 권한만 부여하면 됩니다:

chmod +x invok-mcp

옵션 B: 소스에서 빌드

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

구성

기본적으로 브리지는 http://localhost:8080에 연결됩니다.

포트나 호스트를 변경하려면 바이너리와 같은 디렉토리에 config.json 파일을 생성하세요:

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

파일이 존재하지 않으면 자동으로 기본값이 사용됩니다.

IDE 통합

Antigravity / Claude Desktop / 모든 MCP 클라이언트

mcp_config.json(Antigravity) 또는 claude_desktop_config.json(Claude Desktop)에 다음 내용을 추가하세요:

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

중요: 바이너리의 절대 경로를 사용하세요. args: ["mcp"] 필드는 일부 IDE 클라이언트에서 서버를 올바르게 등록하기 위해 필요합니다.

작동 원리

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

1. IDE가 invok-mcp를 하위 프로세스로 생성합니다.

2. 브리지가 stdin에서 JSON-RPC 메시지를 한 줄씩 읽습니다.

3. tools/list의 경우, Invok에서 GET /mcp/tools/list를 호출합니다.

4. tools/call의 경우, Invok에서 POST /mcp/tools/call을 호출합니다.

5. 응답은 JSON-RPC 형식으로 stdout에 다시 기록됩니다.

교차 컴파일

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

관련 프로젝트

• Invok — 이 브리지가 연결되는 Spring Boot 백엔드입니다.