内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/billing-mcp</h1>
<p align="center"><strong>一个 AI 代理的账户经济系统，基于 MCP — 计划配额、计量使用、发票、收据和收益。只读且限定账户范围。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/billing-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/billing-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/billing-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/billing-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许 AI 代理自行管理其**自己的**账户经济系统，通过 stdio: 剩余的计划配额、计量使用、发票和收据，以及代理的收益 — 所有这些都不需要人工账户所有者的介入。
每次读取操作都会调用 three.ws 计费 API — 不会模拟。限定账户范围的读取操作会针对**您自己的**账户，解析自您的 three.ws 会话。这个服务器是**只读**的：它显示私有计费数据，但从不签名、收费或转移资金。
## 安装
```bash
npm install @three-ws/billing-mcp
```
或使用 `npx`（无需安装）：
```bash
npx @three-ws/billing-mcp
```
## 快速开始
**Claude 代码**，一行：
```bash
claude mcp add billing -- npx -y @three-ws/billing-mcp
```
**Claude 桌面版 / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```json
{
"mcpServers": {
"billing": {
"command": "npx",
"args": ["-y", "@three-ws/billing-mcp"],
"env": {
"THREE_WS_SESSION": "<您的 __Host-sid cookie>"
}
}
}
}
```
`THREE_WS_SESSION` 是每个读取操作（除了公共费用率）所必需的 — 它是来自已登录的 three.ws 浏览器会话的 `__Host-sid` cookie 的值，API 使用它来解析您的账户并仅返回您的数据。
使用 MCP 检查器检查界面：
```bash
npx -y @modelcontextprotocol/inspector npx @three-ws/billing-mcp
```
## 工具
| 工具 | 类型 | 功能 |
| -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `get_billing_summary` | 读取 · 会话 | 您的计划层级、配额上限和实时用量（头像 + 存储、代理、MCP 调用、LLM 调用）+ 剩余空间。 |
| `query_usage` | 读取 · 会话 | 计量使用情况汇总为一个期间的发票报表 — 按操作划分的项目、总计和对账。 |
| `export_billing_history` | 读取 · 会话 | 与 `query_usage` 相同的项目，作为可保存的 CSV 有效载荷（带有建议的文件名和解析预览）。 |
| `get_receipt` | 读取 · 会话 | 一个项目化收据 — 按 `event_id`（带有结算交易 + 资源链接）或按 `purchase_id`（签名技能购买收据）。 |
| `get_revenue` | 读取 · 会话 | 您拥有的代理的收益 — 总计/费用/净额，按技能和时间划分，以及创作者订阅收入。 |
| `get_fee_info` | 读取 · **公共** | 当前平台费用率（`fee_bps` + `fee_percent`）。无需会话。 |
所有读取操作都针对实时状态 — 使用情况、发票和收益在调用之间会发生变化 — 因此没有工具是幂等的，这里没有任何内容会发生突变。
### 输入参数
**`get_billing_summary`** — 无。
**`query_usage`** — `period`（YYYY-MM，可选），`from` / `to`（ISO-8601，可选；当设置 `period` 时会被忽略）。默认为当前 UTC 日历月。
**`export_billing_history`** — `period`，`from`，`to`（与 `query_usage` 相同），`preview_rows`（0-100，默认为 5 — 在 `preview` 中显示多少解析行；始终返回完整的 CSV）。
**`get_receipt`** — 恰好一个 `event_id`（数字，按费用收据）或 `purchase_id`（UUID，签名技能购买收据）。
**`get_revenue`** — `agent_id`（UUID，可选 — 缩小到一个代理），`from` / `to`（ISO-8601，默认为最近 30 天），`granularity`（`day` | `week` | `month`，默认为 `day`）。
**`get_fee_info`** — 无。
## 您的欠费 vs. 您的收益
同一账户的两个方面，两个工具：
- **"这笔费用是多少？"** → `query_usage` / `export_billing_history` / `get_receipt` — 计量费用、期间报表和任何单笔费用的收据。
- **"我的代理赚了多少？"** → `get_revenue` — 总计/费用/净额收益，按技能和时间划分，以及创作者订阅收入。
`get_billing_summary` 位于两者之上：您的计划、配额上限和剩余空间。
## 金钱 & 单位
- 费用金额以 **USDC 原子单位**（6 位小数）表示，同时附带人类可读的 `*_usd` 字符串 — 例如 `gross_atomics: "150000"` 是 `gross_usd: "0.15"`。
- `get_revenue` 收益总额以 **代币的原子单位**（`currency_mint` / `chain` 确定代币）表示；创作者订阅收入以 **USD** 单独报告，因为它直接结算到您的钱包，从不与可提取池混合单位。
- 使用情况和收益读取的对账告诉您每个计量费用是否映射到实际的链上结算（`all_reconciled`，以及计数）。
## 要求
- **Node.js >= 20.**
- 可以访问 `https://three.ws`（或您自己的 `THREE_WS_BASE`）。
### 环境变量
| 变量 | 是否必需 | 默认值 |
| ----------------------- | -------------------------------- | -------------------- |
| `THREE_WS_BASE` | 否 | `https://three.ws` |
| `THREE_WS_TIMEOUT_MS` | 否 | `20000` |
| `THREE_WS_SESSION` | 是（所有读取操作，但 `get_fee_info` 除外） | — |
`THREE_WS_SESSION` 是来自已登录的 three.ws 浏览器会话的 `__Host-sid` cookie 的值。请像密码一样对待它 — 它授予对您的私有计费数据的读取访问权限。
## 链接
- 首页：https://three.ws
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
版权所有 © 2026 nirholas。保留所有权利。
本软件是专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者明确书面许可，不得授予任何权利。
