Bitrefill MCP 服务器

这是一个基于 TypeScript 的 MCP 服务器，提供对接 Bitrefill 服务的访问，允许您搜索礼品卡、手机充值等。此服务器实现了模型上下文协议（Model Context Protocol），以将 Bitrefill 功能暴露给 AI 助手。

工作原理

该服务器使用模型上下文协议（MCP）与 Claude 和类似的 AI 助手进行通信。它：

1. 使用标准 I/O 作为独立进程运行进行通信
2. 注册资源和工具以访问 Bitrefill 服务
3. 通过 Bitrefill API 提供产品搜索和详细信息
4. 返回结构化的 JSON 响应，这些响应可以由 AI 助手处理

架构

应用服务器遵循以下架构：

src/
├── index.ts                # 主入口点
├── constants/              # 静态数据
│   ├── categories.ts       # 产品类别
│   └── payment_methods.ts  # 支付方式
├── handlers/               # MCP 请求处理器
│   ├── resources.ts        # 资源端点
│   └── tools.ts            # 工具实现
├── schemas/                # 数据验证模式
│   ├── detail.ts           # 产品详情响应类型
│   ├── invoice.ts          # 发票模式
│   ├── misc.ts             # 杂项模式
│   ├── order.ts            # 订单模式
│   └── search.ts           # 搜索参数和响应类型
├── services/               # API 服务
│   ├── invoices.ts         # 发票服务
│   ├── misc.ts             # 杂项服务
│   ├── orders.ts           # 订单服务
│   ├── products.ts         # 产品详情服务
│   └── search.ts           # 搜索功能
└── utils/                  # 实用函数
    ├── index.ts            # 错误日志等
    └── api/                # API 客户端
        ├── authenticated.ts # 认证的 API 客户端
        ├── base.ts         # 基础 API 客户端
        └── public.ts       # 公共 API 客户端

特性

资源

• bitrefill://product-types - Bitrefill 上可用的产品类型列表
• bitrefill://categories/{type} - 特定产品类型可用的类别列表（例如，bitref fill://categories/gift-cards）

工具

• search - 搜索礼品卡、esims、手机充值等

  • 必需：query（例如，'Amazon'，'Netflix'，'AT&T' 或 '*' 表示所有）
  • 可选：country，language，limit，skip，category

• detail - 获取产品的详细信息

  • 必需：id（产品标识符）

• categories - 获取完整的产品类型/类别映射

  • 不需要任何参数

• create_invoice - 创建购买产品的新发票（需要 API 密钥）

  • 必需：products（要包含在发票中的产品数组）
    • 每个产品都需要：product_id
    • 可选的产品字段：quantity，value，package_id，phone_number，email，send_email，send_sms
  • 必需：payment_method（其中之一："balance"，"bitcoin"，"lightning"）
  • 可选：webhook_url，auto_pay

• get_invoices - 检索带有可选过滤器的发票列表

  • 可选：start，limit，after，before

• get_invoice - 根据 ID 检索特定发票的详细信息

  • 必需：id（发票标识符）

• pay_invoice - 支付未支付的发票（仅适用于“余额”支付方式）

  • 必需：id（发票标识符）

• get_orders - 检索带有可选过滤器的订单列表

  • 可选：start，limit，after，before

• get_order - 根据 ID 检索特定订单的详细信息

  • 必需：id（订单标识符）

• unseal_order - 根据 ID 揭示特定订单的代码和 PIN

  • 必需：id（订单标识符）

• get_account_balance - 检索您的账户余额

  • 不需要任何参数

• ping - 检查 Bitrefill API 是否可用

  • 不需要任何参数

配置

API 密钥设置

要使用除 search、categories 和 detail 之外的所有依赖于 Bitrefill API 的工具，您需要设置 Bitrefill API 凭据：

1. 创建一个 Bitrefill 账户
2. 通过填写 此表单 请求开发者 API 密钥
3. 在根目录中创建一个 .env 文件（您可以从 .env.example 复制）
4. 添加您的 Bitrefill API 凭据：

   BITREFILL_API_SECRET=your_api_key_here
   BITREFILL_API_ID=your_api_id_here
   

只有设置了 API 凭据时，create_invoice 工具才会可用。如果未设置 API 凭据，则不会注册该工具，也不会出现在可用工具列表中。

开发

安装依赖项：

npm install

构建服务器：

npm run build

开发时自动重建：

npm run watch

调试

由于 MCP 服务器通过标准 I/O 进行通信，调试可能会很困难。我们推荐使用 MCP Inspector，它作为一个包脚本提供：

npm run inspector

Inspector 将提供一个 URL，以便您可以在浏览器中访问调试工具。

安装

通过 Smithery 安装

要通过 Smithery 自动安装 Bitrefill for Claude Desktop：

npx -y @smithery/cli install @bitrefill/bitrefill-mcp-server --client claude

Claude Desktop

在以下位置添加服务器配置：

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bitrefill": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "env": {
        "BITREFILL_API_SECRET": "your_api_key_here",
        "BITREFILL_API_ID": "your_api_id_here"
      }
    }
  }
}

Cline

1. 打开 Cline 扩展设置
2. 打开“MCP 服务器”标签
3. 点击“配置 MCP 服务器”
4. 添加服务器配置：

{
  "mcpServers": {
    "github.com/bitrefill/bitrefill-mcp-server": {
      "command": "npx",
      "args": ["-y", "bitrefill-mcp-server"],
      "disabled": false,
      "autoApprove": ["search", "detail", "categories"],
      "env": {
        "BITREFILL_API_ID": "your_api_id_here",
        "BITREFILL_API_SECRET": "your_api_key_here"
      }
    }
  }
}

额外的 Cline 配置选项：

• disabled：设置为 false 启用服务器
• autoApprove：不需要每次使用都明确批准的工具列表

Cursor

1. 打开 Cursor 设置
2. 打开“功能”设置
3. 在“MCP 服务器”部分，点击“添加新的 MCP 服务器”
4. 选择一个名称，并选择“命令”作为类型
5. 在“命令”字段中输入以下内容：

npx -y bitrefill-mcp-server

6. （可选）如果您使用 create_invoice 工具，请添加环境变量：
   • BITREFILL_API_SECRET: your_api_key_here
   • BITREFILL_API_ID: your_api_id_here

Docker

您还可以使用 Docker 运行服务器。首先，构建镜像：

docker build -t bitrefill-mcp-server .

然后运行容器：

docker run -e BITREFILL_API_SECRET=your_api_key_here -e BITREFILL_API_ID=your_api_id_here bitrefill-mcp-server

对于开发，您可能希望将源代码挂载为卷：

docker run -v $(pwd):/app --env-file .env bitrefill-mcp-server