mcp-a2a-bridge

코딩 에이전트(GitHub Copilot CLI, Claude Code, Codex, Hermes)가 원격 A2A 에이전트를 호출할 수 있게 해주는 MCP 서버입니다. 또한 선적 읽기 전용 활동 대시보드를 포합합니다.

저장소: httpps://github.com/TonPC64/mcp-a2a-bridge

MIT 라이선스에 따라 사용이 허가됩니다.

코딩 에이전트 지침은 AGENTS.md부터 시작하고, 설치에는 skills/setup/SKILL.md를, 변경 사항 및 R에는 skills/contribute/SKILL.md를 사용하세요.

대시보드 UI 케이스

선적 대시보드는 컴팩트한 에이전트 카드, 실시간 작업 활동, 2열 작업 요약, 상태 표시기, 반응형 레이아웃을 갖춘 미래지향적 Liqud Glaas 인터페이스를 사용합니다. 이 스크린숏은 옵트인 프론트엔드 목 데이터 모드를 사용하므로 실제 에이전트에 연결하거나 로그를 노출하지 않고 재현해도 안전합니다.

동일한 목 UI를 로컬에서 실해하려면:

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 127.0.0.1

목 모드는 UI 개발 및 스크린숏 전용입니다. 일반 빌드는 라이브 대시보드 API와 SSE를 사용합니다.

Related MCP server: agntcy-mcp-server

시자하기

설정 선택

두 프롤일 모두 Python 3.11 이상과 uv가 필요합니다. 선적 대시보드 프론트엔드는 Node.js 24.15 이상이 필요하며, CI는 최신 Node.js 24 릴리스를 사용합니다.

MCP만

MCP 브리지만 설치하고 실합니다. 여기에는 Node.js/npm이나 대시보드 프론트엔드 빌드가 필요하지 않습니다.

git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --locked

MCP + 대시보드

선적 대시보드 웹 런타임을 설치한 다윔 번들된 프론트엔드 에셋을 빌드하세요. Node.js와 npm은 이 빌드(또는 프론트엔드 개발)에만 필요하며, 이미 빌드된 대시보드를 실하는 데는 필요하지 않습니다.

git clone https://github.com/TonPC64/mcp-a2a-bridge.git mcp-a2a-bridge
cd mcp-a2a-bridge
uv sync --extra dashboard --locked
npm --prefix dashboard ci
npm --prefix dashboard run build

개발 및 테스트에는 uv sync --all-extras --locked를 사용하세요. 여기에는 대시보드 테스트 스위트에 필요란 Python 패키지가 포합됩니다. 아래 명령은 /absolute/path/to/mcp-a2a-bridge를 사용합니다. 이를 자신의 클론의 절대 경로로 바꾸세요. 다른 사용자의 경로를 복사하지 마세요.

A2A 에이전트 구서

저장소 트에 .a2a-agents.json을 생합니다:

{
  "agents": {
    "example-agent": {
      "url": "https://agent.example.invalid",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_TOKEN"
      }
    }
  }
}

A2A 에이전트의 기본 URL을 사용하세요. 브리지는 해당 에이전트의 /.well-known/agent-card.json을 자동으로 요청합니다. 에이전트가 인증을 요구하지 않는 경우 Authorization을 제거하거나(또는 빈 headers 객체를 사용)하세요. 레지스트리는 비밀을 포할 수 있으므로 커밋하지 말고, 적절한 경우 파일 권한을 제한하세요.

레지스트리 위치는 다윔 순서로 확입니다:

1. A2A_BRIDGE_CONFIG

2. 브리지 프로세스의 현재 디렉터리에 있른 .a2a-agents.json

3. ~/.config/a2a-bridge/agents.json

저장소 외부에서 MCP 명령을 시자하는 호스트의 경우 해당 호스트의 MCP 환경에서 A2A_BRIDGE_CONFIG를 절대 경로로 설정하세요. 런타임에 a2a_add_agent로 검증된 에이전트를 추가할 수도 있습니다. 기본적으로 확인된 레지스트리 파일에 기록됩니다.

MCP 서버 등록

각 호스트는 동일한 로컬 체크아웃 명령을 시작해야 합니다:

uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

위에서 만든 editable 설치를 사용합니다. 다음 휴대용 경로 자리 표시자로 호스트를 구성하세요.

GitHub Copilot CLI — 이 서버를 ~/.copilot/mcp-config.json에 추가합니다:

{
  "mcpServers": {
    "a2a": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-a2a-bridge",
        "mcp-a2a-bridge"
      ]
    }
  }
}

Claude Code:

claude mcp add a2a -- uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

Codex — 이것을 ~/.codex/config.toml에 추가합니다:

[mcp_servers.a2a]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/mcp-a2a-bridge", "mcp-a2a-bridge"]

Hermes: MCP 서버 등록 UI 또는 명령을 사용하고 stdio 서버를 선택한 다음 uv 명령에 다음 인수를 제공합니다:

run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

등록 후 호스트를 다시 시자한 다윔 a2a_lis_agents를 호출하여 레지스트리를 사용할 수 있고 에이전트에 연결할 수 있는지 확인하세요.

도구

a2a_send_message는 timeout_s(기본값 60초)까지 대기합니다. 작업이 아직 실행 중이면 task_id와 함께 done: false를 반환하며, a2a_get_task로 폴링하세요. 에이전트가 state: "input_required"를 반환하면 동일한 task_id로 a2a_send_message를 다시 호출하세요.

대시보드

선택적 독립형 대시보드는 구성된 에이전트, 해당 상태/스킬, 그리고 같은 머신의 브리지 프로세스에서 발생하는 실시간 작업 활동을 표시합니다. 읽기 전용이며 에이전트에 메시지를 보내지 않습니다.

시작하기 전에 dashboard 프로필을 설치하고 에셋을 빌드하세요:

cd /absolute/path/to/mcp-a2a-bridge
uv sync --extra dashboard --locked
npm --prefix dashboard ci
npm --prefix dashboard run build
uv run mcp-a2a-bridge-dashboard

기본적으로 127.0.0.1:9100에서만 수신합니다. 같은 머신에서 http://127.0.0.1:9100을 여세요.

프론트엔드 목 데이터

Python 서비스나 SSE 없이 대시보드 UI를 실행하려면 옵트인 목 모드를 사용하세요. 스크린샷용 대표 에이전트와 작업 활동이 포함됩니다:

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev:mock -- --host 0.0.0.0

같은 네트워크에서 Vite URL을 여세요. VITE_USE_MOCK_DATA=true는 프론트엔드 빌드/개발 서버에서만 사용됩니다. 일반 npm run dev 및 프로덕션 빌드는 계속 라이브 대시보드 API와 SSE를 사용합니다.

활동이 대시보드에 표시되어야 하는 모든 브리지 프로세스에 대해 보고를 활성화하세요. 이 환경 변수를 MCP 서버 구성에 추가하세요(또는 수동으로 시작할 때):

A2A_BRIDGE_DASHBOARD=1 uv run --directory /absolute/path/to/mcp-a2a-bridge mcp-a2a-bridge

해당 플래그가 없는 브리지 프로세스는 활동을 메모리에만 보관하며 공유 대시보드에 표시되지 않습니다. 대시보드는 이들보다 먼저 또는 나중에 시작할 수 있습니다.

LAN 배포

명시적 비루프백(non-loopback) 바인드를 설정하면 신뢰할 수 있는 LAN에서 토큰 없이 대시보드를 의도적으로 노출할 수 있습니다. 이 모드에는 인증이 없으므로 사설의 신뢰할 수 있는 네트워크에서만 사용하고 공개 인터넷에는 절대 노출하지 마세요.

보호된 LAN 액세스의 경우 강력한 토큰을 설정하고 자체 네트워크 액세스 제어 기능을 갖춘 TLS 종료 리버스 프록시 뒤에 서비스를 배치하세요:

export A2A_BRIDGE_DASHBOARD_HOST=0.0.0.0
export A2A_BRIDGE_DASHBOARD_TOKEN="$(openssl rand -hex 32)"
uv run mcp-a2a-bridge-dashboard

토큰이 설정되면 대시보드 HTML, 정적 에셋, API 라우트, SSE 라우트 모두 토큰이 필요합니다. 브라우저 사용자는 /login에서 한 번 입력합니다. 이렇게 생성된 HttpOnly, same-site 세션 쿠키 덕분에 EventSource가 정상적으로 다시 연결됩니다. API 클라이언트는 대신 Authorization: Bearer <token>을 보낼 수 있습니다. 서비스는 토큰을 절대 로그에 기록하지 않습니다. 토큰은 액세스를 인증하지만 트래픽을 암호화하지 않으므로 신뢰할 수 없는 네트워크에서는 직접 HTTP LAN 엔드포인트를 사용하지 말고 리버스 프록시에서 HTTPS를 사용하세요.

macOS의 경우 launchd/com.example.a2a-bridge-dashboard.plist 템플릿이 로그인 시 대시보드를 실행할 수 있습니다. LaunchAgent로 설치하기 전에 __REPO__ 및 __HOME__ 자리 표시자를 바꾸세요.

대시보드 프론트엔드 개발

Node.js 24.15+와 npm은 프론트엔드 작업 또는 번들 에셋 재빌드에만 필요합니다:

cd /absolute/path/to/mcp-a2a-bridge/dashboard
npm ci
npm run dev

Vite가 개발 URL(보통 http://localhost:5173)을 출력합니다. npm run build로 Python 대시보드가 사용하는 에셋을 빌드하세요.

Copilot A2A 서버

번들 서버에는 인증된 copilot CLI가 필요합니다:

copilot-a2a-agent --port 9002 --cwd /path/to/default/repository

--allow-all-tools로 Copilot을 실행하므로 127.0.0.1에 바인딩됩니다. 수신 활동은 동일한 옵트인 공유 SQLite 저장소를 사용할 수 있으며 대시보드에서 소스 및 대상 필드와 함께 표시됩니다.

대시보드는 Hermes를 수정하지 않고도 Hermes의 네이티브 감사 파일을 읽을 수 있습니다. A2A_BRIDGE_HERMES_AUDIT, 그다음 $HERMES_HOME/a2a_audit.jsonl, 그다음 ~/.hermes/a2a_audit.jsonl 순서로 확인합니다.

개발 및 테스트

저장소 루트에서 Python 테스트 스위트를 실행하세요:

uv sync --all-extras --locked
uv run pytest -v

dashboard/에서 대시보드 테스트를 실행하거나 프로덕션 대시보드 빌드를 만드세요:

npm test
npm run build

CI는 Python 3.11에서 Python 스위트를 실행하고, uv.lock을 검증하며, 최신 Node.js 24 릴리스에서 대시보드 설치, 테스트, 프로덕션 빌드를 실행합니다.

tests/test_integration.py는 프로세스 내에서 A2A 에이전트를 실행하고 브리지를 엔드투엔드로 테스트합니다.