Prompt Lab

Loops de otimização de prompts e suítes de teste de regressão para Claude Code, com uma interface web complementar.

Documentação

Prompt Lab MCP Server

Loops de otimização de prompts e suítes de testes de regressão para Claude Code, com uma interface web complementar.

O agente executa dentro da sua sessão do Claude Code e é responsável por todo o trabalho de LLM — pontuar respostas, propor prompts melhorados, aplicar sugestões. O servidor mantém o estado do workspace e mantém o agente e a Prompt Lab UI sincronizados.

Início rápido

Copie mcp-connect.json deste repositório para o seu projeto como .mcp.json:

{
  "mcpServers": {
    "prompt-lab": {
      "type": "http",
      "url": "https://prompt-lab-mcp.up.railway.app/mcp"
    }
  }
}

O Claude Code conecta automaticamente na próxima inicialização. Verifique com /mcp.

Exemplo de sessão

# 1. Open a workspace — agent shares the UI URL
start_web_app()
→ "Open https://prompt-lab-mcp.vercel.app?s=abc123 to follow along."

# 2. Register an API key
register_api_key(workspaceId, "sk-ant-...")

# 3. Set a system prompt and a test case
set_system_prompt(workspaceId, "You are a concise customer support agent...")
add_test_cases(workspaceId, [{
  query: "How do I reset my password?",
  targetAnswer: "Click 'Forgot password' on the login page and follow the email link."
}])

# 4. Run the optimization loop
loop_optimization(workspaceId, threshold=85)
→ Iteration 1 — score 58: response too long, no mention of email link
→ Iteration 2 — score 74: better, but missing the exact step
→ Iteration 3 — score 91: SUCCESS — prompt updated to require step-by-step answers

A UI mostra a pontuação de cada iteração, o raciocínio do agente e o prompt de sistema revisado em tempo real.

Como funciona

Prompt Lab UI (github.com/jurek-f/prompt-lab)
  ↕  HTTP
Prompt Lab MCP Server (Railway)
  ↕  MCP
Claude Code (your machine)

Chaves de API

As chaves de API nunca são armazenadas na configuração do servidor MCP. Em vez disso, passe-as para o Claude Code como variáveis de ambiente — o agente as lê e as registra no servidor no início de cada sessão usando register_api_key.

Defina a(s) chave(s) para o(s) provedor(es) que deseja usar. O agente detecta automaticamente o provedor a partir do prefixo da chave ao chamar register_api_key.

Se elas já estiverem no seu ambiente de sistema, o Claude Code as herda automaticamente — nada mais a fazer. Caso contrário, adicione-as a ~/.claude/env ou ao seu perfil de shell:

ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
OPENAI_API_KEY=sk-...

Ferramentas MCP

Configuração

Ferramenta	Descrição
`start_web_app(workspaceId?)`	Cria um workspace e retorna a URL da Prompt Lab UI.
`register_api_key(workspaceId, apiKey, provider?)`	Registra uma chave de API para execuções de teste. O provedor é detectado automaticamente a partir do prefixo da chave.
`list_models(workspaceId)`	Lista os modelos disponíveis com base nas chaves registradas.
`set_test_model(workspaceId, model)`	Define o modelo para execuções de teste. Sincroniza com o seletor de modelo da UI.
`delete_session(workspaceId)`	Exclui um workspace e todo o seu estado. Irreversível.

Templates

Os templates são globais e aparecem nos menus suspensos da UI assim que são enviados.

Ferramenta	Descrição
`save_template(name, testCases)`	Salva um template de suíte de testes. Aparece no menu suspenso "Carregar suíte de testes…" da UI.
`save_system_prompt_template(name, content)`	Salva um template de prompt de sistema. Aparece no menu suspenso "Carregar template…" da UI.

Estado do workspace

Ferramenta	Descrição
`get_workspace_state(workspaceId)`	Lê o workspace completo: prompt de sistema, casos de teste, resultados, sugestões, modelo.
`set_system_prompt(workspaceId, systemPrompt)`	Define o prompt de sistema sem incrementar o contador de iterações.
`add_test_cases(workspaceId, testCases, replace?)`	Adiciona casos de teste. `replace=true` sobrescreve todos os existentes.
`post_test_result(workspaceId, testCaseId, response, score, reasoning, model)`	Armazena um resultado de teste pontuado.
`post_prompt_suggestion(workspaceId, prompt, reasoning, expectedGain?)`	Enfileira um prompt revisado para revisão na UI.
`apply_suggestion(workspaceId, suggestionId)`	Aplica uma sugestão pendente e incrementa o contador de iterações.
`get_regression_status(workspaceId, threshold?)`	Resumo de aprovado/reprovado em todos os casos de teste para o prompt de sistema atual.

Otimização

Requer um workspace com pelo menos um caso de teste.

Ferramenta	Descrição
`start_optimization_session(workspaceId, threshold?, maxIterations?)`	Passagem única — pontua casos de teste, publica uma sugestão e aguarda a revisão do usuário na UI.
`loop_optimization(workspaceId, threshold?, maxIterations?)`	Loop automatizado — itera até que todas as pontuações atinjam o limite ou que o número máximo de iterações seja alcançado.

Regressão

Ferramenta	Descrição
`run_regression_testsuite(workspaceId, threshold?)`	Passagem única — pontua todos os casos de teste, sem alterações de prompt.
`loop_regression(workspaceId, threshold?)`	Loop automatizado — repete até que cada pontuação individual atinja o limite. Uma média alta que mascara um caso reprovado não é uma aprovação.

Arquivo

Ferramenta	Descrição
`pull_ui_history(workspaceId)`	Busca todos os resumos de sessão e execuções de regressão enviados pela UI.

Auto-hospedagem

Implante no Railway e defina estas variáveis de ambiente:

Variável	Descrição
`UPSTASH_REDIS_REST_URL`	URL do Upstash Redis para persistência
`UPSTASH_REDIS_REST_TOKEN`	Token do Upstash Redis
`PROMPT_LAB_UI_URL`	URL da sua implantação da Prompt Lab UI

npm install
npm run dev    # starts on :3000

Endpoint MCP: http://localhost:3000/mcp

Licença

MIT — veja Licença.