cp2p
v0.1.0
Published
P2P distributed resource sharing system for Claude context management
Maintainers
bbangjoReadme
Claude P2P - Distributed Resource Sharing System
P2P 네트워크를 통한 Claude 컨텍스트 메모리 문제 해결 시스템
개요
Claude를 사용하다 보면 컨텍스트 메모리가 부족해지는 문제가 발생합니다. 이 프로젝트는 허가된 사용자들 간의 P2P 네트워크를 구성하여 컴퓨팅 자원을 분산 처리함으로써 이 문제를 해결합니다.
핵심 기능
- P2P 자원 공유: 신뢰할 수 있는 피어 간 컴퓨팅 자원 공유
- 컨텍스트 분산: Claude 컨텍스트를 효율적으로 분할하여 여러 노드에 분산
- 보안 통신: End-to-End 암호화 및 신뢰 기반 인증
- 자동 자원 할당: 지능형 코디네이터를 통한 최적 피어 선택
- 투명한 통합: 기존 Claude 워크플로우에 자연스럽게 통합
- 🆕 피어 레지스트리: 간편한 이름 기반 peer 발견 및 연결
시스템 아키텍처
┌─────────────────────────────────────────────────────────┐
│ Client A (Heavy Load) ◄──► Coordinator ◄──► Client B │
│ │ │ │ │
│ Local Storage Shared Context Local │
└─────────────────────────────────────────────────────────┘자세한 아키텍처는 ARCHITECTURE.md를 참고하세요.
빠른 시작
사전 요구사항
- Node.js >= 18.0.0
- npm >= 9.0.0
설치
방법 1: npm 글로벌 설치 (권장) ⭐
# npm에서 직접 설치
npm install -g cp2p
# 설치 확인
cp2p --version방법 2: GitHub에서 설치
# GitHub에서 직접 설치 (최신 버전)
npm install -g github:bbangjooo/claude-p2p
# 또는 저장소 클론 (개발용)
git clone https://github.com/bbangjooo/claude-p2p.git
cd claude-p2p
npm install
npm run build
npm link기본 사용법
방법 0: MCP 서버로 Claude와 통합 (가장 쉬움!) ⭐
Claude Desktop에서 직접 P2P 기능을 사용:
자동 설치 (권장):
# 1. 빌드 및 전역 커맨드 설정
npm run build
npm link
# 2-a. 로컬 registry 사용 (기본값)
cp2p install-mcp
# ✅ MCP 서버 설정 자동 등록 (registry: http://localhost:9000)
# ✅ Slash commands 자동 설치 (/p2p-init, /p2p-start 등)
# 2-b. 클라우드 registry 사용 (EC2 등)
cp2p install-mcp --registry http://YOUR_EC2_IP:9000
# ✅ EC2 registry 서버 URL로 설정
# 💡 팀원들과 공유하는 registry 서버 사용 시
# 2-c. 모든 옵션 커스터마이징
cp2p install-mcp \
--registry http://registry.example.com:9000 \
--port 9001
# 3. Claude Desktop 재시작
# 4. Claude와 대화!
You: 큰 코드베이스 분석해줘
Claude: [자동으로 자원 체크 → 부족하면 P2P peer에게 위임]
You: /p2p-status
Claude: [P2P 네트워크 상태를 자동으로 확인하고 보고]옵션 설명:
--registry <url>: Registry 서버 URL (기본값: http://localhost:9000)--port <number>: P2P 노드 포트 (기본값: 9001)--coordinator <url>: Coordinator 서버 URL (선택)--auto-start: 자동 시작 여부 (기본값: true)
npm link 없이 사용:
npm run build
# 로컬 registry
node dist/cli.js install-mcp
# EC2 registry
node dist/cli.js install-mcp --registry http://YOUR_EC2_IP:9000수동 설치:
# 1. 빌드
npm run build
# 2. Claude Desktop 설정 파일 수정 (~/Library/Application Support/Claude/claude_desktop_config.json)
{
"mcpServers": {
"cp2p": {
"command": "node",
"args": ["/ABSOLUTE/PATH/cp2p/dist/mcp/server.js"],
"env": {
"REGISTRY_URL": "http://localhost:9000",
"P2P_PORT": "9001"
}
}
}
}
# 3. Claude Desktop 재시작✨ 간소화된 MCP 서버 특징:
- 🔍 실시간 자원 모니터링: CPU, Memory를 자동으로 체크
- 🚀 자동 peer 위임: 자원 부족 시 가장 좋은 peer에게 자동 위임
- ⚡ 자동 초기화: Docker 환경이 없으면 자동으로 실행
- 🎯 핵심 기능만: 불필요한 기능 제거, 4개 툴만 제공
자세한 MCP 사용법은 간소화된 MCP 가이드 ⭐를 참고하세요. 전체 기능이 필요하면 MCP 가이드를 참고하세요.
방법 1: 레지스트리를 이용한 간편 연결 (권장)
# 1. 레지스트리 서버 시작
cp2p registry start
# 2. 노드 시작 및 자동 등록
cp2p start-with-registry --name my-laptop
# 3. 다른 노드와 연결 (이름으로!)
cp2p connect-peer my-desktop
# 4. 등록된 피어 확인
cp2p registry list방법 2: Multiaddress 직접 사용
# 1. P2P 노드 시작
cp2p start --port 9000
# 2. 피어 연결 (긴 주소 필요)
cp2p connect /ip4/192.168.1.100/tcp/9001/p2p/12D3KooW...
# 3. 신뢰 피어 추가
cp2p trust add <peer-id>자세한 사용법은 Registry Guide를 참고하세요.
방법 3: Docker로 실행 (가장 간편!)
Docker Compose로 Registry + 노드들을 한 번에 실행:
# 전체 스택 실행
docker-compose up -d
# 상태 확인
curl http://localhost:9000/health # Registry
curl http://localhost:9100/api/info # Node1
curl http://localhost:9101/api/info # Node2
# 등록된 peer 확인
curl http://localhost:9000/peers자세한 내용은 Docker Guide를 참고하세요.
Claude Code Slash Commands ⚡
cp2p install-mcp 실행 시 자동으로 설치되는 커스텀 slash commands!
사용 가능한 커맨드
/p2p-init- 프로젝트 전체 초기화 (빌드, 링크, MCP 설치)/p2p-install- MCP 서버 자동 설치/p2p-start- P2P 노드 시작 가이드/p2p-connect- Peer 연결 가이드/p2p-status- 현재 P2P 상태 확인/p2p-help- 전체 도움말 보기
사용 방법
Claude Code에서 채팅하면서 / 를 입력하면 자동완성으로 커맨드가 나타납니다:
You: /p2p-init
Claude: [프로젝트를 자동으로 초기화합니다]
You: /p2p-status
Claude: [현재 P2P 네트워크 상태를 확인하고 보고합니다]예시
처음 설정할 때:
You: /p2p-init
Claude: 프로젝트를 초기화하겠습니다!
1. npm install ✓
2. npm run build ✓
3. npm link ✓
4. cp2p install-mcp ✓
모두 완료되었습니다! Claude Desktop을 재시작하세요.Peer 연결할 때:
You: /p2p-connect
Claude: Peer 연결을 도와드리겠습니다.
먼저 사용 가능한 peer를 확인하겠습니다...
[cp2p registry list 실행]
...커맨드 위치: .claude/commands/p2p-*.md
개발 현황
현재 프로젝트는 모든 Phase 구현 완료 상태입니다! 🎉
로드맵
- [x] Phase 0: 프로젝트 초기 설정 및 설계
- [x] Phase 1: MVP Prototype (P2P 연결, 메시징 프로토콜)
- [x] Phase 2: Context Management (컨텍스트 분할/병합, 스토리지)
- [x] Phase 3: Security & Trust (암호화, 키 관리, 신뢰 모델)
- [x] Phase 4: Coordinator Service (자원 할당, 피어 발견)
- [x] Phase 5: Integration & Orchestration (워크플로우 통합)
- [x] Phase 6: Monitoring (메트릭 수집, 성능 추적)
자세한 구현 계획은 IMPLEMENTATION_PLAN.md를 참고하세요.
프로젝트 구조
cp2p/
├── src/ # 소스 코드
│ ├── core/ # 핵심 P2P 클라이언트 (P2PClient, DataTransfer)
│ ├── context/ # 컨텍스트 관리 (Splitter, Merger, ContextChunk)
│ ├── security/ # 암호화 및 인증 (KeyManager, Encryption, TrustManager)
│ ├── coordinator/ # 코디네이터 서비스 (Server, Client, ResourceAllocator)
│ ├── registry/ # 🆕 피어 레지스트리 (RegistryServer, RegistryClient)
│ ├── network/ # 네트워크 레이어 (P2PProtocol, SecureChannel, MessageProtocol)
│ ├── storage/ # 로컬 스토리지 (LocalStorage with LevelDB)
│ ├── integration/ # 통합 레이어 (WorkflowOrchestrator)
│ ├── monitoring/ # 모니터링 (Monitor, 메트릭 수집)
│ └── utils/ # 유틸리티 (logger, checksum)
├── tests/ # 테스트
├── docs/ # 문서
│ └── REGISTRY_GUIDE.md # 🆕 레지스트리 사용 가이드
└── scripts/ # 유틸리티 스크립트기술 스택
- Language: TypeScript/Node.js 18+
- P2P Framework: libp2p 3.1.0 (TCP, Noise, Mplex)
- Storage: LevelDB (로컬 persistent storage)
- Encryption: Node.js crypto (AES-256-GCM)
- Coordinator: Express.js (REST API)
- CLI: Commander.js
- Testing: Jest (72 tests)
- Logging: Winston
📚 문서
시작하기
- 간소화된 MCP 가이드 - ⭐⭐ 자원 부족 시 자동 peer 위임 (가장 쉬움!)
- MCP 가이드 - ⭐ Claude Desktop과 통합하기 (전체 기능)
- Claude 자원 공유 가이드 - 처음부터 끝까지 완전한 가이드
- Registry 가이드 - 이름 기반 peer 발견 및 연결
- Docker 가이드 - Docker로 간편하게 배포하기
고급 설정
개발자
개발 참여
개발 환경 설정
# 의존성 설치
npm install
# 개발 모드 실행
npm run dev
# 테스트 실행
npm test
# 린트 검사
npm run lint
# 타입 체크
npm run type-check브랜치 전략
main: 프로덕션 준비 코드develop: 개발 중인 코드feature/*: 새 기능 개발fix/*: 버그 수정
커밋 컨벤션
feat: 새로운 기능 추가
fix: 버그 수정
docs: 문서 수정
refactor: 코드 리팩토링
test: 테스트 추가/수정
chore: 빌드 프로세스 또는 도구 변경보안
보안 관련 이슈는 공개 이슈가 아닌 이메일로 보고해주세요: [[email protected]]
보안 정책 및 가이드라인은 SECURITY.md를 참고하세요.
라이선스
MIT License - 자세한 내용은 LICENSE 파일을 참고하세요.
문서
- Core Concepts - 핵심 개념 및 용어 설명 (Node vs Peer, Trust Model, etc.)
- Architecture Design - 시스템 아키텍처 설계
- Implementation Plan - 구체적인 구현 계획
- API Specification - API 명세 (작성 예정)
- Security Guidelines - 보안 가이드라인 (작성 예정)
연락처
- Issue Tracker: https://github.com/bbangjooo/cp2p/issues
- Discussions: https://github.com/bbangjooo/cp2p/discussions
감사의 말
이 프로젝트는 다음 오픈소스 프로젝트들의 영향을 받았습니다: