El-Dopa

Um servidor MCP para ajudar agentes de IA a se recuperarem, se reorientarem e fazerem a porra do trabalho.

Documentação

L-Dopa

Um servidor MCP para ajudar agentes de IA a se recuperarem, refocarem e fazerem as coisas acontecerem.

L-Dopa me consertou, certo??

L-Dopa é um servidor Model Context Protocol (MCP) pequeno e voltado para produção que ajuda um agente a se recuperar quando uma abordagem está falhando, o contexto está disperso ou as tentativas estão virando um loop. Ele não executa comandos, não altera sistemas externos nem substitui o julgamento de um agente. Ele analisa as evidências fornecidas, retém estado de recuperação limitado e propõe um próximo passo mais seguro.

O nome é uma piada. O loop de recuperação não é.

O que ele faz

L-Dopa v0.1 fornece seis ferramentas MCP que permitem a um agente diagnosticar falhas, reduzir escopo, restaurar contexto relevante e gerenciar tentativas de forma deliberada.

Ferramenta	Use quando	Ela retorna
`diagnose`	Uma operação falhou e o agente tem um erro ou trecho de log.	Causa provável, confiança calibrada, evidência editada, próximas ações e orientação de nova tentativa.
`stimulate`	O agente está girando em círculos sem fazer uma observação útil.	Um reset conciso que foca em uma suposição e uma verificação mínima e segura.
`focus`	Uma tarefa é ampla demais ou emaranhada.	Uma lista priorizada de uma a cinco próximas ações concretas; três é o padrão.
`reuptake`	O agente precisa de contexto de recuperação relevante da sua sessão L-Dopa.	Um resumo compacto de falhas recentes, tentativas, sucessos, fatos e problemas não resolvidos.
`retry`	O agente está considerando ou relatando uma nova tentativa.	Uma nova tentativa registrada e limitada, ou um bloqueio com recomendação de estratégia alternativa.
`fix_me`	O agente está travado e quer uma sequência de recuperação concisa.	Diagnóstico, ações focadas, um empurrão de recuperação e orientação de nova tentativa.

Princípios de design

Princípio	Implementação na v0.1
Sem certeza mágica	A confiança diagnóstica é `low`, `medium` ou `high`; evidência fraca permanece fraca.
Sem loops cegos	Falhas repetidas materialmente semelhantes, propostas de nova tentativa inalteradas e limites de nova tentativa por operação bloqueiam novas tentativas.
Memória limitada	O estado baseado em JSON retém apenas o número configurado de registros por categoria para cada sessão.
Seguro por padrão	L-Dopa oferece apenas diagnóstico e planejamento. Ele nunca executa comandos de shell ou ações externas.
Saída ciente de credenciais	Padrões comuns de token, cabeçalho de autorização, senha, chave de API, JWT, chave AWS e token GitHub são editados antes do estado, logs e saída da ferramenta.
Implantação simples	O servidor usa transporte stdio MCP padrão e requer Node.js 18 ou mais recente.

Instalação

Clone o repositório e instale as dependências:

git clone https://github.com/mshanghai570/L-Dopa.git
cd L-Dopa
npm install
npm run build

Inicie o servidor stdio manualmente com:

npm start

npm start intencionalmente parece aguardar entrada. Servidores MCP falam JSON-RPC pela entrada e saída padrão, então normalmente um cliente MCP o inicia para você.

Conecte um cliente MCP

Compile L-Dopa primeiro e depois use seu ponto de entrada executável. A seguinte configuração MCP genérica é compatível com clientes que suportam servidores stdio locais:

{
  "mcpServers": {
    "l-dopa": {
      "command": "node",
      "args": ["/absolute/path/to/L-Dopa/dist/index.js"],
      "env": {
        "LDOPA_STATE_FILE": "/absolute/path/to/l-dopa-state.json",
        "LDOPA_MAX_HISTORY": "50",
        "LDOPA_RETRY_LIMIT": "3",
        "LDOPA_LOG_LEVEL": "info"
      }
    }
  }
}

Para um pacote instalado, o comando pode ser l-dopa, dependendo do ambiente do cliente. Mantenha a saída padrão reservada para mensagens de protocolo MCP. L-Dopa escreve seus próprios logs operacionais estruturados e concisos na saída de erro padrão.

Configuração

L-Dopa roda com padrões seguros e pode ser configurado por meio de um arquivo JSON e/ou variáveis de ambiente. Copie o exemplo fornecido para começar:

cp l-dopa.config.example.json l-dopa.config.json
LDOPA_CONFIG=./l-dopa.config.json npm start

Variáveis de ambiente substituem valores de arquivo.

Configuração	Propriedade JSON	Variável de ambiente	Padrão	Significado
Caminho do estado	`stateFile`	`LDOPA_STATE_FILE`	`~/.l-dopa/state.json`	Local do armazenamento de sessão JSON limitado.
Limite de histórico	`maxHistory`	`LDOPA_MAX_HISTORY`	`50`	Máximo positivo de registros retidos para cada categoria em uma sessão.
Limite de nova tentativa	`retryLimit`	`LDOPA_RETRY_LIMIT`	`3`	Máximo positivo de novas tentativas planejadas/relatadas retidas para uma operação antes que novas tentativas sejam bloqueadas.
Nível de registro	`logLevel`	`LDOPA_LOG_LEVEL`	`info`	Um de `debug`, `info`, `warn` ou `error`.
Arquivo de configuração	—	`LDOPA_CONFIG`	—	Caminho opcional para um arquivo de configuração JSON.

A configuração não contém configurações de credenciais de provedor porque esta versão não faz chamadas de modelo ou provedor. Se uma extensão futura exigir credenciais, passe-as por variáveis de ambiente; não as adicione a um repositório, arquivo de configuração ou prompt de recuperação.

Referência de ferramentas

Todos os argumentos de texto são limitados e com credenciais editadas antes de L-Dopa persistir ou retorná-los. sessionId tem como padrão "default", mas os agentes devem usar um ID estável por tarefa ou conversa para evitar que históricos de recuperação não relacionados se misturem.

`diagnose`

Use diagnose após uma falha com o máximo de contexto útil disponível. errorMessage, recentOperation, logs, attemptedSolution, expectedResult e actualResult são opcionais, mas um erro preciso ou resultado real torna a resposta mais útil.

{
  "sessionId": "deploy-2026-08-27",
  "recentOperation": "Deploy version 0.1.0",
  "errorMessage": "429 Too Many Requests",
  "attemptedSolution": "Immediately retried the deployment",
  "expectedResult": "Deployment accepted",
  "actualResult": "The API rejected the request"
}

A resposta inclui likelyCause, confidence, evidence, recommendedNextActions, retryAppropriate, tryDifferentStrategy e um indicador de redacted. A detecção é deliberadamente heurística, não falsamente autoritativa.

`stimulate`

Use stimulate quando um agente precisar parar de narrar e começar a aprender. Forneça um task obrigatório e um context opcional de alto sinal.

{
  "sessionId": "deploy-2026-08-27",
  "task": "Repair the deployment",
  "context": "The health check timed out twice after a successful build"
}

A estratégia de recuperação enfatiza uma ação mínima e verificável e alerta contra loops inalterados.

`focus`

Use focus para transformar uma tarefa ampla em uma sequência deliberadamente curta. maxSteps é opcional e varia de um a cinco; o padrão é três.

{
  "sessionId": "deploy-2026-08-27",
  "task": "Repair the deployment and verify availability",
  "context": "Health checks time out",
  "maxSteps": 3
}

`reuptake`

Use reuptake quando o agente precisar de contexto de sessão relevante sem despejar uma transcrição. limit tem como padrão cinco e é limitado a vinte.

{
  "sessionId": "deploy-2026-08-27",
  "limit": 5
}

Ele retorna a tarefa atual, status de recuperação, falhas recentes, soluções tentadas, abordagens bem-sucedidas, fatos descobertos, problemas não resolvidos e contagem de novas tentativas. As ferramentas da v0.1 ainda não expõem uma ferramenta dedicada de registro de fatos; discoveredFacts é reservado para extensões e permanece presente no esquema compacto.

`retry`

Use retry para criar um registro explícito de nova tentativa ou relatar seu resultado. Um proposedChange deve nomear o que é diferente. L-Dopa permite registros planejados, bem-sucedidos e com falha, mas nunca executa a nova tentativa em si.

{
  "sessionId": "deploy-2026-08-27",
  "operation": "Deploy version 0.1.0",
  "previousFailure": "429 Too Many Requests",
  "proposedChange": "Wait for Retry-After and submit only one request",
  "result": "planned"
}

L-Dopa bloqueia uma nova tentativa se o limite de operação configurado for excedido, a mesma falha tiver recorrido ou uma nova tentativa existente for repetida sem uma proposta alterada. Sua resposta de bloqueio recomenda um caminho alternativo limitado, que pode incluir entregar uma subtarefa bem delimitada e evidências coletadas a outro agente capaz.

`fix_me`

Use fix_me para a versão curta de diagnose → focus → stimulate → retry guidance. Ele registra uma falha fornecida, quando presente, e depois retorna um plano; não o executa.

{
  "sessionId": "publish-0.1.0",
  "task": "Publish the package safely",
  "recentOperation": "npm publish",
  "errorMessage": "401 Unauthorized",
  "attemptedSolution": "Re-ran the same command"
}

Estado e privacidade

O armazenamento de estado é um arquivo JSON simples escrito atomicamente com modo 0600. Ele tem uma forma versionada e armazena sessões separadas por chave sessionId. Dentro de cada sessão, registros de falha, registros de nova tentativa, soluções tentadas, abordagens bem-sucedidas e fatos descobertos são limitados a maxHistory.

O estado é intencionalmente leve, não um sistema de memória de longo prazo. Ele é local à máquina do usuário em execução e não é transmitido por L-Dopa. Revise ou exclua o arquivo de estado configurado sempre que precisar limpar o histórico de recuperação.

Importante: A edição cobre vários padrões comuns de credenciais, mas é uma conveniência defensiva, não uma licença para enviar segredos. Não coloque intencionalmente senhas, tokens, chaves privadas ou cabeçalhos de autorização completos em entrada de diagnóstico.

Desenvolvimento

npm install
npm run build
npm test

O projeto é deliberadamente modular:

src/
  config.ts       Configuration loading and validation
  index.ts        Executable stdio MCP entry point
  logger.ts       Structured, redacted standard-error logging
  redaction.ts    Credential-detection and output redaction
  recovery.ts     Diagnostic, focus, stimulation, and plan logic
  server.ts       MCP server and tool registrations
  state.ts        Bounded, atomic JSON session storage
  types.ts        Shared contracts
tests/
  l-dopa.test.ts  End-to-end MCP and state behavior tests

Cobertura de testes

A suíte automatizada conecta um cliente e servidor MCP reais por meio do transporte em memória do SDK. Ela cobre inicialização do servidor, descoberta de ferramentas MCP, cada ferramenta, persistência de estado, retenção limitada, limites de nova tentativa, novas tentativas inalteradas, detecção de falha repetida e edição de credenciais.

Execute com:

npm test

Limitações e roteiro

L-Dopa v0.1 usa heurísticas determinísticas, então reconhece classes comuns de falha, mas não é um depurador onisciente. Ele não tem armazenamento vetorial, persistência remota, integração com provedor de modelo ou capacidade de execução de comandos por design. Ele não inspeciona a cadeia de pensamento oculta de um agente; ele apenas trabalha com contexto operacional fornecido.

Adições futuras devem preservar esses limites: adicione uma ferramenta apenas quando ela fornecer um benefício claro de recuperação, mantenha a execução de comandos em um componente separado com controle de permissão e mantenha o estado limitado e inspecionável.

Licença

MIT