429 Throttle MCP server

429-throttle-mcp

English | 中文

不再被 API 429 拒绝 — 自带限流的 MCP 代理 + Agent 操作员技能。模型在长程任务中自动控速；非技术用户一句话完成「打开 / 调参 / 关闭 / 诊断 / 复盘」。

是什么

很多免费大模型 API（Grok、Gemini、Dots 等）每分钟只能调用 30 次左右。模型在做长程任务（搜索 + 生成 PPT、批量调用工具）时，很容易超出限额被 429 拒绝。

429-throttle-mcp 在这个痛点上提供了一个透明限流层：

模型 → call_api 工具 → 限流器 → 实际 API 请求 → 返回结果 + 用量快照

模型不需要知道速率限制的存在，它只需要正常调用 call_api。限流逻辑在 MCP 内部透明执行——额度够就放行，不够就告诉模型等多久再重试。

适合谁：

• 开发者 / Agent 框架用户：npm i 429-throttle-mcp（MCP）或 npm i dsh-throttle（DSH）即得透明限流代理；
• 非技术用户：配合 rate-limit-operator 技能，用一句话完成限流的打开、调参、关闭与复盘。

v1.1 方向变化（重要）

v1.1 从「仅面向开发者的限流代理」升级为「非技术用户也能用的限流控制面」，新增三块能力：

1. Agent 操作员技能 rate-limit-operator — 把「打开 / 调参 / 关闭 / 诊断 / 复盘」全部口语化，由 agent 代劳。用户说「打开限流」「太慢了」「还是 429」「关掉限流」即可，无需懂 RPM/TPM、无需改文件。
2. 任务复盘 begintask / endtask — 长任务开始 / 结束时各调一次，返回：实际用时、调用次数、被限流次数、原定串行用时、按并发度推算的「第几轮会触顶」。
3. 两种 429 的区分 — 代理拦截（rejectedCalls > 0，可调参解决）vs 上游平台配额 429（只能查平台文档），避免盲目调高本代理上限反而更易被封。

版本与变更记录

当前版本 v1.1.0（npm 自 1.0.2 起跳升）。v1.1.0 变更：

• ✨ 新增工具：begintask / endtask（长任务复盘）
• ✨ 新增统计：totalDurationMs / avgLatencyMs（getratelimit_status 返回）
• ✨ 新增操作员技能 rate-limit-operator（口语控制全流程）
• 🔒 安全加固：call_api 增加 URL scheme 白名单（仅 http/https）
• 🔧 兼容修复：适配 @modelcontextprotocol/sdk 1.30（改用高层 McpServer + Zod raw shape）

包结构

Monorepo，包含两个独立 npm 包，共享核心限流逻辑：

429-throttle-mcp/
├── packages/
│   ├── rate-limiter.js              # 核心限流逻辑（共享）
│   ├── 429-throttle-mcp/            # MCP Server 包
│   │   ├── package.json
│   │   ├── server.js
│   │   └── rate-limiter.js
│   └── dsh-throttle/                # DSH Plugin 包
│       ├── package.json
│       ├── plugin.js
│       └── rate-limiter.js
├── dsh-manifest.json
├── README.md
└── .env.example

核心参数

参数优先级：setratelimit 工具动态调整 > env 启动值。动态调整实时生效但进程重启后回到 env 默认值；长期参数请改 env。

暴露的工具（v1.1 共 5 个）

call_api

通过限流代理发送 HTTP 请求。所有外部 API 调用必须经过此工具（否则限流器无数据，复盘为空）。

返回：API 响应 + meta.rateLimit 用量快照。如果被限流拒绝，返回 RATELIMIT_EXCEEDED，包含 retryAfterSeconds 建议等待时间。

getratelimit_status

查询当前速率限制使用情况。返回已用/剩余调用次数和 Token 数、rejectedCalls（被本代理拦截数）、totalDurationMs（累计接口耗时）、avgLatencyMs（平均单次时延）及建议。判 429 来源看 rejectedCalls。

setratelimit

动态调整限流参数（实时生效，无需重启）。

begin_task（v1.1 新增）

开启一个限流观测任务区间，返回 taskId。长任务开始前调用。

end_task（v1.1 新增）

结束任务区间并返回复盘报告。

返回字段：

Shortened. The full README is on GitHub.