quota-mcp

English | 简体中文

quota-mcp

AI 订阅账户用量与配额追踪器。它将散落在各供应商控制台中的余额、订阅到期日期和速率限制窗口汇总到一处，并通过 REST 管理 API 和 MCP 查询接口提供这些信息——只需用一行配置将你的 Agent（Hermes、Claude Code、……）连接到它，它就能自行回答“我还剩多少配额？”

目前支持两个平台：

平台	数据来源	凭据	可查看内容
StepFun（阶跃星辰，.ai 国际版 / .com 中国版）	platform.stepfun.{ai,com} 控制台 Connect RPC	浏览器会话（Oasis-Token，约 2 小时，自动续期）+ 可选的方案密钥	方案与到期时间、5 小时 / 每周 / 订阅额度窗口、账户下的访问密钥、会话健康状态
Command Code（commandcode.ai）	api.commandcode.ai 上未公开文档的 /alpha/* 接口	单个 Bearer API 密钥	方案（GOAT/Pro/Max/……）、5 小时 / 每周 / 每月窗口、余额、计费周期请求统计

亮点：

• 静态加密：凭据使用 AES-256-GCM 加密后存入 SQLite（纯 Go 驱动，无 CGO）；每个端点都只返回脱敏视图
• StepFun 会话自动续期：后台 goroutine 每 60 秒检查一次，并续期 TTL 低于 20 分钟的会话。续期已过期的会话会得到降级的设备令牌——系统会检测到这一情况并拒绝保存该令牌
• 双认证平面：StepFun 的方案密钥（永久有效）和控制台会话（配额数据）分别管理和探测；状态判定由永久凭据平面决定
• MCP 只读：查询接口（列出 / 探测 / 汇总）可安全地交给 Agent 使用；注册 / 续期 / 删除操作仅在 REST 端提供
• 单个二进制文件，无外部服务依赖

快速开始

go build -o quota-mcp ./cmd/quota-mcp

# In production set the master key explicitly (64 hex chars). Without it the key is
# derived from machine traits and old ciphertext becomes unreadable after a migration.
export QUOTA_MCP_MASTER_KEY=$(openssl rand -hex 32)

./quota-mcp -db data/quota-mcp.db -listen 127.0.0.1:8780

启动后：

• http://127.0.0.1:8780/healthz 健康检查
• http://127.0.0.1:8780/api/stepfun/accounts REST 列表
• http://127.0.0.1:8780/mcp MCP 端点

注册账户

Command Code（两个凭据平面）

alpha/API 密钥平面最简单——使用永久 Bearer 密钥：

curl -X POST http://127.0.0.1:8780/api/commandcode/accounts \
  -H 'Content-Type: application/json' \
  -d '{"service":"cc-myname","api_key":"user_xxx","label":"primary"}'

从 commandcode.ai/settings/keys 获取密钥（创建时仅显示一次）。服务器会先通过 whoami 验证密钥，并拒绝存储未通过验证的密钥。

内部/会话平面模拟浏览器行为：传入 session_text（完整的 Cookie: 标头、document.cookie 转储，或裸值 __Secure-commandcode_prod_.session_token）。系统会使用 billing/credits 验证会话，只有验证通过才会存储。会话会过期，因此请从 CookieCloud 刷新，或再次从 DevTools 复制 Cookie：

curl -X POST http://127.0.0.1:8780/api/commandcode/accounts \
  -H 'Content-Type: application/json' \
  -d '{"service":"cc-myname","session_text":"__Secure-commandcode_prod_.session_token=eyJ..."}'

同时存储两者时，API 密钥优先。每次注册都会覆盖本次提供的凭据平面——只用 api_key 重新注册会清除已存储的会话，反之亦然，因此凭据轮换绝不会被悄悄跳过。

StepFun（浏览器会话）

Oasis-Token 是 HttpOnly Cookie，因此 document.cookie 无法读取它——请从 DevTools 的请求标头中复制。将完整的 Cookie: 标头（或裸令牌）粘贴到服务器：

curl -X POST http://127.0.0.1:8780/api/stepfun/accounts \
  -H 'Content-Type: application/json' \
  -d '{"service":"ai-412848664332275712","region":"ai","session_text":"Oasis-Token=eyJ...; Oasis-Webid=...","email":"[email protected]"}'

真实环境测试中发现的协议情况（均已在代码中处理）：

• .ai 的 Oasis-Token Cookie 值由 两个 JWT 拼接而成（8 个片段）；控制台只接受完整值，单个片段会返回 token is illegal
• 不同站点的时间戳单位不同：.ai 返回秒级字符串，.com 返回毫秒；代码会根据数值大小推断单位
• .com 设备令牌仅有效 30 分钟，且其 RefreshToken 会返回降级令牌——.com 会话需要定期重新导入
• 过期后续期会得到设备令牌（mode 1，数据平面始终返回 token is illegal），因此必须在过期前续期；降级防护会拒绝存储此类令牌

REST API

GET    /api/stepfun/accounts                     List (masked view)
POST   /api/stepfun/accounts                     Enrol/update (stored only if at least one plane probes OK)
POST   /api/stepfun/accounts/{service}/probe     Probe (auto-renews once on console auth failure)
POST   /api/stepfun/accounts/{service}/renew     Force-renew the console session
POST   /api/stepfun/accounts/{service}/register?region=ai   Register an anonymous device slot (self-test)
DELETE /api/stepfun/accounts/{service}           Delete
POST   /api/stepfun/probe                        Probe all (cron-friendly)

GET    /api/commandcode/accounts                 List (masked view)
POST   /api/commandcode/accounts                 Enrol/update (api_key or session_text; stored only if it probes OK)
POST   /api/commandcode/accounts/{service}/probe Probe
DELETE /api/commandcode/accounts/{service}       Delete
POST   /api/commandcode/probe                    Probe all

MCP 接口（供 Agent 使用）

有两种连接方式，任选其一：

1. Streamable HTTP（通过 /mcp 提供服务）——适用于始终在线的部署：

mcp_servers:
  quota:
    url: http://<your-host>:8780/mcp

2. stdio——适用于自行启动服务的客户端（Claude Code、容器、类似 mcp-publisher 的注册表安装）：

# local binary
quota-mcp -stdio

# or straight from the published image (works with zero setup)
docker run -i --rm -v quota-mcp-data:/data ghcr.io/limitcool/quota-mcp:latest

在 Claude Code 或任何其他 MCP 客户端中，使用方式都相同。

所有工具均为只读：

工具	描述
quota_list_accounts	列出所有账户：套餐、到期时间、剩余配额、会话／密钥状态（已遮罩）
quota_probe_account	实时探测一个账户（会请求上游，需要几秒钟）
quota_probe_all	按顺序探测所有账户并刷新缓存
quota_status	摘要：各平台的服务中／受限／无效／需要重新登录的账户数，以及每个账户的一行状态
quota_check_alerts	当前触发的告警：配额偏低、即将到期、会话失效、密钥被拒绝、超出窗口限制
quota_report	定时摘要所用的数据：所有账户编号和当前告警

告警、到期提醒和定时摘要

quota-mcp 负责检测条件（它持有数据并运行 60 s 后台循环）；调度和发送由你的 Agent 平台负责。以下是类似 hermes 的配置方式：

1. 阈值和到期告警（事件驱动，推送）

后台评估器会刷新过期的探测数据（>5 min）、评估规则、在 SQLite（alert_events）中维护触发／已解决状态机，并通过 webhook 仅 POST 状态变更——同一告警在解决并再次触发前不会重复发送。

规则：credit_low（剩余比例低于阈值）、expiring_soon（订阅／计费周期将在 N 天内结束）、session_dead（StepFun 控制台会话需要重新导入）、key_rejected（Command Code 密钥收到 401/403）、window_limited（超出速率窗口限制）。

QUOTA_MCP_ALERT_WEBHOOK_URL=http://<hermes>:8642/webhooks/quota \
QUOTA_MCP_ALERT_CREDIT_PCT=0.2 \
QUOTA_MCP_ALERT_EXPIRY_DAYS=7 \
./quota-mcp -listen 0.0.0.0:8780

每次状态变更时推送的载荷：

{
  "source": "quota-mcp",
  "at": "2026-09-21T15:52:30Z",
  "fired":    [{"kind":"credit_low","provider":"stepfun","service":"ai-…","severity":"warn","title":"订阅额度即将耗尽","detail":"剩余 13%（阈值 20%），2026-10-20 重置"}],
  "resolved": []
}

没有 webhook？没问题——hermes（或其他工具）也可以改为轮询：

# hermes mcp_servers
mcp_servers:
  quota:
    url: http://<host>:8780/mcp

然后设置 hermes cron 每 15–30 min 调用 quota_check_alerts，并通过 hermes send 发送新告警。GET /api/alerts?history=20 也可以采用相同方式。

2. 定时摘要（cron）

quota_report（或 GET /api/report）会返回稳定、便于 Agent 使用的数据：每个账户的套餐／到期时间／剩余配额／会话状态／窗口用量／请求统计，以及当前告警。将 hermes 现有的 09:30 cron 指向该接口：一次运行即可调用工具、编写消息并通过 hermes send 发送。quota-mcp 内部不会重复实现调度器。

3. 环境变量

变量	默认值	含义
QUOTA_MCP_ALERT_CREDIT_PCT	0.2	剩余比例低于此值时触发
QUOTA_MCP_ALERT_EXPIRY_DAYS	7	订阅／计费周期将在 N 天内结束时触发
QUOTA_MCP_ALERT_WEBHOOK_URL	—	告警状态变更的 POST 目标；为空时仅记录（拉取模式）

示例（quota_status 输出——Agent 用于回答“还剩多少配额？”的内容）：

{
  "stepfun": {
    "total": 2, "healthy": 2, "attention": 0,
    "accounts": ["ai-4128…: ok (10 models)", "com-3766…: ok (0 models)"]
  },
  "commandcode": {
    "total": 1, "serving": 1, "limited": 0, "key_rejected": 0,
    "accounts": ["cc-limitcool: serving GOAT"]
  }
}

项目结构

cmd/quota-mcp/        Entrypoint (flags/env config, one port serving both surfaces)
internal/store/       SQLite + AES-256-GCM encryption + schema
internal/stepfun/     StepFun protocol client + account registry + background renewer
internal/commandcode/ Command Code protocol client + account registry
internal/api/         REST management surface (net/http, no framework)
internal/mcpsrv/      MCP query surface (modelcontextprotocol/go-sdk)
internal/alerts/      Alert rules + firing/resolved state machine + webhook push
internal/digest/       Scheduled-digest payload for cron consumers

安全边界

• 密文仅写入数据库——绝不写入日志或响应；每个端点均返回经过遮罩的内容
• REST 接口包含写入操作：请将其绑定到回环地址或专用网络。若要公开访问，请在前面部署反向代理并启用身份验证，且只公开 MCP 路径
• 丢失主密钥将导致所有已存储凭据无法读取——请备份 QUOTA_MCP_MASTER_KEY

发布版本

每个 GitHub Release 都附有 Linux／macOS／Windows（amd64 + arm64）二进制文件。下载最新版本：

# example: linux amd64
curl -LO https://github.com/limitcool/quota-mcp/releases/latest/download/quota-mcp_linux_amd64
chmod +x quota-mcp_linux_amd64

Docker

每次推送到 main（:main）或推送标签（:v1.0.0、:latest）时，都会将镜像发布到 ghcr.io/limitcool/quota-mcp（amd64 + arm64）。

docker run -d --name quota-mcp \
  -p 8780:8780 \
  -v quota-mcp-data:/data \
  -e QUOTA_MCP_MASTER_KEY=$(openssl rand -hex 32) \
  ghcr.io/limitcool/quota-mcp:latest

也可以使用随附的 compose 文件（必须设置 QUOTA_MCP_MASTER_KEY，并将其写入 .env）：

echo "QUOTA_MCP_MASTER_KEY=$(openssl rand -hex 32)" > .env
docker compose up -d

数据库位于 /data 卷中（QUOTA_MCP_DB=/data/quota-mcp.db）。请备份主密钥——丢失后，所有已存储凭据都将无法读取。

许可证

MIT