429-throttle-mcp

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. 任务复盘 begin_task / end_task — 长任务开始 / 结束时各调一次，返回：实际用时、调用次数、被限流次数、原定串行用时、按并发度推算的「第几轮会触顶」。
3. 两种 429 的区分 — 代理拦截（rejectedCalls > 0，可调参解决）vs 上游平台配额 429（只能查平台文档），避免盲目调高本代理上限反而更易被封。

---

版本与变更记录

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

• ✨ 新增工具：begin_task / end_task（长任务复盘）
• ✨ 新增统计：totalDurationMs / avgLatencyMs（get_rate_limit_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

包名	安装	用途
429-throttle-mcp	npm i 429-throttle-mcp	MCP Server（ZCode / WorkBuddy 等 MCP 客户端）
dsh-throttle	npm i dsh-throttle	DeepSeek Harness Plugin

---

核心参数

参数	默认值	说明
MAX_CALLS	30	每分钟最大调用次数 (RPM)
MAX_TOKENS	750000	每分钟最大 Token 数 (TPM)，含请求体和响应体

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

---

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

call_api

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

参数	类型	必填	说明
url	string	✅	目标 API 的完整 URL（仅 http/https）
method	string	❌	HTTP 方法，默认 GET
body	string	❌	请求体，JSON 字符串
headers	string	❌	自定义请求头，JSON 字符串

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

get_rate_limit_status

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

set_rate_limit

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

参数	类型	说明
callsPerMinute	number	每分钟最大调用次数 (RPM)
tokensPerMinute	number	每分钟最大 Token 数 (TPM)

begin_task（v1.1 新增）

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

参数	类型	说明
name	string	任务名（可选，便于辨识）

end_task（v1.1 新增）

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

参数	类型	说明
taskId	string	begin_task 返回的 taskId
concurrency	number	假设每轮并发调用数，默认 1（串行）

返回字段：

字段	含义
wallClockMs / apiTimeMs	任务挂钟用时 / 纯接口耗时
calls / tokens	本次任务调用次数 / Token 消耗
rejectedCalls	被本代理拦截次数（>0 = 本代理限流；=0 但仍见 429 = 上游平台）
estimatedSerialDurationMs	原定串行用时（调用数 × 平均时延）
timeoutRound	按给定并发度推算第几轮触顶（calls 限与 tokens 限先到者；「未达上限」= 没撞到）

---

安装

MCP 客户端（ZCode / WorkBuddy 等）

npm install 429-throttle-mcp

在 MCP 配置中添加（stdio）：

{
  "mcpServers": {
    "429-throttle-mcp": {
      "command": "node",
      "args": ["node_modules/429-throttle-mcp/server.js"],
      "env": {
        "MAX_CALLS": "30",
        "MAX_TOKENS": "750000"
      }
    }
  }
}

DeepSeek Harness

npm install dsh-throttle

方式一（推荐）：DSH CLI 一键挂载

dsh plugin --profile web add dsh-throttle

方式二：手动挂载——将插件装入 profiles/<profile>/node_modules/@deepseek-ai/dsh-throttle/，并在 cordis.patch.yml 的 - insert: 数组追加条目：

- id: dsh-throttle
  name: '@deepseek-ai/dsh-throttle'
  config: {}

---

🔍 重中之重：挂载后如何确认启用与跑通

MCP クライアント（WorkBuddy を例に）

ステップ 1 — 有効化：コネクター管理ページで 429-throttle-mcp を見つけ、Trust をクリックします（初回マウント時は必須です）。設定で disabled: true になっている場合は、先に false に変更します。

ステップ 2 — 有効化を確認（次のいずれかを満たせば成功です）：

• ✅ コネクター管理ページにその server が接続済みと表示され、ツールが 5/5 個ある
• ✅ セッションのツール一覧に 429-throttle-mcp_call_api / get_rate_limit_status などが表示される
• ✅ モデルに get_rate_limit_status を一度呼び出させ、JSON が返ればプロセスは稼働中です

ステップ 3 — コマンドラインでスモークテスト（クライアントの UI に依存しません）：

# 从 server.js 所在目录启动，正常打印启动信息即 OK
node server.js

期待される出力：已启动 ＋ 每分钟调用上限: 30 次 ＋ 工具: call_api / get_rate_limit_status / set_rate_limit / begin_task / end_task。

よくある問題：

• ツールが表示されない → 90％はセッションが更新されていないことが原因です。新しい会話ウィンドウを開いて再試行してください（MCP ツールはセッション開始時に読み込まれます）。
• disabled / env パラメーターを変更した → 反映するにはクライアントの再起動が必要です。
• ツールが 3 個しかなく、begin_task/end_task がない → 1.0.x がインストールされています。1.1.0 にアップグレードしてください。

DeepSeek Harness

1. プラグインを profiles/<profile>/node_modules/@deepseek-ai/dsh-throttle/ にインストールし、patch にエントリーを追加します（上記参照）。
2. Harness を再起動します。
3. ツール一覧に call_api / get_rate_limit_status / set_rate_limit / begin_task / end_task が表示されれば、有効化は成功です。
4. スモークテスト：get_rate_limit_status を呼び出して、返り値を確認します。

完全な一連の流れを一度実行する（推奨、振り返りを含む）

1. begin_task({name:"演示"})                       → 记下 taskId
2. call_api({url:"https://example.com"})           → status 200 + _meta.rateLimit
3. end_task({taskId, concurrency:2})               → 用时 / 次数 / timeoutRound
4. get_rate_limit_status()                         → 累计统计

---

エージェントオペレーターのスキル（口語での操作、v1.1 で追加）

スキル rate-limit-operator をエージェントのスキルディレクトリ（例：WorkBuddy の ~/.workbuddy/skills/rate-limit-operator/）にインストールすると、次のような口語表現をきっかけに、エージェントが自動で操作を代行します：

段階	ユーザーの口語表現	エージェントの動作
開く	「レート制限を開いて／レート制限は有効？」	自己診断 → 現在の上限を報告。有効でない場合は Trust / disabled の変更 / 再起動を案内
パラメーター調整	「少し上げて／遅すぎる／また制限された／デフォルトに戻して」	まず rejectedCalls を確認して、このプロキシ自身のレート制限かを判断し、その後 set_rate_limit で上げる／下げる／リセットする
閉じる	「レート制限を切って／もう使わない」	disabled=true に変更して再起動を案内するか、パネルで閉じるよう案内
診断	「まだ 429 が出る」	rejectedCalls で判定：>0 ならこのプロキシが原因（調整可能）、=0 なら上流プラットフォームのクォータが原因（確認方法を案内し、数値は捏造しない）
振り返り	長時間タスクの終了時	begin_task / end_task で所要時間／回数／上限到達時のラウンドを自動的にレポート

重要な認識：ユーザーが「まだ 429 が出る」と言ったときは、まず原因を判断してから対応します。上流プラットフォームの 429（無料／スタータープランのクォータ）は、このプロキシでは解決できません。このプロキシの上限をむやみに引き上げると、呼び出しがさらに激しくなり、ブロックされやすくなるだけです。

---

ワークフローの例（振り返りを含む）

モデルがブランドの PPT を検索するタスクを実行する場合：

1. begin_task({name:"PPT 搜索"}) → taskId を記録
2. get_rate_limit_status → クォータに余裕があることを確認
3. call_api → ブランドのキーワードを検索（拒否された場合は retryAfterSeconds の後に再試行）
4. すべての情報を収集するまで 2〜3 を繰り返す
5. end_task({taskId, concurrency:3}) → 所要時間／回数／上限到達時のラウンドの振り返りを取得
6. set_rate_limit → 振り返りの結果に基づいてレート制限パラメーターを厳しくする、または緩める

---

レート制限アルゴリズム

スライディングウィンドウ ＋ トークンバケット（Sliding Window + Token Bucket）：60 秒のスライディングウィンドウを維持し、呼び出しごとにタイムスタンプとトークン消費量を記録します。ウィンドウ外の古い記録は自動的に削除されます。制限を超えた場合は、最も古い記録の残り待ち時間を計算します。

並行処理の安全性：tryConsume() は同期関数であり、Node.js のシングルスレッドイベントループで自然に直列化されるため、競合状態は発生しません。

---

なぜ「ゆっくり呼び出す」とプロンプトに書くのではなく、これを使うのか？

方法	効果
Prompt に「2 秒ごとに呼び出す」と書く	❌ モデルには秒を測る機能がなく、指示にも従いません。一気に呼び出せば、やはり 429 が発生します
外部スクリプトでレート制限	❌ 追加のプロセスが必要です。モデルは状況を把握できず、問題が起きてもデバッグが困難です
MCP レート制限プロキシ（本プロジェクト）	✅ モデルに意識させず、透過的に制御し、構造化されたエラーと待機の提案を返します
MCP レート制限プロキシ ＋ オペレータースキル	✅ 技術に詳しくないユーザーでも、「開く／パラメーター調整／閉じる／振り返り」と一言伝えるだけで操作できます

---

アプリケーションシナリオのキーワード

429エラー, 429 対策, MCP レート制限, LLM の毎分呼び出し制限, 無料 LLM のレート制限, エージェントによる一括呼び出しで発生する 429, MCP キュー呼び出し, RPM, TPM, rate limiter mcp, quota guard, mcp server, mcp proxy, throttle, llm api quota, cop, HTTP 429, Too Many Requests, rate limiting, token bucket, sliding window, API proxy, LLM rate limit, AI API throttle, concurrent rate limit, 1 分あたり 30 回の呼び出し, MCP 有効化の確認, MCP スモークテスト

---

ライセンス

MIT