Stampchain Mcp

开发 TypeScript

🚀 Stampchain MCP Server

Stampchain MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，可通过 Stampchain API 与比特币邮票（Bitcoin Stamps）和 SRC - 20 代币数据进行交互。它为兼容 MCP 的客户端提供了查询比特币邮票、邮票集合和 SRC - 20 代币的工具。

🚀 快速开始

前提条件

Node.js 18 及以上版本
npm 或 yarn

安装

克隆仓库：

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

安装依赖：

npm install

构建项目：

npm run build

测试安装：

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

📦 安装指南

配置文件

服务器可以通过以下方式进行配置：

配置文件（JSON 格式）
环境变量
命令行参数

示例配置文件

{
"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          # 全面验证（模式 + 类型检查 + 格式化 + 测试）

开发工作流程

安装依赖：npm install
启动开发服务器：npm run dev
在监视模式下运行测试：npm run test:watch
提交代码前进行验证：npm run validate

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🛠️ 故障排除

常见问题

构建错误：确保已安装 Node.js 18 及以上版本，并先运行 npm install。
连接问题：检查 Stampchain API 是否可访问。
MCP 客户端集成：验证配置文件中的路径是否正确。

调试

启用调试日志以查看详细信息：

npm run start -- --debug

或者在配置中设置日志级别：

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

👥 贡献指南

分叉仓库。
创建功能分支：git checkout -b feature/new-feature
进行更改。
运行测试：npm test
提交更改：git commit -am 'Add new feature'
推送到分支：git push origin feature/new-feature
提交拉取请求

代码风格

所有新代码使用 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 客户端集成
全面的测试套件

0 条评论
分类：开发