MCP-Inscriptionサーバー

概要

AI モデルが Ordinals Inscription と対話し、トランザクションのコンテンツを表示できるようにする Model Context Protocol (MCP) サーバー。

Related MCP server: MCP Bitcoin CLI

🎮 デモ

💼 目次

• MCP-Inscriptionサーバー

  • 概要

  • 💼 目次

  • 🔧 機能

  • 🦆 Goose 統合

    • STDIO (ローカル拡張) の使用

      • SSE (リモート拡張) の使用

  • 🔑 クロード デスクトップ統合

    • Claudeデスクトップ統合のテスト

  • 📂 プロジェクト構造

  • 📦 開発セットアップ

  • 📦 利用可能なツール

    • 序数を表示

  • 🚨 エラー処理

  • 🤝 貢献する

  • 📝 ライセンス

🔧 機能

• 序数検出: Bitcoin トランザクションを自動的に検出し、序数に解析します。テキストベース、画像、JSON、その他の表記形式をサポートします。

🦆 Goose 統合

Gooseは、Block社によるオープンソースのAIエージェントフレームワークで、モデルコンテキストプロトコル（Model Context Protocol）を介した拡張機能をサポートしています。MCP-InscriptionサーバーをGoose拡張機能として統合することで、GooseがOrdinals Inscriptionと連携できるようになります。Gooseは、MCPサーバーとの統合に2つのモードをサポートしています。サーバーをローカルプロセス（STDIO）として実行するか、Server-Sent Events（SSE）を介してリモートサービスとして接続するかです。以下に、両方の方法の手順を示します。

STDIO (ローカル拡張) の使用

このメソッドは、MCP-Inscription サーバーを Goose のサブプロセスとしてローカルで実行し、標準入出力を介して通信します。

1. MCP-Inscription リポジトリをクローンしてビルドします (まだ行っていない場合)。

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

   次のステップで必要になるので、リポジトリへの完全な絶対パスをメモしておいてください。

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 ) ( 拡張機能の使用 | goose )）。

6. **新しい拡張機能を使ってGooseセッションを開始します。**これで、Gooseで拡張機能を使用できるようになりました。CLI経由でGooseを実行している場合は、次のコマンドを実行して、拡張機能を含むセッションを開始します。

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

「序数」を拡張機能に付けた名前（ 拡張機能の使用 | goose ）に置き換えます。（これにより、セッションで拡張機能が確実に読み込まれます。また、拡張機能がグローバルに有効になっている場合は、Goose Desktop または CLI によってすべてのセッションで拡張機能が自動的に使用できるようになります。）

SSE (リモート拡張) の使用

このメソッドは、HTTP SSEストリームを介してGooseを既に実行中のMCPサーバーに接続します。MCP-Inscriptionサーバーをスタンドアロンサービスとして（別のマシン上、あるいはGooseとは独立して）実行する場合、このメソッドを使用します。

1. MCP サーバーをスタンドアロン サービスとして起動します。MCP -Inscription サーバーを SSE モードで実行して接続をリッスンします。

   # 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. **拡張機能の有効化：**リモート拡張機能を追加したら、Gooseの設定で有効化されていることを確認してください（STDIOの場合と同様）。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サーバーのディレクトリと追加の設定ヒントが記載されています。これらのドキュメントは、他の拡張機能を調べたり、独自の拡張機能を開発したりする場合に役立ちます。

🔑 クロード デスクトップ統合

Claude Desktop (Claude 用の Anthropic のデスクトップ アプリ) で MCP-Inscription サーバーを使用するには、次の手順に従います。

1. Claude Desktopのダウンロードとインストール： Claude Desktopの公式ダウンロードページにアクセスし、お使いのオペレーティングシステム（macOSまたはWindows）用のアプリを入手してください（ Claude for Desktopのインストール | Anthropicヘルプセンター）。アプリをインストールし、最新バージョンを使用していることを確認してください（アプリメニューでアップデートを確認できます）。

2. MCP-Inscription リポジトリのクローンとビルド:

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

3. MCP-Inscription Server を使用するように 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_config.json自動的に起動します。Claude Desktopが起動していた場合は、変更を有効にするために再起動する必要があります。

Claudeデスクトップ統合のテスト

Claude Desktop を再起動すると、MCP-Inscription サーバーが正しく動作しているかどうかをテストできます。

• 応答を確認してください。Claudeは詳細な回答（例えば、刻印自体やルーン情報など）をエラーなく返すはずです。エラーメッセージが表示されたり、有効な応答がない場合は、MCP サーバーに正しく接続されていない可能性があります。

• Claude のログを確認する（必要な場合）： Claude Desktop は、MCP 統合のデバッグに役立つログファイルを提供します。ツールが応答しない場合は、以下のログファイルを確認してください。

  • macOS: ~/Library/Logs/Claude/

  • Windows: %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 ライセンスに基づいてライセンスされています。