Stampchain MCP

邮票链MCP服务器

 ](https://badge.fury.io/js/stampchain-mcp)   ](https://nodejs.org/)  

用于与比特币邮票和加密货币进行交互的模型上下文协议（MCP）服务器 通过Stampchain API的SRC-20代币数据。此服务器提供MCP兼容 客户可以使用工具查询比特币邮票、收藏品和SRC-20代币。

特性

• 比特币邮票工具：获取邮票详细信息、搜索邮票并检索

近期邮票

• 邮票收藏：查询集合并搜索集合数据
• SRC-20代币：获取令牌信息并搜索SRC-20令牌
• 类型安全：使用TypeScript和Zod验证构建
• 综合测试：CI验证的全面测试覆盖率
• 可配置的：针对不同环境的灵活配置选项
• 跨平台：可在Ubuntu、Windows和macOS上使用Node.js 18+

快速开始

先决条件

• Node.js 18+
• npm或纱线

安装

1. 克隆存储库：

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

1. 安装依赖项：

   npm install

1. 构建项目：

   npm run build

1. 测试安装：

   npm run start

MCP客户端集成

克劳德桌面

要与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传输接受连接。

可用工具

比特币邮票

• 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 -日志记录级别（调试、信息、警告、错误）
• STAMPCHAIN_API_TIMEOUT -API超时（以毫秒为单位）

命令行用法

# Start with default configuration
npm run start

# Start with custom config file
npm run start -- --config config.json

# Start with debug logging
npm run start -- --log-level debug

# Show available tools
npm run tools

# Show version information
npm run version

发展

脚本

• 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 -完整的验证套件

测试

该项目包括全面的测试覆盖范围：

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

项目结构

src/
├── api/           # API client and related utilities
├── config/        # Configuration management
├── interfaces/    # TypeScript interfaces
├── protocol/      # MCP protocol handlers
├── schemas/       # Zod validation schemas
├── tools/         # MCP tool implementations
├── utils/         # Utility functions
├── index.ts       # Main entry point
└── server.ts      # Server implementation

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"
  }
}

发展

测试覆盖率

该项目在多个领域保持全面的测试覆盖：

• ✅ 单元测试 -核心实用程序和辅助功能
• ✅ 集成测试 -MCP服务器功能
• ✅ API验证 -确保v2.3 API兼容性
• ✅ 架构验证 -TypeScript和Zod模式对齐
• ✅ 跨平台 -在Ubuntu、Windows和macOS上测试
• ✅ 多版本 -Node.js 18.x、20.x和22.x支持
• ✅ 真正的API测试 -根据Stampchain API v2.3进行验证

详细测试命令

# Run specific test suites
npm run test:unit         # Unit tests for utilities and helpers
npm run test:integration  # Integration tests for MCP server
npm run test:api         # API validation tests (v2.3 compatibility)
npm run test:tools       # Tool functionality tests
npm run test:schemas     # Schema validation tests

# Advanced testing options
npm run test:ui          # Run tests in UI mode (interactive)
npm run test:ci          # CI test run (includes coverage)
npm run validate         # Full validation (schema + typecheck + format + tests)

开发工作流程

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严格模式指南
• 为新功能编写测试
• 根据需要更新文档
• 跑 npm run validate 在提交PR之前

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• 问题:

• 文档: Stampchain API文档
• 社区: 电报 @BitcoinStamps

更新日志

v0.2.0版本

• Stampchain API v2.3兼容性：更新了最新API的架构和验证
• 增强测试：具有跨平台CI验证的全面测试套件
• 改进文档：带有身份徽章和更好组织的专业自述文件
• 简化开发：简化验证流程（TypeScript+Prettier）
• 漏洞修补：解决了CI问题并改进了模式验证

v0.1.0

• 初始版本
• 基本的比特币邮票，收藏和SRC-20工具
• MCP客户端集成
• 全面的测试套件