헤데라 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) 와 같은 자율 에이전트 상호작용 도구와도 호환됩니다.

Related MCP server: HashPilot

폴더 구조

지엑스피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. 저장소 복제

git clone https://github.com/hgraphpunks/hedera-mcp-server.git
cd hedera-mcp-server

2. 종속성 설치

npm install

3. 환경 변수 구성

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

# .env
HEDERA_NETWORK=testnet
HEDERA_OPERATOR_ID=0.0.12345
HEDERA_OPERATOR_KEY=302e0201...
REGISTRY_TOPIC_ID=        # (optional – if not provided, a new registry topic will be created)
PORT=3000
SSE_PORT=3001

4. 프로젝트 구축

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

npm run build

5. 서버를 로컬로 실행

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

npm start

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

• REST API는 http://localhost:3000 에서 수신 중입니다.

• MCP SSE 서버는 http://localhost:3001/sse 에서 사용할 수 있습니다.

6. 개발 모드

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

npm run dev

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 인터페이스를 제공합니다. 이 인터페이스는 다음 위치에서 사용할 수 있습니다.

http://localhost:3001/sse

커서와의 통합

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를 사용하여 테스트를 수행합니다. 테스트는 단위 테스트, 통합 테스트, 엔드투엔드 테스트로 구성됩니다.

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

npm test

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

• 단위 테스트: 개별 서비스의 논리를 검증합니다(예: fileService.test.ts 의 파일 청킹).

• 통합 테스트: Supertest를 사용하여 REST API 엔드포인트를 테스트하여 적절한 응답을 보장합니다.

• 종단간 테스트: Hedera Testnet에서 전체 에이전트 커뮤니케이션 흐름(에이전트 등록, 연결, 메시징)을 시뮬레이션합니다.

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

유지 관리 및 최적화

• 로깅 및 모니터링:
  서버에는 기본 로거가 포함되어 있습니다. 운영 환경에서는 더욱 강력한 로깅 솔루션(예: Winston 또는 Pino)을 통합하고 로그 로테이션 및 모니터링 대시보드를 설정하는 것을 고려해 보세요.

• 캐싱:
  에이전트 프로필과 연결 목록은 메모리에 캐시됩니다. 부하가 높은 시나리오에서는 이를 영구 저장소(예: Redis 또는 데이터베이스)로 대체하는 것을 고려하세요.

• 스케일링:
  서버는 메모리 내 캐시를 제외하고는 상태 비저장(stateless)입니다. 로드 밸런서 뒤에서 수평 확장이 가능합니다. 여러 인스턴스의 경우 모든 에이전트가 글로벌 레지스트리에 나타나도록 동일한 레지스트리 구성을 공유해야 합니다.

• 보안 고려 사항:

  • .env 파일을 보호하고 개인 키를 노출하지 마세요.

  • 프로덕션의 경우 API 엔드포인트에 대한 적절한 인증/권한 부여를 구현합니다.

  • HTTPS 및 기타 안전한 통신 방식을 사용하는 것을 고려하세요.

• 표준 준수 업데이트:
  Hedera Agent Kit 및 Standards Agent Kit 업데이트를 계속 확인하세요. 새로운 필드나 프로토콜이 도입되는 경우 종속성 업그레이드에 최소한의 조정만 필요할 수 있습니다.

기여하다

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

특허

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