MCP-등록 서버

개요

AI 모델이 Ordinals Inscriptions과 상호 작용하여 거래의 콘텐츠를 표시할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

Related MCP server: MCP Bitcoin CLI

🎮 데모

💼 목차

• MCP-등록 서버

  • 개요

  • 💼 목차

  • 🔧 특징

  • 🦆 구스 통합

    • STDIO(로컬 확장) 사용

      • SSE(원격 확장) 사용

  • 🔑 Claude 데스크톱 통합

    • Claude Desktop 통합 테스트

  • 📂 프로젝트 구조

  • 📦 개발 설정

  • 📦 사용 가능한 도구

    • 순서 표시

  • 🚨 오류 처리

  • 🤝 기여하기

  • 📝 라이센스

🔧 특징

• 순서형 감지 : 비트코인 거래를 자동으로 감지하고 순서형으로 구문 분석하여 텍스트 기반, 이미지, JSON 및 기타 비문 형식을 지원합니다.

🦆 구스 통합

Goose는 Block에서 개발한 오픈소스 AI 에이전트 프레임워크로, 모델 컨텍스트 프로토콜(Model Context Protocol)을 통한 확장 기능을 지원합니다. MCP-Inscription 서버를 Goose 확장 기능으로 통합하여 Goose가 Ordinals Inscriptions과 상호 작용할 수 있도록 할 수 있습니다. Goose는 MCP 서버에 대해 두 가지 통합 모드를 지원합니다. 서버를 로컬 프로세스(STDIO)로 실행하거나 서버 전송 이벤트(SSE)를 통해 원격 서비스로 연결하는 것입니다. 두 가지 방법에 대한 지침은 다음과 같습니다.

STDIO(로컬 확장) 사용

이 방법은 Goose의 하위 프로세스로 MCP-Inscription 서버를 로컬에서 실행하여 표준 입출력을 통해 통신합니다.

1. MCP-Inscription 저장소를 복제하고 빌드합니다(아직 하지 않았다면):

   지엑스피1

   다음 단계에서 필요하므로 저장소의 전체 절대 경로를 기록해 두세요.

2. Goose에 새 확장 프로그램 추가: Goose의 설정 인터페이스를 엽니다. 명령줄에서 goose configure 실행하거나 Goose 데스크톱 앱에서 설정 > 확장 프로그램 으로 이동하여 확장 프로그램을 추가할 수 있습니다. 메뉴에서 "확장 프로그램 추가"를 선택합니다( 확장 프로그램 | goose 사용 ).

3. 확장 유형 선택 - 명령줄 확장: 확장 유형을 묻는 메시지가 표시되면 명령줄 확장 (CLI 메뉴 또는 UI에서)을 선택하여 Goose가 로컬 명령을 실행하도록 합니다( 확장 사용 | goose )(기본 제공 또는 원격 확장과 대조적으로).

4. 확장 세부 정보를 입력하세요. MCP-Inscription 서버의 이름과 명령을 제공하세요.

   • ID : mcp-inscription

   • 이름: "mcp-inscription" 또는 다른 식별자로 지정할 수 있습니다(이것이 확장 프로그램을 지칭하는 방식입니다).

   • 명령: 빌드된 CLI 스크립트의 전체 경로를 지정하세요. 예:

     node /absolute/path/to/mcp-inscription/build/cli.js

     /absolute/path/to/mcp-inscription 저장소를 복제한 실제 경로로 바꾸세요.

   • 일반적으로 스크립트 경로를 넘어서는 인수를 추가할 필요는 없습니다(서버에 특수 플래그가 필요한 경우는 제외).

5. 마무리 및 활성화: 확장 프로그램 추가를 완료합니다. Goose가 이 새 확장 프로그램을 구성(일반적으로 ~/.config/goose/config.yaml )에 추가합니다. 확장 프로그램이 활성화 되어 있는지 확인합니다(CLI 마법사를 사용하는 경우, 추가 시 기본적으로 활성화되어 있어야 합니다. Goose 데스크톱 앱에서 확장 프로그램 목록을 확인하고 활성화되어 있지 않으면 활성화할 수 있습니다(확장 프로그램 사용 | goose ).

6. 새 확장 프로그램으로 Goose 세션을 시작하세요. 이제 Goose에서 확장 프로그램을 사용할 수 있습니다. CLI를 통해 Goose를 실행하는 경우, 다음을 실행하여 확장 프로그램이 포함된 세션을 시작하세요.

   goose session --with-extension "mcp-inscription"

"ordinals"를 확장 프로그램에 지정한 이름으로 바꿉니다( 확장 프로그램 사용 | goose ). (이렇게 하면 세션에서 확장 프로그램이 로드됩니다. 또는 확장 프로그램이 전역적으로 활성화된 경우, Goose Desktop이나 CLI가 모든 세션에서 자동으로 해당 확장 프로그램을 사용할 수 있도록 설정합니다.)

SSE(원격 확장) 사용

이 방법은 HTTP SSE 스트림을 통해 Goose를 이미 실행 중인 MCP 서버에 연결합니다. MCP-Inscription 서버를 독립형 서비스로 실행하려는 경우(다른 컴퓨터에서 실행하거나 Goose와 독립적으로 실행하려는 경우) 이 방법을 사용하세요.

1. MCP 서버를 독립 실행형 서비스로 시작합니다. 연결을 수신하려면 SSE 모드에서 MCP-Inscription 서버를 실행합니다.

   # Navigate to your mcp-inscription directory
   cd /path/to/mcp-inscription
   
   # If you havent built it yet
   npm install
   npm run build
   
   # Run in SSE mode on port 3000 (default)
   SERVER_MODE=sse node build/cli.js
   
   # Alternatively, specify a different port
   SERVER_MODE=sse PORT=9000 node build/cli.js

   이렇게 하면 서버가 SSE 모드로 시작되어 http://localhost:3000 (또는 지정한 포트)에서 사용할 수 있습니다.

2. Goose(원격)에 새 확장 프로그램을 추가합니다. 이전과 마찬가지로 goose configure 실행하거나 Goose UI를 사용하여 확장 프로그램을 추가합니다 ( "확장 프로그램 사용" | "goose "). 이번에는 확장 프로그램 유형을 묻는 메시지가 나타나면 "원격 확장 프로그램"을 선택합니다( "확장 프로그램 사용" | "goose "). 이렇게 하면 Goose가 SSE를 통해 외부 서버에 연결됩니다.

3. 원격 확장 프로그램 세부 정보를 입력하세요. 확장 프로그램에 이름(예: "ordinals")을 지정하고 서버의 URL을 입력하세요. URL 에는 MCP 서버가 실행 중인 기본 주소를 입력하세요. 예를 들어, 서버가 로컬 컴퓨터의 9000번 포트에서 수신 대기하는 경우 http://localhost:9000 입력할 수 있습니다. Goose는 해당 주소에서 MCP 서버의 SSE 엔드포인트에 연결을 시도합니다. (Goose는 표준 MCP SSE 경로를 사용하며, 관례적으로 서버의 /mcp/sse 경로 아래에 있습니다. 일반적으로 호스트와 포트만 입력하면 나머지는 Goose가 처리합니다.)

4. 확장 기능 활성화: 원격 확장 기능을 추가한 후, STDIO의 경우처럼 Goose 설정에서 활성화되었는지 확인하세요. STDIO 또는 SSE 확장 기능 중 하나만 활성화하면 됩니다(같은 도구를 사용). 실수로 같은 서버의 로컬 버전과 원격 버전을 모두 활성화한 경우, 혼동을 방지하기 위해 하나를 비활성화하는 것이 좋습니다.

Goose에서 MCP-Inscription 확장 프로그램 사용하기: 확장 프로그램을 설정하고 활성화하면(위의 방법 중 하나를 통해) Goose와 상호 작용하고 ord 데이터를 쿼리할 수 있습니다. 새로운 Goose 채팅이나 세션에서 평소처럼 질문하기만 하면 됩니다. Goose는 요청을 처리하기 위해 MCP-Inscription 도구를 사용해야 하는 시점을 인식합니다. 예:

• "서수형을 보여주세요: 0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389?"

이러한 질문을 하면 Goose는 MCP-Inscription 서버의 도구를 호출하여 답변(예: 최신 비트코인 블록 정보)을 반환합니다. Goose가 MCP-Inscription 서버를 통해 비트코인 블록체인에서 가져온 최신 정보로 응답하는 것을 볼 수 있습니다.

Goose가 해당 확장 프로그램을 사용하지 않는 것 같으면(예: 정보를 찾을 수 없다고 응답하는 경우), 해당 확장 프로그램이 활성화되어 있고 서버가 SSE 모드(원격)로 실행 중인지 확인하세요. Goose의 CLI를 자세한 로깅과 함께 실행하여 해당 확장 프로그램 호출을 시도했는지 확인할 수도 있습니다. 일반적으로 올바르게 구성된 경우, Goose는 MCP-Inscription 서버의 기능을 자동으로 감지하여 필요한 경우 사용합니다.

추가 자료: Goose 확장 기능 및 MCP에 대한 자세한 내용은 Goose 공식 문서( 확장 기능 사용 | goose )를 참조하세요. 이 문서에는 기본 제공 및 커뮤니티 확장 기능 목록이 포함되어 있으며, MCP 서버가 Goose에 통합되는 방식을 설명합니다. 또한 Goose 문서와 MCP(Model Context Protocol) 문서에서 사용 가능한 MCP 서버 목록과 추가 구성 팁을 확인할 수 있습니다. 더 많은 확장 기능을 살펴보거나 직접 개발하려는 경우 이 문서가 도움이 될 수 있습니다.

🔑 Claude 데스크톱 통합

Claude Desktop(Claude용 Anthropic 데스크톱 앱)에서 MCP-Inscription 서버를 사용하려면 다음 단계를 따르세요.

1. Claude Desktop 다운로드 및 설치: 공식 Claude Desktop 다운로드 페이지를 방문하여 운영 체제(macOS 또는 Windows)에 맞는 앱을 다운로드하세요( Claude Desktop 설치 | Anthropic 도움말 센터 ). 앱을 설치하고 최신 버전을 사용하고 있는지 확인하세요(앱 메뉴에서 업데이트 확인 가능).

2. MCP-Inscription 저장소를 복제하고 빌드합니다.

   git clone https://github.com/Laz1mov/mcp-inscription
   cd mcp-inscription
   npm install
   npm run build

3. MCP-Inscription 서버를 사용하도록 Claude Desktop을 구성합니다. Claude Desktop 구성 파일을 엽니다(Claude Desktop에서 처음으로 설정을 편집할 때 생성됩니다).

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

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
     이 JSON 설정의 "mcpServers" 섹션에 MCP-Inscription 서버 항목을 추가하세요. 예:

   {
     "mcpServers": {
       "mcp-inscription": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-inscription/build/cli.js"]
       }
     }
   }

   위 스니펫에서 "mcp-inscription" 서버의 식별자입니다(원하는 이름으로 지정할 수 있습니다). /absolute/path/to/mcp-inscription 저장소를 복제한 실제 전체 경로로 바꾸세요.

4. Claude Desktop을 다시 시작하세요. claude_desktop_config.json 파일을 저장한 후 Claude Desktop을 닫았다가 다시 여세요 . 다음 실행 시 Claude는 구성된 대로 MCP-Inscription 서버를 자동으로 시작합니다. Claude Desktop이 실행 중이었다면 변경 사항을 적용하려면 다시 시작해야 합니다.

Claude Desktop 통합 테스트

Claude Desktop을 다시 시작하면 MCP-Inscription 서버가 제대로 작동하는지 테스트할 수 있습니다.

• 응답을 확인하세요. Claude는 오류 없이 자세한 답변(예: 비문 자체 또는 룬 정보)을 반환해야 합니다. 오류 메시지가 표시되거나 유용한 응답이 없으면 MCP 서버가 제대로 연결되지 않았을 수 있습니다.

• Claude의 로그를 확인하세요(필요한 경우): Claude Desktop은 MCP 통합 디버깅에 도움이 되는 로그 파일을 제공합니다. 도구가 응답하지 않으면 다음 위치에서 로그 파일을 확인하세요.

  • macOS: ~/Library/Logs/Claude/

  • 윈도우: %APPDATA%\Claude\logs\
    일반적인 MCP 연결 메시지는 mcp.log , MCP 서버 출력/오류는 mcp-server-mcp-inscription.log 파일(또는 사용자가 지정한 파일 이름)을 확인하세요. 이 로그는 서버 시작 여부 또는 오류(예: 잘못된 경로 또는 서버 예외) 발생 여부를 보여줍니다. 오류가 발생하면 필요에 따라 구성 또는 환경을 수정한 후 Claude Desktop을 다시 시작하고 다시 테스트하세요.

📂 프로젝트 구조

mcp-inscription/
├── src/
│   ├── ordinals_client.ts      # Bitcoin ordinals and runestone utility functions
│   ├── servers/
│   │   ├── index.ts            # Server exports and factory functions
│   │   ├── sse.ts              # Server implementation using SSE transport
│   │   ├── stdio.ts            # Server implementation using STDIO transport
│   │   └── base.ts             # Base server implementation with shared functionality
│   ├── index.ts                # Main entry point
│   ├── cli.ts                  # CLI launcher
│   ├── mcp_inscription_types.ts # Shared types and schemas for the MCP-Inscription server
│   └── utils/
│       ├── logger.ts           # Logger setup
│       ├── cache.ts            # Caching implementation
│       ├── error_handlers.ts   # Error handling utilities
│       ├── json_utils.ts       # JSON processing utilities
│       ├── img_utils.ts        # Image processing and conversion utilities
│       └── version.ts          # Version information
├── .env.example                # Example environment configuration file
├── package.json
├── tsconfig.json
└── README.md

📦 사용 가능한 도구

순서 표시

설명:
거래의 증인 데이터에서 순서적 비문 데이터를 디코딩합니다.

입력 스키마:

{
  "txid": "string"
}

입력 예시:

{
  "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389"
}

산출:
디코딩된 비문 내용을 반환합니다. 비문 내용은 텍스트, JSON, HTML 또는 기타 형식일 수 있습니다.

🚨 오류 처리

서버는 사용자 지정 오류 유형을 사용하여 비트코인 작업 및 블록체인 쿼리를 처리합니다. 자세한 오류 메시지는 Pino를 사용하여 기록되며, 디버깅을 용이하게 하기 위해 클라이언트 응답에 포함됩니다.

🤝 기여하기

기여와 기능 요청을 환영합니다! GitHub에서 풀 리퀘스트를 제출하거나 이슈를 열어주세요.

📝 라이센스

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