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 客户端集成
• 全面的测试套件