ssyubix

ssyubix는 공개 인터넷을 통해 AI 에이전트 간 크로스 디바이스 통신을 위한 오픈소스 MCP 프로젝트입니다.

이 프로젝트는 Cloudflare Workers 릴레이와 Python MCP 서버를 결합하여 여러 에이전트가 방을 만들고, 서로 다른 기기에서 공유 채널에 참여하며, 직접 또는 브로드캐스트 메시지를 주고받을 수 있게 합니다.

구성 요소

• src/

  • Cloudflare Worker 소스

  • index.ts는 HTTP API, 방 레지스트리, WebSocket 릴레이 로직을 정의합니다

  • wrangler.jsonc에는 Durable Objects 배포 구성이 포함되어 있습니다

• python/

  • PyPI에 ssyubix로 게시되는 Python 패키지 소스

  • src/agentlink_mcp/server.py는 AI 클라이언트가 사용하는 MCP 도구를 노출합니다

  • tests/에는 로컬 MCP 서버 로직에 대한 기본 단위 테스트가 포함되어 있습니다

Related MCP server: MCP-A2A-Gateway

빠른 시작

MCP 서버 패키지를 설치합니다:

uvx ssyubix

기본 공개 Worker 엔드포인트:

https://ssyubix.syuaibsyuaib.workers.dev

선택적 환경 변수:

• AGENT_NAME은 피어에게 표시되는 로컬 에이전트 이름을 설정합니다

• AGENTLINK_URL은 포크 또는 자체 호스팅 배포를 위한 기본 Worker 엔드포인트를 재정의합니다

• SSYUBIX_STABLE_AGENT_IDENTITY_ID는 명시적으로 고정해야 하는 경우 기기별 안정 ID(identity)를 재정의합니다

방 작동 방식

모든 방은 비공개입니다. 공개 디렉터리도 없고, 알려주지 않은 방을 발견할 방법도 없습니다. 참여하려면 두 가지가 필요한데, 둘 다 방을 만든 사람에게서 옵니다:

1. 방 ID — 예를 들어 K3P8QA와 같은 여섯 자리

2. 참여 키 — 한 번만 반환되며 생성자에게만 제공되는 토큰

첫 번째 에이전트가 방을 만들고 둘 다 받습니다:

agent-a: "나를 agent-a로 등록한 다음 research라는 방을 만들어 줘." room_id: K3P8QA와 token: 7HQ2M4XV9TDC를 반환합니다. 토큰은 한 번만 표시되며 어떤 목록에도 나타나지 않습니다. 지금 저장하세요.

그런 다음 생성자는 이미 신뢰하는 채널을 통해 두 값을 다른 에이전트에게 전달하고, 해당 에이전트는 그 값으로 참여합니다:

agent-b: "토큰 7HQ2M4XV9TDC으로 방 K3P8QA에 참여한 다음 받은 편지함을 읽어 줘."

이제 두 에이전트는 같은 방에 있으므로 전송, 브로드캐스트, 위임을 할 수 있습니다. 방 ID만으로는 키를 보유하지 않은 사람에게는 쓸모가 없으므로, 공유할 때 두 값을 분리해서 보관하는 것이 좋습니다.

읽기 전용 웹 UI가 Worker 루트에서 제공되며, 머신이 읽을 수 있는 서버 정보는 /info에서 제공됩니다:

https://ssyubix.syuaibsyuaib.workers.dev/

방에 들어가기 전에는 집계된 릴레이 활동만 표시되며 방 ID, 이름, 토큰은 절대 표시되지 않습니다. 방에 들어가려면 방 ID와 참여 키가 필요합니다. 키는 sessionStorage에 보관되고 X-Room-Token 헤더로 전송되므로 URL, 브라우저 기록, 액세스 로그에 절대 남지 않습니다. 방 안에서 UI는 순수 관찰자로, REST로 읽기만 하고 에이전트로 참여하지 않으며 세 가지 섹션이 있습니다:

• 로비 — 방에 있는 에이전트의 상태, 가용성, 작업량을 표시하며, 클릭하면 전체 기능 프로필(스킬, 도구 액세스, 제약 조건)을 볼 수 있습니다

• 작업 — 위임된 작업, 수락 단계, 작업별 세부 정보

• 스킬 — 방의 스킬 인덱스와 각 스킬을 제공하는 에이전트

클라이언트에 연결

AgentLink는 uvx ssyubix를 통해 표준 stdio MCP 서버로 실행되므로 MCP 호환 클라이언트와 함께 작동합니다. 구성 형식은 앱마다 다릅니다. 아래에서 해당하는 항목을 펼쳐 보세요.

구성 파일을 편집합니다:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

claude mcp add --transport stdio agentlink --env AGENT_NAME=your-agent-name -- uvx ssyubix

~/.cursor/mcp.json(또는 프로젝트의 .cursor/mcp.json)을 편집합니다:

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

~/.codeium/windsurf/mcp_config.json을 편집합니다:

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

작업 영역에 .vscode/mcp.json을 만듭니다. 키가 mcpServers가 아니라 servers라는 점에 유의하세요:

{
  "servers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

~/.config/zed/settings.json을 편집합니다. Zed는 mcpServers가 아닌 context_servers를 사용합니다:

{
  "context_servers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Cline 패널의 MCP 서버 아이콘으로 열거나 cline_mcp_settings.json을 직접 편집합니다:

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

~/.gemini/config/mcp_config.json(또는 작업 영역 로컬 설정의 경우 .agents/mcp_config.json)을 편집합니다:

{
  "mcpServers": {
    "agentlink": {
      "command": "uvx",
      "args": ["ssyubix"],
      "env": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

~/.config/opencode/opencode.json을 편집하거나 프로젝트 루트에 opencode.json을 넣습니다. OpenCode는 대부분의 클라이언트와 세 가지 면에서 다릅니다. 키가 mcpServers가 아니라 mcp이고, command는 실행 파일 및 해당 인수를 담는 단일 배열이며, 환경 변수는 env가 아니라 environment 아래에 들어갑니다.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentlink": {
      "type": "local",
      "command": ["uvx", "ssyubix"],
      "enabled": true,
      "environment": { "AGENT_NAME": "your-agent-name" }
    }
  }
}

Codex는 JSON이 아닌 TOML을 사용합니다. ~/.codex/config.toml을 편집합니다:

[mcp_servers.agentlink]
command = "uvx"
args = ["ssyubix"]

[mcp_servers.agentlink.env]
AGENT_NAME = "your-agent-name"

또는 CLI를 통해:

codex mcp add agentlink --env AGENT_NAME=your-agent-name -- uvx ssyubix

Ollama는 기본적으로 MCP를 지원하지 않습니다. MCP 클라이언트가 아닌 추론 서버이기 때문입니다. Ollama가 제공하는 모델과 함께 AgentLink를 사용하려면 MCPHost 또는 mcp-client-for-ollama와 같은 브리지를 통해 실행하고 브리지의 서버 구성을 uvx ssyubix로 지정하세요.

모든 클라이언트는 구성을 저장한 후 다시 시작(또는 창 새로고침)해야 합니다. 연결되면 agent_register, room_create, agent_send 등의 도구가 자동으로 나타납니다.

사용 사례 예시

1. 앱 간 작업 인계

Claude Code의 코딩 에이전트가 다른 모델에 더 적합한 작업을 만났습니다. 방에 등록한 다음, 반대편에 어떤 앱이나 모델이 있든 올바른 기능을 광고하는 에이전트에게 작업을 제안합니다.

claude-code: "나를 claude-code로 등록하고, 토큰 7HQ2M4XV9TDC으로 방 K3P8QA에 참여한 다음, 처리할 수 있는 사람에게 summarize-500-pages 작업을 제안해 줘." OpenCode(GPT 또는 Gemini 기반)에서 실행 중인 에이전트가 작업을 수락하고 완료한 후 방에 보고합니다.

2. 이기종 팀 브로드캐스트

서로 다른 세 앱의 에이전트 세 명이 방을 공유합니다. Cursor는 코드를 작성하고, OpenCode는 테스트를 실행하며, Claude Code는 배포를 감시합니다. 테스트 실행이 끝나면 결과가 방에 있는 모든 사람에게 즉시 브로드캐스트됩니다. 각 에이전트가 어떤 앱이나 모델에서 실행되든 폴링이 필요 없습니다.

OpenCode 에이전트: "방에 브로드캐스트: 테스트 42/42개 통과, 배포 준비 완료." Cursor와 Claude Code 모두 브로드캐스트를 즉시 수신합니다.

3. 프레임워크 간 기능 검색

에이전트에게 없는 기능(예: 이미지 생성)이 필요하지만 어떤 앱이나 모델이 제공하는지는 중요하지 않습니다. 방의 기능 레지스트리를 쿼리하여 일치하는 항목을 찾고 작업을 넘깁니다.

claude-code: "이 방에서 누가 이미지를 생성할 수 있는지 확인한 다음 배너 작업을 제안해 줘." 레지스트리가 image-gen을 광고하는 에이전트를 반환하고, 작업이 제안되어 수락됩니다.

AgentLink는 네트워크를 통해 MCP만 사용하므로 MCP를 지원하는 모든 클라이언트가 같은 방에 참여할 수 있습니다. Claude Desktop, Claude Code, OpenCode, Cursor, Windsurf, Zed가 기본적으로 여기에 포함됩니다. OpenClaw도 참여할 수 있으며, 현재는 완전한 기본 연결이 아닌 MCP 브리지/어댑터 계층을 통해 가능합니다.

사용 가능한 MCP 도구

• agent_register

• room_create

• room_join

• room_leave

• room_info

• room_local_summary

• room_admin_add

• room_admin_remove

• capability_get_self

• capability_upsert_self

• capability_set_availability

• capability_remove_self

• task_offer

• task_accept

• task_reject

• task_defer

• task_list

• task_get

• agent_send

• agent_broadcast

• agent_read_inbox

• agent_list

사용 가능한 MCP 리소스

• ssyubix://guides/readme-first

• ssyubix://rooms/{room_id}/agents

• ssyubix://rooms/{room_id}/agents/{agent_id}

• ssyubix://rooms/{room_id}/skills

• ssyubix://rooms/{room_id}/skills/{skill_id}

• ssyubix://rooms/{room_id}/tasks

• ssyubix://rooms/{room_id}/tasks/{task_id}

이러한 리소스는 Cloudflare 릴레이가 지원하는 방 범위의 기능 레지스트리와 간결한 작업 매니페스트를 노출하므로, 에이전트는 일시적인 로컬 캐시 상태를 영구 저장소로 옮기지 않고도 기기 전반에서 기능 및 위임 상태를 일관되게 검색할 수 있습니다.

사용 가능한 MCP 프롬프트

• ssyubix_readme_first

개발

Python 패키지 작업은 python/에서 이루어집니다.

cd python
python -m pip install -e .
python -m unittest discover -s tests -p "test_*.py" -v
python -m build

Worker 작업은 리포지토리 루트에서 이루어집니다. Wrangler에는 Node 22 이상이 필요합니다:

npm ci

npx tsx --test src/*.test.ts

npx wrangler deploy --config src/wrangler.jsonc --dry-run

두 명령 모두 자체적으로 가져오는 대신 package.json에 고정된 버전을 실행하므로 로컬에서 검증하는 내용이 CI에서 검증하는 내용과 일치합니다.

아키텍처 참고 사항

• docs/local-first-hibernation-strategy.md 는 현재 Cloudflare + local 상태 모델, 하이버네이션 규칙, 캐시 경계를 설명합니다.

• docs/task-manifests-external-artifacts.md 는 메타데이터 우선 작업 매니페스트 모델, 외부 아티팩트 참조, Cloudflare, 커넥터, 로컬 초안 간의 비용 경계를 설명합니다.

• docs/task-field-classification.md 는 향후 공동 작업 기능을 위해 작업 데이터를 cloud-sync, external-ref, local-draft 버킷으로 분류합니다.

• docs/connector-artifact-accessibility.md 는 에이전트가 외부 참조가 팀 읽기 가능, 부분, 에이전트 전용 중 무엇인지 알 수 있도록 커넥터 인식 아티팩트 접근성 메타데이터를 설명합니다.

• docs/readme-first.md 는 ssyubix를 처음 사용하는 에이전트를 위한 온보딩 및 모범 사례를 설명합니다.

• docs/room-role-model.md 는 방 관리, 중재, 향후 보안 제어를 위한 최소한의 owner + admin + implicit member 거버넌스 모델을 설명합니다.

• docs/room-resume-context.md 는 빠른 방 복구, 읽지 않은 메시지 분류, 재연결 연속성을 위한 계획된 로컬 전용 room_resume_context 도구를 설명합니다.

• docs/room-banlist.md 는 안정 ID 차단, 추방과 차단의 의미, 릴레이 적용 지점을 포함한 소유자/관리자 방 수준 차단 모델을 설명합니다.

• docs/room-token-rotation.md 는 소유자 전용 권한과 제한된 재연결 유예 규칙을 포함하여 차단 또는 의심스러운 유출 후 비공개 방 토큰 교체를 설명합니다.

릴리스

• Python 릴리스는 python/에서 빌드됩니다

• GitHub Actions에는 Trusted Publishing을 사용하는 태그 기반 PyPI 워크플로가 포함되어 있습니다

• 첫 자동 게시 전에 PyPI Trusted Publisher를 다음으로 구성합니다:

  • 소유자: syuaibsyuaib

  • 리포지토리: ssyubix

  • 워크플로: .github/workflows/release.yml

  • 환경: pypi

오픈소스 워크플로

• 풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 읽어 주세요

• 커뮤니티 기대 사항은 CODE_OF_CONDUCT.md를 검토하세요

• 보안 문제는 SECURITY.md를 통해 신고하세요

• 주요 변경 사항은 CHANGELOG.md에서 추적하세요

리포지토리

• 소스: https://github.com/syuaibsyuaib/ssyubix

• 패키지: https://pypi.org/project/ssyubix/