Bitrefill MCP 服务器

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

工作原理

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

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

架构

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

src/
├── index.ts                # Main entry point
├── constants/              # Static data
│   ├── categories.ts       # Product categories
│   └── payment_methods.ts  # Payment methods
├── handlers/               # MCP request handlers
│   ├── resources.ts        # Resource endpoints
│   └── tools.ts            # Tool implementations
├── schemas/                # Data validation schemas
│   ├── detail.ts           # Product detail response types
│   ├── invoice.ts          # Invoice schemas
│   ├── misc.ts             # Miscellaneous schemas
│   ├── order.ts            # Order schemas
│   └── search.ts           # Search parameters and response types
├── services/               # API services
│   ├── invoices.ts         # Invoice service
│   ├── misc.ts             # Miscellaneous services
│   ├── orders.ts           # Order services
│   ├── products.ts         # Product details service
│   └── search.ts           # Search functionality
└── utils/                  # Utility functions
    ├── index.ts            # Error logging, etc.
    └── api/                # API clients
        ├── authenticated.ts # Authenticated API client
        ├── base.ts         # Base API client
        └── public.ts       # Public API client

功能

资源

• bitrefill://product-types - Bitrefill 上可用的产品类型列表
• bitrefill://categories/{type} - 特定产品类型的可用类别列表（例如，bitrefill://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 服务器通过 stdio 进行通信，调试可能会很困难。我们建议使用 MCP Inspector，它作为包脚本提供：

npm run inspector

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

安装

通过 Smithery 安装

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

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 Servers" 标签页
3. 点击 "Configure MCP Servers"
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. 打开 "Features" 设置
3. 在 "MCP Servers" 部分，点击 "Add new MCP Server"
4. 选择一个名称，并选择 "command" 作为 "Type"
5. 在 "Command" 字段中输入以下内容：

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