Criei um servidor MCP que rastreia seu orçamento de contexto do Claude Code em tempo real

Todo desenvolvedor que usa Claude Code ou Cursor já se deparou com esse problema: o agente começa a entrar em loop, as respostas pioram e então — estouro de contexto. Você não teve nenhum aviso. Você não teve visibilidade. Você simplesmente perdeu toda a sessão.

Eu construí ContextPulse para corrigir isso.

O que é o ContextPulse?

ContextPulse é um servidor MCP independente de framework que fica entre seu agente de codificação AI e suas ferramentas. Ele intercepta cada chamada de ferramenta, conta tokens em tempo real, rastreia seu orçamento de contexto e dispara alertas antes que você atinja o limite.

Ele é disponibilizado em dois repositórios:

• contextpulse-mcp — o servidor MCP + API REST NestJS + gateway WebSocket + fila de alertas BullMQ
• contextpulse — o painel em tempo real Next.js

O problema que ele resolve

As ferramentas de observabilidade atuais (Langfuse, LangSmith, Phoenix) são focadas em framework e mostram o custo após a execução. Elas não informam dentro da execução que você está com 87% de contexto e a uma chamada de ferramenta de um estouro.

E ninguém no código aberto permite que você compare duas execuções de agente lado a lado para ver o que mudou após uma edição de prompt.

O ContextPulse faz ambas as coisas.

Recursos

Fase 1 — Núcleo do servidor MCP

• Intercepta chamadas de ferramentas via protocolo MCP
• Conta tokens usando tiktoken (cl100k_base)
• Armazena tudo em PostgreSQL — sessões, execuções, chamadas de ferramentas, instantâneas de orçamento, alertas
• Dispara avisos a 70% e alertas críticos a 90% de uso de contexto
• Detecta loops: quando a mesma ferramenta é chamada 3× seguidas

Fase 2 — Painel em tempo real

• API REST NestJS: GET /api/runs, /api/runs/:id, /api/runs/:id/tool-calls, /api/runs/:id/alerts
• Gateway WebSocket (Socket.io) envia eventos ao vivo para o painel
• Painel Next.js 15 com barra de orçamento ao vivo, cascata de chamadas de ferramentas, feed de alertas, registro de eventos

Fase 3 — Fila de alertas BullMQ + gráfico de loops

• Trabalhador de alerta assíncrono BullMQ: processa alertas de orçamento e loops sem bloquear o servidor MCP
• Entrega de webhook opcional via ALERT_WEBHOOK_URL
• Gráfico de frequência de detecção de loops — destaca ferramentas chamadas acima do limite de loop em vermelho

Fase 4 — Motor de diferença de execução

• GET /api/diff?runA=<id>&runB=<id> compara duas execuções
• Retorna delta de tokens, delta de chamadas de ferramentas, vencedor do orçamento, novos loops introduzidos, loops resolvidos
• UI de diferença completa no painel: cartões de estatísticas lado a lado, tabela de delta, detalhamento ferramenta por ferramenta

Stack tecnológico

TypeScript · NestJS · Next.js 15 · PostgreSQL · Redis
BullMQ · WebSocket (Socket.io) · MCP SDK · tiktoken · Zod · Tailwind

Início rápido

1. Inicie o PostgreSQL

createdb contextpulse

2. Clone e execute o servidor MCP

git clone https://github.com/DIYA73/contextpulse-mcp
cd contextpulse-mcp
npm install
cp .env.example .env
npm run dev:api   # API NestJS na porta 3000
npm run dev:mcp   # Servidor MCP na stdio

3. Adicione ao Claude Code

// ~/.claude/settings.json
{
  "mcpServers": {
    "contextpulse": {
      "command": "npx",
      "args": ["tsx", "/path/to/contextpulse-mcp/src/proxy/server.ts"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/contextpulse"
      }
    }
  }
}

4. Execute o painel

git clone https://github.com/DIYA73/contextpulse
cd contextpulse
npm install
echo "NEXT_PUBLIC_API_URL=http://localhost:3000" > .env.local
npm run dev   # Painel na porta 3001

Abra http://localhost:3001 — você verá o painel ao vivo.

Usando no seu agente

cp_start_session   → obter sessionId
cp_start_run       → obter runId
cp_track_tool_call → chamar após cada chamada de ferramenta
cp_get_budget      → verificar orçamento ao vivo a qualquer momento
cp_get_run_summary → resumo completo da execução com linha do tempo
cp_end_run         → limpar

Exemplo de resposta de cp_track_tool_call:

{
  "toolCallId": "a1b2c3...",
  "inputTokens": 142,
  "outputTokens": 87,
  "totalTokens": 229,
  "budget": {
    "used": 14820,
    "limit": 200000,
    "percentUsed": 7.41
  },
  "budgetStatus": "ok",