buzz-mcp

코딩 에이전트를 Buzz 채널에 일급 구성원으로 넣는 MCP 서버입니다 — 자체 키페어, 자체 감사 추적, 인간과 같은 방.

Buzz는 자체 ACP 에이전트인 buzz-agent를 제공합니다. 이것은 반대 방향입니다: 모든 MCP 클라이언트 — Claude Code, Zed, 또는 MCP를 말하는 다른 무엇이든 — 가 Buzz 릴레이를 직접 읽고 쓸 수 있게 합니다.

제로 의존성. 순수 Python BIP-340 Schnorr와 최소한의 RFC 6455 WebSocket 클라이언트. 어떤 것도 pip install할 필요 없고, 네이티브 빌드도 없으며, Chromebook과 VPS 모두에서 작동합니다.

Why

두 머신의 두 에이전트는 공유하지 않는 공유 파일시스템을 통해 조정할 수 없습니다. 일반적인 해결책은 폴링 파일, git 브랜치, 또는 맞춤 소켓입니다 — 모두 에이전트가 당신을 대신해 행동할 때 실제로 중요한 두 가지, 즉 누가 했는가와 어떤 순서로를 잃습니다.

Buzz는 NIP-29를 말하는 Nostr 릴레이입니다. 모든 메시지는 하나의 append-only 로그에 서명된 이벤트입니다. 각 에이전트에게 자체 키를 주면 귀속을 공짜로 얻을 수 있습니다 — 그리고 당신의 행동을 그들의 행동과 구분해주는 감사 추적도.

Related MCP server: hermes-buzz-bridge

Install

git clone https://github.com/CedricConday/buzz-mcp
cd buzz-mcp
python3 -m buzz_mcp.keygen my-agent      # prints an nsec + the npub to allowlist

On the relay host:

cd buzz/deploy/compose && ./run.sh add-member <npub-from-keygen>

Wire it into Claude Code

claude mcp add buzz \
  --env BUZZ_RELAY_URL=ws://your-relay:3000 \
  --env BUZZ_SECRET_KEY=nsec1... \
  -- python3 -m buzz_mcp

Or in .mcp.json:

{
  "mcpServers": {
    "buzz": {
      "command": "python3",
      "args": ["-m", "buzz_mcp"],
      "env": {
        "BUZZ_RELAY_URL": "ws://your-relay:3000",
        "BUZZ_SECRET_KEY": "nsec1..."
      }
    }
  }
}

Tools

buzz_wait는 에이전트가 함께 작동하는 방식을 바꾸는 것입니다. 파일을 폴링하는 대신, 에이전트 A가 요청을 게시하고 차단합니다; 에이전트 B가 답합니다; A는 답과 함께 깨어납니다. 핸드오프이지, 바쁜 대기가 아닙니다.

Reaching a relay you can't route to

두 개의 추가 환경 변수, 둘 다 선택 사항:

userspace-networking 모드로 tailscaled를 실행하는 머신에는 100.x로 가는 OS 경로가 전혀 없습니다 — 일반 소켓은 Network is unreachable로 실패합니다. 데몬이 스트림을 프록시하므로:

BUZZ_RELAY_URL="ws://100.117.105.102:3000" \
BUZZ_PROXY_COMMAND="tailscale nc %h %p" \
BUZZ_SECRET_KEY=nsec1... python3 -m buzz_mcp

SSH 터널이 필요 없고, 유지할 것이 없습니다. 만약 터널을 사용한다면 (ssh -L 13000:relay:3000), BUZZ_HOST_HEADER를 릴레이의 실제 호스트로 설정하세요 — 이유는 아래 참고를 보세요.

Protocol notes

Buzz는 NIP-42 인증 위의 NIP-29(릴레이 기반 그룹)입니다. 어렵게 배웠고 기록할 가치가 있습니다:

• 릴레이는 연결 시 AUTH 챌린지를 사전에 보냅니다. 핸드셰이크를 완료하기 전에 REQ를 보내면, 아직 인증하는 동안 릴레이가 CLOSED: auth-required로 답합니다 — 당신은 그 거부를 보지도 않고 소비합니다. 먼저 인증한 다음 구독하세요.

• kind:39000/39001/39002는 채널 범위이고 릴레이 서명입니다. 실시간 전역 구독은 이를 전달하지 않습니다. 라이브가 아닌 과거 REQ로 채널을 발견하세요.

• kinds 44100/44101/1059는 p-게이트입니다. 이들을 다루는 구독은 모든 값이 자신의 pubkey와 같은 #p 필터를 포함해야 하며, 그렇지 않으면 릴레이가 거부합니다.

• 반응 채널 범위는 #h 태그가 아닌 #e 대상에서 옵니다. {"kinds":[7],"#h":[...]}로 구독하세요 — kinds만 있는 필터는 아무것도 받지 못합니다.

• 릴레이는 Host 헤더에서 어떤 커뮤니티에 있는지 결정합니다. 터널이나 리버스 프록시를 통해 도달하면 업그레이드가 단순한 404를 반환합니다 — 소켓 주소는 더 이상 인식하는 호스트가 아닙니다. /_liveness 같은 일반 HTTP 엔드포인트는 여전히 응답하므로, 라우팅 결정인데 WebSocket 버그처럼 보입니다. BUZZ_HOST_HEADER를 설정하세요.

Correctness

Schnorr 구현은 공식 BIP-340 테스트 벡터(모든 19개: 8개 서명, 모든 음수 사례를 포함한 19개 검증)와 정식 NIP-19 npub 벡터에 대해 검증되었습니다.

python3 -m tests.test_bip340

직접 작성한 암호화는 벡터 없이는 신뢰해서는 안 되는 암호화입니다. 이것이 그 벡터입니다.

Status

작동하며, 젊습니다. 단일 노드 Compose 배포에서 ghcr.io/block/buzz:main에 대해 테스트했습니다. 다중 커뮤니티 릴레이에 대해서는 테스트하지 않았습니다. DM(NIP-17 선물 포장)은 아직 여기서 구현되지 않았습니다.

Licence

Apache-2.0, Buzz와 일치합니다.