Stampchain MCP

🚀 Stampchain MCP Server

Stampchain MCP Server 是一個基於 Model Context Protocol (MCP) 的服務器，可通過 Stampchain API 與比特幣郵票（Bitcoin Stamps）和 SRC - 20 代幣數據進行交互。它為兼容 MCP 的客戶端提供了查詢比特幣郵票、郵票集合和 SRC - 20 代幣的工具。

🚀 快速開始

前提條件

• 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 傳輸接受連接。

✨ 主要特性

• 比特幣郵票工具：獲取郵票詳細信息、搜索郵票以及檢索最近創建的郵票。
• 郵票集合：查詢集合信息並通過過濾器搜索集合數據。
• SRC - 20 代幣：獲取特定 SRC - 20 代幣的詳細信息，並通過各種過濾器搜索代幣。
• 類型安全：使用 TypeScript 和 Zod 驗證構建。
• 全面測試：擁有完整的測試覆蓋，並通過 CI 進行驗證。
• 可配置：針對不同環境提供靈活的配置選項。
• 跨平臺：在安裝了 Node.js 18 及以上版本的 Ubuntu、Windows 和 macOS 系統上均可運行。

💻 使用示例

基礎用法

以下是克隆和安裝項目的基礎操作：

git clone https://github.com/stampchain-io/stampchain-mcp.git
cd stampchain-mcp
npm install
npm run build
npm run start

高級用法

在 Claude Desktop 中集成時，使用 npx 進行更便捷的配置：

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

📦 安裝指南

配置文件

服務器可以通過以下方式進行配置：

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

📚 詳細文檔

可用工具

比特幣郵票

• get_stamp - 通過 ID 獲取特定郵票的詳細信息。
• search_stamps - 使用各種過濾器（創作者、集合等）搜索郵票。
• get_recent_stamps - 獲取最近創建的郵票。

郵票集合

• get_collection - 獲取特定集合的詳細信息。
• search_collections - 使用過濾器搜索集合。

SRC - 20 代幣

• get_token_info - 獲取特定 SRC - 20 代幣的詳細信息。
• search_tokens - 使用各種過濾器搜索 SRC - 20 代幣。

API 參考

工具參數

所有工具都接受各種參數進行過濾和分頁：

• limit - 返回結果的數量（默認值：10，最大值：100）
• page - 分頁的頁碼（默認值：1）
• sort - 排序字段和方向（例如："created_desc"）

響應格式

所有工具返回的結構化數據包含以下內容：

• success - 布爾值，指示請求是否成功。
• data - 請求的數據（郵票、集合、代幣）。
• pagination - 適用時的分頁信息。
• error - 請求失敗時的錯誤詳細信息。

🔧 技術細節

項目結構

src/
├── api/           # API 客戶端及相關實用工具
├── config/        # 配置管理
├── interfaces/    # TypeScript 接口
├── protocol/      # MCP 協議處理程序
├── schemas/       # Zod 驗證模式
├── tools/         # MCP 工具實現
├── utils/         # 實用函數
├── index.ts       # 主入口點
└── server.ts      # 服務器實現

測試覆蓋

本項目在多個方面保持了全面的測試覆蓋：

• ✅ 單元測試 - 核心實用工具和輔助函數。
• ✅ 集成測試 - 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

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

🛠️ 故障排除

常見問題

1. 構建錯誤：確保已安裝 Node.js 18 及以上版本，並先運行 npm install。
2. 連接問題：檢查 Stampchain API 是否可訪問。
3. MCP 客戶端集成：驗證配置文件中的路徑是否正確。

調試

啟用調試日誌以查看詳細信息：

npm run start -- --debug

或者在配置中設置日誌級別：

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

👥 貢獻指南

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 嚴格模式指南。
• 為新功能編寫測試。
• 根據需要更新文檔。
• 在提交 PR 之前運行 npm run validate。

📝 更新日誌

v0.2.0

• Stampchain API v2.3 兼容性：更新模式和驗證以適配最新 API。
• 增強測試：全面的測試套件，通過跨平臺 CI 驗證。
• 改進文檔：專業的 README，包含狀態徽章和更好的組織。
• 簡化開發：簡化驗證流程（TypeScript + Prettier）。
• 修復 bug：解決 CI 問題並改進模式驗證。

v0.1.0

• 初始版本
• 基本的比特幣郵票、集合和 SRC - 20 工具
• MCP 客戶端集成
• 全面的測試套件