429-throttle-mcp

Pare de ser rejeitado com HTTP 429 — um proxy MCP com limite de taxa mais uma skill de operador de agente. Modelos se autorregulam automaticamente durante tarefas de longa duração; usuários não técnicos abrem / ajustam / desativam / diagnosticam / revisam com frases simples.

GitHub

Experimente este MCPPatrocinado

Documentação

429-throttle-mcp

English | 中文

Nunca mais seja rejeitado por API 429 — proxy MCP com limite de taxa integrado + habilidade de operador de agente. O modelo controla a velocidade automaticamente em tarefas de longa duração; usuários não técnicos concluem "ativar / ajustar / desativar / diagnosticar / revisar" com uma única frase.

O que é

Muitas APIs gratuitas de modelos de grande porte (Grok, Gemini, Dots, etc.) permitem apenas cerca de 30 chamadas por minuto. Ao executar tarefas de longa duração (busca + geração de PPT, chamadas em lote de ferramentas), o modelo facilmente excede o limite e é rejeitado com 429.

O 429-throttle-mcp oferece uma camada transparente de limitação de taxa para esse problema:

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

O modelo não precisa saber da existência do limite de taxa; ele só precisa chamar o call_api normalmente. A lógica de limitação é executada de forma transparente dentro do MCP — se a cota for suficiente, a chamada é liberada; se não, o modelo é informado de quanto tempo esperar antes de tentar novamente.

Para quem é:

Desenvolvedores / usuários de frameworks de agente: npm i 429-throttle-mcp (MCP) ou npm i dsh-throttle (DSH) fornecem um proxy transparente de limitação de taxa;
Usuários não técnicos: com a habilidade rate-limit-operator, ative, ajuste, desative e revise a limitação de taxa com uma única frase.

Mudança de direção na v1.1 (importante)

A v1.1 evoluiu de "proxy de limitação de taxa apenas para desenvolvedores" para um "painel de controle de limitação de taxa utilizável por usuários não técnicos", adicionando três capacidades:

Habilidade de operador de agente rate-limit-operator — transforma "ativar / ajustar / desativar / diagnosticar / revisar" em linguagem coloquial, executada pelo agente. O usuário diz "ativar limite", "muito lento", "ainda 429", "desativar limite" e pronto, sem precisar entender RPM/TPM ou editar arquivos.
Revisão de tarefa begin_task / end_task — chamada uma vez no início e no final de tarefas longas, retornando: tempo real gasto, número de chamadas, número de vezes limitado, tempo serial original e "em qual rodada atingirá o teto" calculado com base no nível de concorrência.
Distinção entre dois tipos de 429 — bloqueio do proxy (rejectedCalls > 0, resolvível com ajuste de parâmetros) vs. cota da plataforma upstream 429 (somente consultando a documentação da plataforma), evitando aumentar cegamente o limite do proxy e aumentar o risco de bloqueio.

Versão e histórico de alterações

Versão atual v1.1.0 (npm saltou de 1.0.2). Alterações na v1.1.0:

✨ Novas ferramentas: begin_task / end_task (revisão de tarefas longas)
✨ Novas estatísticas: totalDurationMs / avgLatencyMs (retornadas por get_rate_limit_status)
✨ Nova habilidade de operador rate-limit-operator (controle completo do fluxo em linguagem coloquial)
🔒 Reforço de segurança: call_api adicionou lista de permissões de scheme de URL (apenas http/https)
🔧 Correção de compatibilidade: adaptação ao @modelcontextprotocol/sdk 1.30 (uso do McpServer de alto nível + Zod raw shape)

Estrutura do pacote

Monorepo contendo dois pacotes npm independentes, compartilhando a lógica central de limitação de taxa:

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

Pacote	Instalação	Uso
`429-throttle-mcp`	`npm i 429-throttle-mcp`	Servidor MCP (clientes MCP como ZCode / WorkBuddy)
`dsh-throttle`	`npm i dsh-throttle`	Plugin DeepSeek Harness

Parâmetros principais

Parâmetro	Valor padrão	Descrição
`MAX_CALLS`	30	Número máximo de chamadas por minuto (RPM)
`MAX_TOKENS`	750000	Número máximo de tokens por minuto (TPM), incluindo corpo da requisição e da resposta

Prioridade dos parâmetros: ajuste dinâmico pela ferramenta set_rate_limit > valor de inicialização do env. O ajuste dinâmico tem efeito imediato, mas após reiniciar o processo, volta ao valor padrão do env; para parâmetros de longo prazo, altere o env.

Ferramentas expostas (5 no total na v1.1)

`call_api`

Envia requisições HTTP através do proxy de limitação de taxa. Todas as chamadas de API externas devem passar por esta ferramenta (caso contrário, o limitador não terá dados e a revisão ficará vazia).

Parâmetro	Tipo	Obrigatório	Descrição
`url`	string	✅	URL completa da API de destino (apenas http/https)
`method`	string	❌	Método HTTP, padrão GET
`body`	string	❌	Corpo da requisição, string JSON
`headers`	string	❌	Cabeçalhos personalizados da requisição, string JSON

Retorno: resposta da API + snapshot de uso do _meta.rateLimit. Se for rejeitado por limite de taxa, retorna RATE_LIMIT_EXCEEDED, incluindo o tempo de espera sugerido em retryAfterSeconds.

`get_rate_limit_status`

Consulta o uso atual do limite de taxa. Retorna chamadas usadas/restantes e tokens, rejectedCalls (número de bloqueios pelo proxy), totalDurationMs (tempo acumulado das interfaces), avgLatencyMs (latência média por chamada) e recomendações. Para identificar a origem do 429, veja rejectedCalls.

`set_rate_limit`

Ajusta dinamicamente os parâmetros de limitação de taxa (efeito imediato, sem reiniciar).

Parâmetro	Tipo	Descrição
`callsPerMinute`	number	Número máximo de chamadas por minuto (RPM)
`tokensPerMinute`	number	Número máximo de tokens por minuto (TPM)

`begin_task` (novo na v1.1)

Inicia um intervalo de observação de limitação de taxa, retornando taskId. Chame antes de iniciar uma tarefa longa.

Parâmetro	Tipo	Descrição
`name`	string	Nome da tarefa (opcional, para identificação)

`end_task` (novo na v1.1)

Encerra o intervalo da tarefa e retorna o relatório de revisão.

Parâmetro	Tipo	Descrição
`taskId`	string	taskId retornado por `begin_task`
`concurrency`	number	Número assumido de chamadas concorrentes por rodada, padrão 1 (serial)

Campos retornados:

Campo	Significado
`wallClockMs` / `apiTimeMs`	Tempo de parede da tarefa / tempo puro de interface
`calls` / `tokens`	Número de chamadas da tarefa / consumo de tokens
`rejectedCalls`	Número de bloqueios pelo proxy (>0 = limite do proxy; =0 mas ainda vê 429 = plataforma upstream)
`estimatedSerialDurationMs`	Tempo serial original (número de chamadas × latência média)
`timeoutRound`	Rodada em que atingirá o teto com a concorrência dada (o que vier primeiro entre limite de chamadas e de tokens; "não atingiu o limite" = não colidiu)

Instalação

Clientes MCP (ZCode / WorkBuddy, etc.)

npm install 429-throttle-mcp

Adicione na configuração do 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

Método 1 (recomendado): montagem com um clique via CLI do DSH

dsh plugin --profile web add dsh-throttle

Método 2: montagem manual — coloque o plugin em profiles/<profile>/node_modules/@deepseek-ai/dsh-throttle/ e adicione uma entrada no array - insert: de cordis.patch.yml:

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

🔍 Ponto crucial: como confirmar a ativação e o funcionamento após a montagem

Clientes MCP (exemplo com WorkBuddy)

Passo 1 — Ativação: na página de gerenciamento de conectores, encontre 429-throttle-mcp e clique em Trust (obrigatório na primeira montagem). Se disabled: true estiver na configuração, altere para false.

Passo 2 — Confirme a ativação (qualquer um dos itens indica sucesso):

✅ A página de gerenciamento de conectores mostra o servidor conectado, ferramentas 5/5
✅ A lista de ferramentas da sessão mostra 429-throttle-mcp_call_api / get_rate_limit_status, etc.
✅ Peça ao modelo para chamar get_rate_limit_status uma vez; retornar JSON significa que o processo está vivo

Passo 3 — Teste de fumaça via linha de comando (independente da UI do cliente):

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

Saída esperada: 已启动 + 每分钟调用上限: 30 次 + 工具: call_api / get_rate_limit_status / set_rate_limit / begin_task / end_task.

Problemas comuns:

Ferramentas invisíveis → 90% é sessão não atualizada: abra uma nova janela de conversa e tente novamente (as ferramentas MCP são carregadas no início da sessão).
Alterou disabled / parâmetros do env → é necessário reiniciar o cliente para ter efeito.
Apenas 3 ferramentas, faltando begin_task/end_task → instalou a versão 1.0.x, atualize para 1.1.0.

DeepSeek Harness

Coloque o plugin em profiles/<profile>/node_modules/@deepseek-ai/dsh-throttle/ e adicione a entrada no patch (veja acima).
Reinicie o Harness.
A lista de ferramentas mostra call_api / get_rate_limit_status / set_rate_limit / begin_task / end_task, ou seja, ativação bem-sucedida.
Teste de fumaça: chame get_rate_limit_status e veja o retorno.

Execute um fluxo completo (recomendado, incluindo revisão)

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()                         → 累计统计

Habilidade de operador de agente (controle por linguagem coloquial, novo na v1.1)

Após instalar a habilidade rate-limit-operator no diretório de habilidades do agente (como ~/.workbuddy/skills/rate-limit-operator/ do WorkBuddy), as seguintes frases acionam automaticamente o agente:

Fase	Fala do usuário	Ação do agente
Ativar	"Ativar limite / o limite está ativo?"	Autoverificação → informa o limite atual; se não ativado, orienta Trust / alterar disabled / reiniciar
Ajustar	"Aumenta um pouco / muito lento / limitado de novo / restaurar padrão"	Primeiro consulta `rejectedCalls` para verificar se é limite do proxy, depois `set_rate_limit` aumenta / diminui / restaura
Desativar	"Desativar limite / não preciso mais"	Altera `disabled=true` e orienta reiniciar, ou guia para desativar no painel
Diagnosticar	"Ainda 429"	Verifica `rejectedCalls`: >0 é o proxy (ajustável); =0 é cota da plataforma upstream (fornece caminho de consulta, não inventa valores)
Revisar	Fim da tarefa longa	`begin_task` / `end_task` geram automaticamente relatório de tempo / chamadas / rodada de teto

Observação importante: quando o usuário diz "ainda 429", primeiro diagnostique a causa, depois aja. O 429 da plataforma upstream (cota de planos gratuitos / iniciais) não é resolvível pelo proxy; aumentar cegamente o limite do proxy só fará chamadas mais agressivas, aumentando o risco de bloqueio.

Exemplo de fluxo de trabalho (incluindo revisão)

Quando o modelo executa uma tarefa de busca de PPT de marca:

begin_task({name:"PPT 搜索"}) → anota o taskId
get_rate_limit_status → confirma cota suficiente
call_api → busca palavras-chave da marca (se rejeitado → espera retryAfterSeconds e tenta novamente)
Repete 2-3 até coletar todas as informações
end_task({taskId, concurrency:3}) → obtém revisão de tempo / chamadas / rodada de teto
set_rate_limit → ajusta os parâmetros de limite para cima ou para baixo com base na revisão

Algoritmo de limitação de taxa

Janela deslizante + balde de tokens (Sliding Window + Token Bucket): mantém uma janela deslizante de 60 segundos, registrando timestamp e consumo de tokens a cada chamada. Registros antigos fora da janela são limpos automaticamente. Quando o limite é excedido, calcula o tempo de espera restante do registro mais antigo.

Segurança de concorrência: tryConsume() é uma função síncrona, naturalmente serializada no loop de eventos de thread única do Node.js, sem condições de corrida.

Por que usar isso em vez de escrever "chame devagar" no prompt?

Método	Efeito
Prompt com "chame a cada 2 segundos"	❌ O modelo não tem cronômetro, não obedece, faz rajadas e ainda recebe 429
Limitação por script externo	❌ Requer processo extra, o modelo não percebe, difícil depurar erros
Proxy de limitação MCP (este projeto)	✅ Transparente para o modelo, controle rigoroso, erro estruturado + sugestão de espera
Proxy de limitação MCP + habilidade de operador	✅ Usuários não técnicos também podem "ativar / ajustar / desativar / revisar" com uma frase

Palavras-chave de cenário de aplicação

Erro 429, anti 429, limitação MCP, limite de chamadas por minuto de modelos de grande porte, limite de taxa de modelos gratuitos, 429 por chamadas em lote de agentes, chamadas em fila 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, 30 calls per minute, confirmação de ativação MCP, teste de fumaça MCP

Licença

MIT

429-throttle-mcp

Documentação

429-throttle-mcp

O que é

Mudança de direção na v1.1 (importante)

Versão e histórico de alterações

Estrutura do pacote

Parâmetros principais

Ferramentas expostas (5 no total na v1.1)

call_api

get_rate_limit_status

set_rate_limit

begin_task (novo na v1.1)

end_task (novo na v1.1)

Instalação

Clientes MCP (ZCode / WorkBuddy, etc.)

DeepSeek Harness

🔍 Ponto crucial: como confirmar a ativação e o funcionamento após a montagem

Clientes MCP (exemplo com WorkBuddy)

DeepSeek Harness

Execute um fluxo completo (recomendado, incluindo revisão)

Habilidade de operador de agente (controle por linguagem coloquial, novo na v1.1)

Exemplo de fluxo de trabalho (incluindo revisão)

Algoritmo de limitação de taxa

Por que usar isso em vez de escrever "chame devagar" no prompt?

Palavras-chave de cenário de aplicação

Licença

`call_api`

`get_rate_limit_status`

`set_rate_limit`

`begin_task` (novo na v1.1)

`end_task` (novo na v1.1)