헤데라 MCP 서버

개요

Hedera MCP 서버는 Hedera 네트워크에서 AI 에이전트 간의 분산 통신을 지원하도록 설계된 프로덕션급 모듈형 Node.js(TypeScript) 서버입니다. 모델-컨텍스트-프로토콜(MCP) 아키텍처를 구현하여 RESTful API와 SSE(Server-Sent Events) 기반 MCP 인터페이스를 모두 제공합니다.

Hedera Agent Kit 과 Standards Agent Kit을 함께 사용하면 서버는 여러 Hedera Consensus Service(HCS) 표준을 지원합니다.

• HCS-1(파일/데이터 관리)
• HCS-2(에이전트 발견 등록부)
• HCS-3(대용량 메시지 처리 및 재귀)
• HCS-10(에이전트 통신 프로토콜)
• HCS-11(분산형 ID/프로필 관리)

이 서버는 특히 헤데라(Hedera)에서 AI 통합 탈중앙화 애플리케이션을 개발하는 해커톤 참가자와 개발자를 대상으로 합니다. 또한, 커서(Cursor) 와 같은 자율 에이전트 상호작용 도구와도 호환됩니다.

폴더 구조

지엑스피1

특징

• 에이전트 등록 및 프로필(HCS-11):
  AI 에이전트를 위한 새로운 Hedera 계정을 생성하거나 기존 계정을 가져오세요. 인바운드/아웃바운드 토픽과 온체인 프로필을 자동으로 설정합니다.
• 에이전트 발견(HCS-2):
  중앙 레지스트리 주제에 상담원을 등록하세요. 제공된 검색 API를 사용하여 이름이나 역량으로 상담원을 검색하세요.
• 보안 통신(HCS-10):
  에이전트 간 연결 요청을 시작하고 수락합니다. 에이전트가 안전하게 메시지를 교환할 수 있는 전용 연결 토픽을 설정합니다.
• 대용량 메시지 처리(HCS-1 및 HCS-3):
  전용 파일 주제에 대용량 메시지 내용을 저장하고 메시지 내에서 HRL(HCS 리소스 로케이터) 참조를 반환하여 부하를 분산합니다.
• SSE를 통한 MCP 인터페이스:
  AI 도구(예: Cursor)가 서버 "도구"(예: register_agent, send_message)를 직접 호출할 수 있도록 하는 MCP 호환 SSE 엔드포인트( FastMCP 를 통해)를 노출합니다.
• RESTful API:
  자세한 요청/응답 형식을 통해 에이전트 작업, 연결 관리 및 메시징을 위한 포괄적인 HTTP 엔드포인트를 제공합니다.
• 프로덕션 준비 완료 배포:
  원활한 단일 명령 배포를 위해 Docker 및 Docker Compose 구성이 제공됩니다.

요구 사항

• Node.js ≥ 18(LTS 권장)
• npm (Node와 함께 제공)
• Docker 및 Docker Compose (컨테이너 배포용)
• 거래에 충분한 자금이 있는 Hedera 테스트넷(또는 메인넷) 계정
  (다음 환경 변수를 설정하세요: HEDERA_OPERATOR_ID 및 HEDERA_OPERATOR_KEY .)

시작하기

1. 저장소 복제

2. 종속성 설치

3. 환경 변수 구성

프로젝트 루트에 다음 내용으로 .env 파일을 만듭니다(실제 자격 증명에 맞게 조정).

4. 프로젝트 구축

TypeScript 코드를 JavaScript로 컴파일합니다.

5. 서버를 로컬로 실행

REST API 및 MCP SSE 서버를 시작합니다.

다음 내용을 나타내는 로그가 표시되어야 합니다.

• REST API는 http://localhost:3000 에서 수신 중입니다.
• MCP SSE 서버는 http://localhost:3001/sse 에서 사용할 수 있습니다.

6. 개발 모드

자동 재구축을 통해 빠르게 개발하려면 다음을 사용하세요.

API 문서

에이전트 엔드포인트

• POST /api/agents/register
  새로운 에이전트를 등록합니다.
  요청 본문:
  { "name": "AliceAgent", "accountId": "0.0.ABCDE", // optional – leave empty to generate a new account "privateKey": "302e0201...", // optional – required if accountId is provided "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
  응답(201개 생성됨):
  { "accountId": "0.0.789123", "privateKey": "302e0201... (if new)", "profile": { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" } }
• GET /api/agents/{계정ID}
  계정 ID로 에이전트의 프로필을 검색합니다.
  응답(200 OK):
  { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" }
• GET /api/agents?name=앨리스&기능=0
  이름 및/또는 역량으로 에이전트를 검색하세요.
  응답(200 OK):
  [ { "name": "AliceAgent", "inboundTopicId": "0.0.444444", "outboundTopicId": "0.0.444445", "type": 1, "capabilities": [0, 4], "model": "gpt-4", "creator": "Alice" } ]

연결 엔드포인트

• POST /api/connections/request
  다른 에이전트에 연결 요청을 시작합니다.
  요청 본문:
  { "fromAccount": "0.0.AAAAA", "fromPrivateKey": "302e0201...", "toAccount": "0.0.BBBBB" }
  응답(200 OK):
  { "requestSequenceNumber": 42 }
• POST /api/connections/accept
  연결 요청을 수락하고 전용 연결 주제를 생성합니다.
  요청 본문:
  { "fromAccount": "0.0.BBBBB", "fromPrivateKey": "302e0201...", "requesterAccount": "0.0.AAAAA" }
  응답(200 OK):
  { "connectionTopicId": "0.0.CCCCC" }
• GET /api/connections?accountId=0.0.AAAAA
  지정된 에이전트에 대한 모든 활성 연결을 나열합니다.
  응답(200 OK):
  [ { "peer": "0.0.BBBBB", "connectionTopicId": "0.0.CCCCC" } ]

메시징 엔드포인트

• POST /api/messages/send
  확립된 연결을 통해 메시지를 전송합니다.
  요청 본문:
  { "senderAccount": "0.0.AAAAA", "senderKey": "302e0201...", "connectionTopicId": "0.0.CCCCC", "message": "Hello, AgentB!" }
  응답(200 OK):
  { "sequenceNumber": 7 }
• GET /api/messages?connectionTopicId=0.0.CCCCC&limit=10
  연결 주제에서 최근 메시지를 검색합니다.
  응답(200 OK):
  { "messages": [ "{\"p\":\"hcs-10\",\"op\":\"message\",\"operator_id\":\"0.0.444444@0.0.AAAAA\",\"data\":\"Hello, AgentB!\",\"m\":\"Message from agent.\"}" ] }

MCP SSE 인터페이스

서버는 FastMCP 기반의 SSE(Server-Sent Events)를 통해 MCP 인터페이스를 제공합니다. 이 인터페이스는 다음 위치에서 사용할 수 있습니다.

커서와의 통합

1. 서버를 실행합니다:
   MCP SSE 서버가 실행 중인지 확인하세요(기본값은 포트 3001). 아래 설명대로 npm start 또는 Docker를 사용하세요.
2. 커서에서 구성:
   커서의 MCP 설정에서 다음 URL을 사용하여 새 MCP 서버를 추가합니다.
   http://localhost:3001/sse
   커서는 사용 가능한 도구 목록(예: register_agent , request_connection , send_message 등)을 자동으로 검색합니다.
3. 용법:
   이러한 도구를 사용하여 커서의 AI가 작업을 수행하도록 지시할 수 있습니다. 예를 들어, 다음과 같이 프롬프트합니다.

   "AliceAgent라는 새로운 에이전트를 등록하고 나를 BobAgent에 연결해 주세요."
   커서는 SSE 인터페이스에 정의된 각각의 MCP 도구를 호출합니다.

도커 배포

이 프로젝트에는 간편한 단일 명령 배포를 위한 Dockerfile과 docker-compose.yml 파일이 포함되어 있습니다.

Docker Compose 사용

1. 환경 변수 확인:
   프로젝트 루트의 .env 파일에 환경 변수를 설정합니다(위 참조).
2. 빌드 및 실행:
   docker-compose up --build -d
   이 명령은 Docker 이미지를 빌드하고 컨테이너를 분리 모드로 시작합니다. REST API는 3000번 포트에서, MCP SSE 서버는 3001번 포트에서 접속 가능합니다.
3. 배포 확인:
   브라우저를 열거나 curl 사용하여 확인하세요.
   • 상태 점검: http://localhost:3000/
   • MCP SSE 엔드포인트: http://localhost:3001/sse

테스트

테스트 모음 실행

이 프로젝트에서는 Jest를 사용하여 테스트를 수행합니다. 테스트는 단위 테스트, 통합 테스트, 엔드투엔드 테스트로 구성됩니다.

다음을 사용하여 모든 테스트를 실행합니다.

테스트에는 다음이 포함됩니다.

• 단위 테스트: 개별 서비스의 논리를 검증합니다(예: fileService.test.ts 의 파일 청킹).
• 통합 테스트: Supertest를 사용하여 REST API 엔드포인트를 테스트하여 적절한 응답을 보장합니다.
• 종단간 테스트: Hedera Testnet에서 전체 에이전트 커뮤니케이션 흐름(에이전트 등록, 연결, 메시징)을 시뮬레이션합니다.

참고: 테스트는 Hedera 테스트넷에서 라이브 운영을 실행합니다. 테스트 환경에 충분한 자금이 있는지, 그리고 최소 HBAR 소비량을 알고 있는지 확인하세요.

유지 관리 및 최적화

• 로깅 및 모니터링:
  서버에는 기본 로거가 포함되어 있습니다. 운영 환경에서는 더욱 강력한 로깅 솔루션(예: Winston 또는 Pino)을 통합하고 로그 로테이션 및 모니터링 대시보드를 설정하는 것을 고려해 보세요.
• 캐싱:
  에이전트 프로필과 연결 목록은 메모리에 캐시됩니다. 부하가 높은 시나리오에서는 이를 영구 저장소(예: Redis 또는 데이터베이스)로 대체하는 것을 고려하세요.
• 스케일링:
  서버는 메모리 내 캐시를 제외하고는 상태 비저장(stateless)입니다. 로드 밸런서 뒤에서 수평 확장이 가능합니다. 여러 인스턴스의 경우 모든 에이전트가 글로벌 레지스트리에 나타나도록 동일한 레지스트리 구성을 공유해야 합니다.
• 보안 고려 사항:
  • .env 파일을 보호하고 개인 키를 노출하지 마세요.
  • 프로덕션의 경우 API 엔드포인트에 대한 적절한 인증/권한 부여를 구현합니다.
  • HTTPS 및 기타 안전한 통신 방식을 사용하는 것을 고려하세요.
• 표준 준수 업데이트:
  Hedera Agent Kit 및 Standards Agent Kit 업데이트를 계속 확인하세요. 새로운 필드나 프로토콜이 도입되는 경우 종속성 업그레이드에 최소한의 조정만 필요할 수 있습니다.

기여하다

기여를 환영합니다! 저장소를 포크하고 개선 사항을 담은 풀 리퀘스트를 열어주세요. 주요 변경 사항의 경우, 먼저 이슈를 열어 변경 사항을 논의해 주세요.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다.