Bitwave价格服务MCP服务器 - AgenticLedger版

![AgenticLedger](https://agenticledger.com) ![TypeScript](https://www.typescriptlang.org/) ![Tests](./test/integration-test.ts) ![License](./LICENSE)

一 符合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\*\*：这可能是该服务托管或运行的平台或环境的一部分，具体含义取决于该平台的命名规则和上下文。 [](https://www.npmjs.com/package/@modelcontextprotocol/sdk)

______________________________________________________________________

综合起来，这个网址可以大致翻译为：“一个用于访问价格服务的安全网络应用，该服务由特定实例（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（可译为“加密货币比较”或保持原名，根据上下文决定是否需要具体翻译） 用于加密货币价格数据

Agenticledger MCP BitwavePriceService

快速接入

详细介绍

Bitwave价格服务MCP服务器 - AgenticLedger版

🎯 概述

主要特点

📋 目录

🚀 安装

要求

依赖项

⚡ 快速入门

运行集成测试

启动开发服务器

生产构建

🔐 认证模式

🛠️ 可用工具

1. 获取价格

2. 健康检查

3. 列出支持的资产

💡 使用示例

示例1：获取当前比特币（BTC）的美元价格

示例2：获取历史以太坊价格

示例3：获取多个价格

示例4：列出所有支持的资产

🧪 测试

运行集成测试

测试覆盖率

🎨 平台集成

AgenticLedger 合规性

✅ 核心需求已满足

✅ 模式要求

✅ 响应格式标准

✅ 测试要求

📚 API 文档

Bitwave价格服务API

响应格式

🔧 故障排除

常见问题

“时间窗口将在未来结束”错误

“coinId 不是数字”错误

健康检查返回404（错误）

📁 项目结构

🤝 贡献（或“参与贡献”）

代码风格

📄 许可证

🔗 链接

问题

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP