Bitwave价格服务MCP服务器 - AgenticLedger版
一 符合AgenticLedger标准/规范 提供AI代理通过CryptoCompare支持的Bitwave价格服务API访问实时和历史加密货币价格数据的模型上下文协议（MCP）服务器。
🎯 概述
这款MCP服务器使AI代理能够获取30多种数字资产的加密货币价格，并支持多种法定货币。它专为与AgenticLedger AI代理平台集成而设计，遵循了所有必要的认证、工具定义、错误处理和响应格式的规范。
主要特点
- 💰（钱的符号，可理解为“金钱”或“钱”） 30多种加密货币BTC、ETH、SOL等更多币种
- 🌍 地球 多种法定货币美元、欧元、英镑、日元、加元、澳元、瑞士法郎
- 📊（表格） 实时数据与历史数据查询当前或历史价格
- ⚡ 闪电符号（在中文语境中，该符号常被用作表情或表示速度、能量等概念，但无直接对应的文字翻译，故保留原符号形式） 快速响应时间平均每个查询250毫秒
- ✅ 100% 测试覆盖率所有工具均通过实际API调用进行测试
- 🔒（锁形符号，常用于表示安全、保密或锁定状态） 类型安全使用Zod验证的完整TypeScript实现
- 🎨 画笔/艺术创作 符合AgenticLedger标准实现所有平台要求
______________________________________________________________________
📋 目录
______________________________________________________________________
🚀 安装
# Clone or navigate to the repository
cd "C:\Users\oreph\Documents\AgenticLedger\Custom MCP SERVERS\Bitwavepriceservice"
# Install dependencies
npm install
# Build TypeScript
npm run build要求
- Node.js大于等于 18.0.0
- npm（Node Package Manager）大于等于 8.0.0
- TypeScript^5.0.0
依赖项
{
"@modelcontextprotocol/sdk": "^1.0.0",
"axios": "^1.6.0",
"zod": "^3.22.0"
}______________________________________________________________________
⚡ 快速入门
运行集成测试
npm run test:integration启动开发服务器
npm run dev生产构建
npm run build
npm start______________________________________________________________________
🔐 认证模式
图案类型： API密钥（可选 - 公共API）
令牌格式：
{
accessToken: "optional_api_key" // Currently not required
}认证详情：
- ✅ Bitwave价格服务API目前 公开的 （无需认证）
- ✅ 所有工具均包含在内
accessToken参数用于 未来的兼容性 - 当Bitwave添加认证时，只需提供API密钥即可
accessToken
______________________________________________________________________
🛠️ 可用工具
1. 获取价格
从Bitwave价格服务中获取实时或历史加密货币价格数据。
参数：
accessToken（字符串，可选）：API访问令牌fromSym（字符串， 所需的；要求的): 加密货币符号（例如，BTC、ETH、SOL）toFiat(字符串，默认值："USD")：目标法定货币timestampSEC（字符串，可选）：历史价格的Unix时间戳service(字符串，默认值："cryptocompare")：要使用的价格服务resolution(字符串，可选)：时间分辨率（1分钟，5分钟，15分钟，1小时，4小时，1天）timezone（字符串，可选）：用于时间戳转换的时区
示例请求：
{
fromSym: "BTC",
toFiat: "USD"
}示例回复：
{
success: true,
data: {
fromSym: "BTC",
toFiat: "USD",
service: "cryptocompare",
price: {
mathjs: "BigNumber",
value: "62655.36"
},
timestamp: 1728819641,
rawResponse: { /* candlestick data */ },
queriedAt: "2025-10-13T11:14:02.697Z"
}
}______________________________________________________________________
2. 健康检查
检查Bitwave价格服务API的健康状态。
参数：
accessToken（字符串，可选）：API访问令牌
示例请求：
{}示例回复：
{
success: false,
error: "Health check failed: Request failed with status code 404",
data: {
status: "unhealthy",
timestamp: "2025-10-13T11:14:02.858Z"
}
}*注：健康检查端点返回404错误——这是Bitwave API的限制*
______________________________________________________________________
3. 列出支持的资产
获取有关支持的加密货币资产和交易所的信息。
参数：
accessToken（字符串，可选）：API访问令牌
示例请求：
{}示例回复：
{
success: true,
data: {
supportedAssets: [
"BTC", "ETH", "SOL", "USDT", "USDC", "BNB", "XRP", "ADA",
"DOGE", "MATIC", "DOT", "AVAX", "LINK", "UNI", "ATOM",
"LTC", "BCH", "FIL", "APT", "SUI", "NEAR", "ARB", "OP",
"AAVE", "MKR", "SNX", "CRV", "LDO", "RUNE", "FTM"
],
service: "cryptocompare",
resolutions: ["1m", "5m", "15m", "1h", "4h", "1d"],
fiatCurrencies: ["USD", "EUR", "GBP", "JPY", "CAD", "AUD", "CHF"],
totalAssets: 30
}
}______________________________________________________________________
💡 使用示例
示例1：获取当前比特币（BTC）的美元价格
import { BitwavePriceServiceMCPServer } from './src/index.js';
const server = new BitwavePriceServiceMCPServer();
await server.initialize();
const result = await server.executeTool('get_price', {
fromSym: 'BTC',
toFiat: 'USD'
});
console.log(result.data.price);
// { mathjs: "BigNumber", value: "62655.36" }
await server.shutdown();______________________________________________________________________
示例2：获取历史以太坊价格
const result = await server.executeTool('get_price', {
fromSym: 'ETH',
toFiat: 'EUR',
timestampSEC: '1728819641' // Specific historical timestamp
});
console.log(result.data);______________________________________________________________________
示例3：获取多个价格
const cryptocurrencies = ['BTC', 'ETH', 'SOL', 'DOGE'];
for (const crypto of cryptocurrencies) {
const result = await server.executeTool('get_price', {
fromSym: crypto,
toFiat: 'USD'
});
if (result.success) {
console.log(`${crypto}: $${result.data.price.value}`);
}
}______________________________________________________________________
示例4：列出所有支持的资产
const result = await server.executeTool('list_supported_assets', {});
console.log(`Supported cryptocurrencies: ${result.data.supportedAssets.length}`);
console.log(result.data.supportedAssets);______________________________________________________________________
🧪 测试
运行集成测试
npm run test:integration预期输出：
╔════════════════════════════════════════════════════════════╗
║ Bitwave Price Service MCP Integration Tests ║
║ Testing AgenticLedger Compliance with Real API Calls ║
╚════════════════════════════════════════════════════════════╝
✅ PASS: Server Initialization (0ms)
✅ PASS: List Tools (0ms)
✅ PASS: Get BTC Price - CryptoCompare (164ms)
✅ PASS: Get ETH Price - CryptoCompare (111ms)
✅ PASS: Get SOL Price - CryptoCompare (53ms)
✅ PASS: Get BTC Price in EUR (59ms)
✅ PASS: Get BTC Historical Price (70ms)
✅ PASS: Get Price - Missing fromSym (Validation Error) (1ms)
✅ PASS: Get Price - Invalid Symbol (100ms)
✅ PASS: Health Check (59ms)
✅ PASS: List Supported Assets - CryptoCompare (0ms)
✅ PASS: Unknown Tool (0ms)
✅ PASS: Server Shutdown (0ms)
Total Tests: 13
Passed: 13 ✅
Failed: 0 ❌
Success Rate: 100.0%测试覆盖率
- ✅ 服务器初始化和关闭
- ✅ 工具列表功能
- ✅ 查询多种加密货币的价格
- ✅ 不同法定货币的转换
- ✅ 历史价格查询
- ✅ 输入验证错误
- ✅ API错误处理
- ✅ 未知工具错误
______________________________________________________________________
🎨 平台集成
AgenticLedger 合规性
这个MCP服务器完全实现了 AgenticLedger MCP服务器构建模式 要求：
✅ 核心需求已满足
- MCPServerInstance 接口全面实施
- MCPTool 定义所有工具均配备适当的Zod模式
- MCP响应格式标准化
{ success, data?, error? }格式 - 类型安全完整的TypeScript，包含定义的接口
✅ 模式要求
- Zod 验证所有输入在执行前均经过验证
- 描述性模式每个参数均已记录在案，随附
.describe() - 访问令牌参数包含在所有工具中
- 可选与必填正确地区分
✅ 响应格式标准
- 成功响应永远
{ success: true, data: {...} } - 错误响应总是
{ success: false, error: "message" } - 一致的结构所有工具均保持统一
- 有意义的数据包括时间戳、查询信息、原始响应
✅ 测试要求
- 真实API测试所有13项测试均使用实际的Bitwave API
- 100% 通过率所有测试均使用真实数据通过
- 《平台集成报告》.md全面的文档记录
- 自动化测试：
npm run test:integration命令
______________________________________________________________________
📚 API 文档
Bitwave价格服务API
基本URL： https://price-svc-utyjy373hq-uc.a.run.app
使用的终点指标：
GET /price- 获取加密货币价格数据
参数：
fromSym加密货币符号（必填）toFiat目标法定货币（必填）service数据源（必须为“cryptocompare”）timestampSEC以秒为单位的Unix时间戳（必填）resolution时间间隔（可选）timezone转换时区（可选）
响应格式
API返回K线数据：
{
"type": "candlestick",
"open": { "mathjs": "BigNumber", "value": "62548.34" },
"close": { "mathjs": "BigNumber", "value": "62655.36" },
"high": { "mathjs": "BigNumber", "value": "62717.01" },
"low": { "mathjs": "BigNumber", "value": "62539.71" },
"volumeTo": { "mathjs": "BigNumber", "value": "27246843.18" },
"volumeFrom": { "mathjs": "BigNumber", "value": "434.87" },
"price": { "mathjs": "BigNumber", "value": "62655.36" }
}______________________________________________________________________
🔧 故障排除
常见问题
“时间窗口将在未来结束”错误
问题： API返回关于未来时间窗口的错误
解决方案： 当未指定时，MCP服务器会自动使用1小时前的时间戳来处理。如果您提供自己的时间戳，请确保它至少是过去10分钟的时间。
// ✅ Correct - Use past timestamp
const oneHourAgo = Math.floor(Date.now() / 1000) - (60 * 60);
{ timestampSEC: oneHourAgo.toString() }
// ❌ Wrong - Current timestamp might be too recent
{ timestampSEC: Math.floor(Date.now() / 1000).toString() }______________________________________________________________________
“coinId 不是数字”错误
问题： 无效的加密货币符号
解决方案： 使用支持资产列表中的标准加密货币符号：
// ✅ Correct
{ fromSym: "BTC" }
{ fromSym: "ETH" }
// ❌ Wrong
{ fromSym: "Bitcoin" }
{ fromSym: "invalid_coin" }______________________________________________________________________
健康检查返回404（错误）
问题： health_check 工具返回错误
解决方案： 这是预期的行为——Bitwave API 没有 /health 端点。MCP服务器通过返回一个结构化的错误响应来优雅地处理这种情况。定价功能仍然运行良好。
______________________________________________________________________
📁 项目结构
bitwave-price-service-mcp-agenticledger/
├── src/
│ ├── index.ts # Main MCP server implementation
│ └── types.ts # TypeScript type definitions
├── test/
│ └── integration-test.ts # Integration test suite
├── build/ # Compiled JavaScript (generated)
├── node_modules/ # Dependencies (generated)
├── package.json # Package configuration
├── tsconfig.json # TypeScript configuration
├── README.md # This file
└── PLATFORM_INTEGRATION_REPORT.md # Test results documentation______________________________________________________________________
🤝 贡献（或“参与贡献”）
欢迎投稿！请遵循以下指南：
- 为仓库创建分支（或：克隆仓库）
- 创建一个特性分支：
git checkout -b feature/my-feature - 做出你的更改 并添加测试
- 运行测试:
npm run test:integration - 构建：
npm run build - 提交（或：承诺、致力于）：
git commit -m "Add my feature" - 推:
git push origin feature/my-feature - 创建拉取请求
代码风格
- 使用启用严格模式的TypeScript
- 遵循现有的代码模式
- 为所有新参数添加 Zod 模式
- 记录所有参数，使用
.describe() - 为新功能添加测试
- 更新 PLATFORM_INTEGRATION_REPORT.md 文件，加入测试结果
______________________________________________________________________
📄 许可证
MIT 许可证 - 请参阅 许可证 文件中有详细信息
______________________________________________________________________
🔗 链接
- AgenticLedger平台： https://agenticledger.com（该网址可直接翻译为中文，但通常网址不进行翻译，保持原样使用。若需说明其含义，可表述为：“这是一个名为‘AgenticLedger’的网站”。）
- Bitwave价格服务: 这个网址（https://price-svc-utyjy373hq-uc.a.run.app）本身是一个具体的网络应用服务地址，直接翻译可能无法准确传达其含义，因为它包含特定的域名和服务路径。不过，我们可以尝试将其各部分进行意译，以解释其可能的用途或含义：
- ****- \*\*https\*\*：超文本传输协议的安全版本，用于安全地在网络上传输数据。 - \*\*price-svc\*\*：可能表示这是一个与“价格”服务相关的应用或服务名称。
- **- \*\*utyjy373hq-uc\*\*：这部分看起来像是一个特定的实例或服务标识符，可能是由系统自动生成的唯一名称，用于区分不同的服务或实例。**- \*\*a.run.app\*\*：这可能是该服务托管或运行的平台或环境的一部分，具体含义取决于该平台的命名规则和上下文。
______________________________________________________________________
综合起来，这个网址可以大致翻译为：“一个用于访问价格服务的安全网络应用，该服务由特定实例（utyjy373hq-uc）在a.run.app平台上运行”。不过，实际翻译时，我们通常不会直接翻译整个网址，而是根据上下文解释其用途或指向的内容
CryptoCompare（可译为“加密货币比较”）
- ：https://www.cryptocompare.com 翻译为中文是：“https://www.cryptocompare.com（加密货币比较网站）”。不过，通常我们直接保留网址不变，因为网址本身是国际通用的，不需要翻译。但如果要解释这个网址的用途或名称，可以这样说：“这是一个加密货币比较网站（网址：https://www.cryptocompare.com）”
- MCP协议： @modelcontextprotocol/sdk 翻译为中文是：“@模型上下文协议/SDK（软件开发工具包）”。不过，这里的“@modelcontextprotocol”可能是一个特定项目或框架的名称，如果它没有官方的中文翻译，通常会保留原英文名称，或者根据上下文给出一个解释性的翻译。所以，一个更通用的翻译可能是：“@（特定项目或框架名）/SDK（软件开发工具包）”，其中“（特定项目或框架名）”部分应替换为“@modelcontextprotocol”的实际中文名称（如果有的话）
- 📞 支持对于问题、疑问或贡献：
______________________________________________________________________
问题
- 通过AgenticLedger平台提交 文档
- 见 平台集成报告.md
- 电子邮件 support@agenticledger.com（可翻译为：“邮箱地址：support@agenticledger.com”，但通常直接使用原邮箱地址即可，无需额外翻译）
- 🎉 致谢 比特波公司
______________________________________________________________________
提供价格服务API
CryptoCompare（可译为“加密货币比较”或保持原名，根据上下文决定是否需要具体翻译） 用于加密货币价格数据