Stampchain MCP

🚀 Stampchain MCP Server

Stampchain MCP Serverは、Stampchain APIを介してBitcoinスタンプやSRC - 20トークンデータとやり取りするためのModel Context Protocol (MCP)サーバーです。このサーバーは、MCP互換のクライアントに、Bitcoinスタンプ、コレクション、およびSRC - 20トークンをクエリするためのツールを提供します。

✨ 主な機能

• Bitcoinスタンプツール：スタンプの詳細を取得、スタンプを検索、最近のスタンプを取得
• スタンプコレクション：コレクションをクエリし、コレクションデータを検索
• SRC - 20トークン：トークン情報を取得し、SRC - 20トークンを検索
• 型安全：TypeScriptとZod検証を使用して構築
• 包括的なテスト：CI検証による完全なテストカバレッジ
• 設定可能：異なる環境に対応した柔軟な設定オプション
• クロスプラットフォーム：Node.js 18+を搭載したUbuntu、Windows、およびmacOSで動作

🚀 クイックスタート

前提条件

• Node.js 18+
• npmまたはyarn

📦 インストール

1. リポジトリをクローンします：

   git clone https://github.com/stampchain-io/stampchain-mcp.git
   cd stampchain-mcp
   

2. 依存関係をインストールします：

   npm install
   

3. プロジェクトをビルドします：

   npm run build
   

4. インストールをテストします：

   npm run start
   

MCPクライアントの統合

Claude Desktop

Claude Desktopで使用するには、claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "stampchain": {
      "command": "node",
      "args": ["/path/to/stampchain-mcp/dist/index.js"],
      "cwd": "/path/to/stampchain-mcp"
    }
  }
}

代替案：npxを使用する（推奨） ローカルインストールなしで簡単にセットアップするには：

{
  "mcpServers": {
    "stampchain": {
      "command": "npx",
      "args": ["-y", "stampchain-mcp"]
    }
  }
}

注：/path/to/stampchain-mcpを実際のインストールディレクトリのパスに置き換えてください。

その他のMCPクライアント

このサーバーは標準のMCPプロトコルを実装しており、MCP互換のクライアントで使用できます。具体的な設定手順については、クライアントのドキュメントを参照してください。サーバーはstdioトランスポートを介した接続を受け付けます。

💻 使用例

利用可能なツール

Bitcoinスタンプ

• get_stamp - IDで特定のスタンプの詳細情報を取得
• search_stamps - さまざまなフィルター（作成者、コレクションなど）でスタンプを検索
• get_recent_stamps - 最近作成されたスタンプを取得

スタンプコレクション

• get_collection - 特定のコレクションの詳細情報を取得
• search_collections - フィルターでコレクションを検索

SRC - 20トークン

• get_token_info - 特定のSRC - 20トークンの詳細情報を取得
• search_tokens - さまざまなフィルターでSRC - 20トークンを検索

🔧 設定

サーバーは以下を通じて設定できます。

1. 設定ファイル（JSON形式）
2. 環境変数
3. コマンドライン引数

設定ファイルの例

{
  "api": {
    "baseUrl": "https://stampchain.io/api",
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info"
  },
  "registry": {
    "maxTools": 1000,
    "validateOnRegister": true
  }
}

環境変数

• STAMPCHAIN_API_URL - APIのベースURL（デフォルト: https://stampchain.io/api）
• STAMPCHAIN_LOG_LEVEL - ログレベル（debug、info、warn、error）
• STAMPCHAIN_API_TIMEOUT - APIのタイムアウト（ミリ秒）

コマンドラインの使用方法

# デフォルト設定で起動
npm run start

# カスタム設定ファイルで起動
npm run start -- --config config.json

# デバッグログで起動
npm run start -- --log-level debug

# 利用可能なツールを表示
npm run tools

# バージョン情報を表示
npm run version

📚 ドキュメント

APIリファレンス

ツールのパラメータ

すべてのツールは、フィルタリングとページネーションのためのさまざまなパラメータを受け付けます。

• limit - 返される結果の数（デフォルト: 10、最大: 100）
• page - ページネーションのページ番号（デフォルト: 1）
• sort - ソートフィールドと方向（例: "created_desc"）

レスポンス形式

すべてのツールは、以下の構造化データを返します。

• success - リクエストが成功したかどうかを示すブール値
• data - 要求されたデータ（スタンプ、コレクション、トークン）
• pagination - 該当する場合のページネーション情報
• error - リクエストが失敗した場合のエラー詳細

トラブルシューティング

一般的な問題

1. ビルドエラー：Node.js 18+がインストールされていることを確認し、最初にnpm installを実行してください。
2. 接続問題：Stampchain APIにアクセスできることを確認してください。
3. MCPクライアントの統合：設定ファイル内のパスが正しいことを確認してください。

デバッグ

詳細情報を表示するには、デバッグログを有効にします。

npm run start -- --debug

または、設定ファイルでログレベルを設定します。

{
  "logging": {
    "level": "debug"
  }
}

開発

スクリプト

• npm run dev - ホットリロードで開発サーバーを起動
• npm run build - TypeScriptプロジェクトをビルド
• npm run test - すべてのテストを実行
• npm run test:watch - ウォッチモードでテストを実行
• npm run test:coverage - カバレッジレポート付きでテストを実行
• npm run typecheck - TypeScriptの型チェック
• npm run format - Prettierでコードを整形
• npm run validate - 完全な検証スイート

テスト

このプロジェクトは、複数の領域にわたる包括的なテストカバレッジを維持しています。

• ✅ 単体テスト - コアユーティリティとヘルパー関数
• ✅ 統合テスト - MCPサーバーの機能
• ✅ API検証 - v2.3 API互換性を保証
• ✅ スキーマ検証 - TypeScriptとZodスキーマの整合性
• ✅ クロスプラットフォーム - Ubuntu、Windows、およびmacOSでテスト
• ✅ マルチバージョン - Node.js 18.x、20.x、および22.xをサポート
• ✅ 実際のAPIテスト - 実際のStampchain API v2.3に対して検証

詳細なテストコマンド

# 特定のテストスイートを実行
npm run test:unit         # ユーティリティとヘルパーの単体テスト
npm run test:integration  # MCPサーバーの統合テスト
npm run test:api         # API検証テスト（v2.3互換性）
npm run test:tools       # ツールの機能テスト
npm run test:schemas     # スキーマ検証テスト

# 高度なテストオプション
npm run test:ui          # UIモードでテストを実行（対話型）
npm run test:ci          # CIテスト実行（カバレッジを含む）
npm run validate         # 完全な検証（スキーマ + 型チェック + 整形 + テスト）

開発ワークフロー

1. 依存関係をインストール：npm install
2. 開発サーバーを起動：npm run dev
3. ウォッチモードでテストを実行：npm run test:watch
4. コミット前に検証：npm run validate

コントリビュート

1. リポジトリをフォークします。
2. 機能ブランチを作成します：git checkout -b feature/new-feature
3. 変更を加えます。
4. テストを実行します：npm test
5. 変更をコミットします：git commit -am 'Add new feature'
6. ブランチにプッシュします：git push origin feature/new-feature
7. プルリクエストを送信します。

コードスタイル

• すべての新しいコードにTypeScriptを使用してください。
• TypeScriptのstrictモードガイドラインに従ってください。
• 新機能に対してテストを書いてください。
• 必要に応じてドキュメントを更新してください。
• PRを送信する前にnpm run validateを実行してください。

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

サポート

• 問題報告：GitHub Issues
• ドキュメント：Stampchain API Docs
• コミュニティ：Telegram @BitcoinStamps

変更履歴

v0.2.0

• Stampchain API v2.3互換性：最新のAPIに対応したスキーマと検証を更新
• 強化されたテスト：クロスプラットフォームのCI検証を備えた包括的なテストスイート
• 改善されたドキュメント：ステータスバッジとより良い組織化を備えたプロフェッショナルなREADME
• 簡素化された開発：合理化された検証パイプライン（TypeScript + Prettier）
• バグ修正：CI問題を解決し、スキーマ検証を改善

v0.1.0

• 初期リリース
• 基本的なBitcoinスタンプ、コレクション、およびSRC - 20ツール
• MCPクライアントの統合
• 包括的なテストスイート