@partyvelope/synapse-mcp

synapse — AI 에이전트 팀의 공유 기억·조율 허브 — 의 MCP 클라이언트입니다.

여러 사람이 각자 Claude Code(또는 다른 MCP 하네스)로 한 프로젝트를 개발할 때, 에이전트들이 결정·컴포넌트·태스크를 하나의 그래프에 기록하고, 서로의 작업을 침범하지 않게 하는 조율 규칙을 강제합니다:

• 🧠 결정 기록 — "왜 이렇게 했는가"가 세션이 끝나도 남고, 다음 에이전트가 같은 결정을 다시 논쟁하지 않습니다. 비슷한 결정은 허브가 중복으로 거부합니다.
• 🔒 작업 클레임 — 코드를 쓰기 전에 무엇을 만질지 선언합니다. 겹치면 누가 언제부터 잡고 있는지 알려주고 두 번째 초안 작성을 막습니다.
• 📬 미읽음 가드 — 나에게 온 미읽음 메시지를 둔 채 그 상대에게 발신하면 거부됩니다. 어긋난 대화("v2 제안" ↔ "v1 확정")가 구조적으로 안 생깁니다.
• 🗺 코드 그래프 내장 — 리포를 파싱해(Java/Spring, TS/JS/React, NestJS, Python/FastAPI, Vue) 컴포넌트·메서드·엔드포인트·호출/DI 엣지를 올립니다. "이 API는 어디서 처리되나"가 검색이 아니라 한 홉입니다.
• 👀 실시간 웹 뷰어 — 사람이 팀의 그래프·결정 히스토리를 브라우저로 봅니다.

빠른 시작 (팀원, 1분)

서버 주소·본인 handle만 있으면 됩니다. Python도, DB도, 다른 설치도 없습니다 — 파서(tree-sitter WASM)까지 이 패키지 하나에 들어 있습니다.

npx -y @partyvelope/synapse-mcp init

마법사가 차례로:

synapse 설치 마법사 (v0.3.0) — Ctrl+C로 언제든 중단

허브 서버 주소 [http://localhost:4000]: https://hub.example.com
  ✓ 연결됨 (허브 v0.3.0)          ← 주소를 받는 즉시 검증합니다. 틀린 주소로
                                     등록을 마치는 사고가 여기서 끊깁니다.
  접근 토큰: ****                  ← 허브가 토큰 게이트를 켠 경우에만 묻습니다.
  기존 프로젝트: shop, admin       ← 오타로 새 프로젝트를 만드는 사고 방지.
프로젝트 키: shop
내 handle (팀원이 @로 부를 이름): yj
역할 (design|frontend|backend|infra|review|pm): backend
등록 방식 — 1) 이 폴더 .mcp.json에 쓰기  2) claude mcp add 명령 출력: 1

✓ .mcp.json 에 등록했습니다. Claude Code를 이 폴더에서 다시 열면 잡힙니다.

이 폴더의 코드 그래프를 지금 인덱싱해서 올릴까요? (y): y
parsed 239 files -> 416 components, 841 methods, 65 endpoints, 2178 edges
ingested: 1322 nodes upserted, ...

끝입니다. .mcp.json을 리포에 커밋하면 다음 팀원은 --agent만 바꾸면 되고, 설치가 끝난 순간 팀 그래프에 내 리포가 이미 들어가 있습니다.

비대화형(스크립트)으로는:

npx -y @partyvelope/synapse-mcp init --url https://hub.example.com --project shop \
  --agent yj --role backend --mode 1 --index y

코드 인덱싱

설치 때 한 번 올렸다면, 이후 갱신은 한 줄입니다 (init 한 폴더에서는 주소·토큰· 프로젝트를 .mcp.json에서 자동으로 읽습니다):

npx -y @partyvelope/synapse-mcp index .

⚠️ 프로젝트가 리포 여럿(프론트/백엔드 분리)이면 루트를 전부 한 명령에 넘기세요: index ../front ../back. 전체 스윕(mode=full) 인덱싱이라 하나만 올리면 다른 리포의 노드가 쓸려 나갑니다.

인덱싱은 머지된 main에서 권장 — 그래프는 팀의 공유 사실이지 작업 중인 브랜치의 추측이 아니어야 합니다.

허브 없이 결과만 보려면 dump . -o graph.json. 에이전트에게는 같은 기능이 index_code MCP 툴로 노출돼 있어 "인덱스 갱신해줘" 한마디면 됩니다.

웹 뷰어

https://<허브>/?project=<키> — 사람이 보는 화면입니다. 그래프는 실시간으로 갱신되고, 노드를 클릭하면 기록된 의도가 열립니다.

결정 히스토리 탭은 팀의 모든 결정을 버전째 보여줍니다 — 뒤집힌 결정은 어떤 결정이 대체했는지까지:

에이전트에게 주어지는 도구 (18개)

| 분류 | 툴 | 하는 일 | |---|---|---| | 기록 | log_decision register_component open_task update_task report_issue resolve_issue | 결정·컴포넌트 의도·태스크·이슈를 그래프에. 중복 결정은 허브가 거부 | | 조율 | claim release_claim list_claims check_conflicts | 작업 선점과 충돌 예측 — 코드가 생기기 전에 겹침을 알림 | | 대화 | send_message inbox read_thread | @handle 멘션 전달, 미읽음 가드, long-poll 대기 | | 회상 | get_context_for_role search_memory why whats_blocking | 세션 시작 컨텍스트, 의미 검색, "왜 이렇게 돼 있나", 막힌 것 | | 코드 | index_code | 리포 파싱 → 코드 그래프 업로드 |

모든 응답에는 미읽음 알림(📬)과 지금 진행 중인 남의 작업(🔨)이 함께 실립니다 — 에이전트가 물어볼 생각을 못 해도 알게 됩니다.

API 계약은 허브가 스스로 설명합니다: GET /api/<프로젝트>/schema — 검증에 쓰는 스키마에서 그대로 생성되므로 낡을 수 없습니다.

진단

npx -y @partyvelope/synapse-mcp doctor --url https://hub.example.com

서버 도달 → 토큰 검증 → 클라이언트/허브 버전 악수 → API 확인을 차례로 점검합니다. 실패 메시지는 스택트레이스가 아니라 다음 행동입니다.

서버 (팀당 1대, 10분)

docker만 있으면 됩니다 — PostgreSQL·임베딩 모델까지 compose에 포함돼 있어 DB를 따로 설치할 일이 없습니다:

git clone https://github.com/PartyVelope/partyvelope-synapse-mcp
cd partyvelope-synapse-mcp
docker compose --profile server up -d --build

공인망에 열려면 .env에 HUB_TOKENS=<랜덤 문자열>을 넣으세요(쉼표로 여러 개 = 로테이션). 토큰을 팀원에게 나눠 주면 init이 알아서 묻고 검증합니다.

설정값

| 플래그 | 환경변수 | 뜻 | |---|---|---| | --url | HUB_URL | 허브 주소 (기본 http://localhost:4000) | | --project | HUB_PROJECT | 프로젝트 키 (첫 기록 때 자동 생성) | | --agent | HUB_AGENT_NAME | 본인 handle — 인증이 없는 신뢰망 도구라 이 이름이 곧 신원입니다 | | --role | HUB_AGENT_ROLE | design｜frontend｜backend｜infra｜review｜pm | | --token | HUB_TOKEN | 접근 토큰 — 허브가 HUB_TOKENS로 게이트를 켠 경우에만 필요 |

자주 묻는 것

npx 말고 전역 설치는? npm i -g @partyvelope/synapse-mcp 후 synapse-mcp init — 세션 기동이 빨라지고 오프라인에서도 돕니다. 업데이트는 npm update -g.

프론트/백엔드 동시 작업인데 역할은? 역할은 컨텍스트 필터일 뿐 권한이 아닙니다. 주 역할로 등록하고 필요한 쪽 작업을 그냥 하면 됩니다.

허브와 클라이언트 버전이 어긋나면? doctor가 악수에서 잡아 줍니다. 어긋난 채 겪는 실패는 재현이 안 되는 모양으로 나타나니, 이상하면 이것부터.

⚠️ 허브를 공인망에 열 때는 서버 쪽 HUB_TOKENS를 반드시 설정하세요. 토큰 게이트가 없는 허브는 신뢰된 팀 네트워크 전용입니다.