账单转发MCP服务器🚀
一种用于集成的高性能模型上下文协议（MCP）服务器 Billforward的 强大的计费和订阅管理API与LLM。
🛠 特性
- 实体发现：快速列出和检查帐户和订阅。
- 协议纯度：零日志泄漏
stdout，确保100%可靠的JSON-RPC通信。 - 安全第一：内置
BILLFORWARD_READ_ONLY=true（默认）模式，通过指示LLM错误拒绝来保护您的数据。 - 现代SDK：使用最新
@modelcontextprotocol/sdk签名(registerTool). - 完全可测试：包括通过Vitest进行的协议合规性和单元测试。
🔑 如何获取您的API代币
您需要一个API令牌，以允许MCP服务器与Billforward通信。
- 登录到您的Billforward环境。
- 导航至 设置>个人>API密钥.
- 创建一个新令牌并复制它。
快速链接：
______________________________________________________________________
⚙️ 配置
使用以下命令运行此服务器 npx （本地或出版）：
{
"mcpServers": {
"billforward": {
"command": "npx",
"args": [
"-y",
"billforward-mcp"
],
"env": {
"BILLFORWARD_ACCESS_TOKEN": "your_private_access_token",
"BILLFORWARD_ENVIRONMENT": "sandbox",
"BILLFORWARD_READ_ONLY": "true"
}
}
}
}高级环境变量
服务器的行为因这些配置而异：
| 变量 | 默认值 | 说明 |
|---|---|---|
BILLFORWARD_ENVIRONMENT | sandbox | 设置目标API。改变 production 当准备好。 |
BILLFORWARD_READ_ONLY | true | 当为真时，POST/PUT操作会向LLM返回指令错误消息，以防止数据突变。 |
BILLFORWARD_PRODUCTION_URL | https://app.billforward.net/v1/ | 环境为生产环境时使用的基本URL。 |
BILLFORWARD_SANDBOX_URL | https://app-sandbox.billforward.net/v1/ | 环境为沙盒时使用的基本URL。 |
BILLFORWARD_DEFAULT_RESULTS | 10 | 每个分页工具响应解析的默认结果数。 |
BILLFORWARD_MAX_RESULTS | 200 | LLM每次工具调用可以请求多少条记录的硬限制。 |
BILLFORWARD_TIMEOUT | 15000 | Axios请求失败前的回退超时（毫秒）。 |
🧰 可用工具
� 搜索与洞察
search：使用电子邮件、ID或关键字在帐户、订阅和发票之间进行并行统一搜索。get-customer-summary：客户的360度仪表板（个人资料、子客户、最近的发票、催款状态）。get-metadata-schema：分析整个环境中使用的元数据键，以帮助过滤查询。
�📖 指导
help：获取可用实体和使用模式的概述。get-me：验证您的连接并查看配置文件元数据。
👥 账户
list-accounts：获取分页的帐户列表(limit,offset,metadata,created_after).get-account：检索特定UUID的完整详细信息。get-account-by-email：通过准确的电子邮件地址快速查找帐户。
📝 订阅
list-subscriptions：获取已分页的订阅列表(limit,offset,created_after).get-subscription：检索特定UUID的完整详细信息。
🧾 发票和付款
list-invoices/get-invoice：获取发票和草稿详细信息。list-payments/list-receipts：提取付款及其相应收据。
💳 定价和目录
list-products：列出主要产品线。list-product-rate-plans：列出具体的费率计划（账户订阅的实体）。
🛡 安全
启用 只读模式 通过确保环境变量 BILLFORWARD_READ_ONLY=true 已设置（它是 true 默认情况下，出于安全考虑）。 如果LLM试图使用以下工具 create-account 或 update-subscription 当只读处于活动状态时，操作将被阻止，LLM将收到一个描述性错误，指示它通知您修改已禁用。
🧪 发展
构建
pnpm run build测试
pnpm test*包括特别 protocol.test.ts 以确保没有第三方包再次将日志泄漏到MCP流。*