L-Dopa

Un servidor MCP para ayudar a los agentes de IA a recuperarse, reenfocarse y hacer que las cosas se hagan.

L-Dopa me arregló, ¿vale??

L-Dopa es un servidor pequeño y orientado a la producción del Model Context Protocol (MCP) que ayuda a un agente a recuperarse cuando un enfoque está fallando, el contexto está disperso o los reintentos se están convirtiendo en un bucle. No ejecuta comandos, no muta sistemas externos ni reemplaza el juicio de un agente. Analiza la evidencia que se le proporciona, conserva un estado de recuperación acotado y propone un siguiente paso más seguro.

El nombre es una broma. El bucle de recuperación no lo es.

Qué hace

L-Dopa v0.1 proporciona seis herramientas MCP que permiten a un agente diagnosticar fallos, reducir el alcance, restaurar el contexto relevante y gestionar los reintentos de forma deliberada.

Related MCP server: nautilus-compass

Principios de diseño

Instalación

Clona el repositorio e instala las dependencias:

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

Inicia el servidor stdio manualmente con:

npm start

npm start parece esperar entrada a propósito. Los servidores MCP se comunican mediante JSON-RPC a través de la entrada y salida estándar, así que normalmente un cliente MCP lo lanza por ti.

Conectar un cliente MCP

Compila L-Dopa primero y luego usa su punto de entrada ejecutable. La siguiente configuración genérica de MCP es compatible con clientes que admiten servidores stdio locales:

{
  "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 un paquete instalado, el comando puede ser en su lugar l-dopa, dependiendo del entorno del cliente. Mantén la salida estándar reservada para los mensajes del protocolo MCP. L-Dopa escribe sus propios registros operativos estructurados y concisos en el error estándar.

Configuración

L-Dopa se ejecuta con valores predeterminados seguros y puede configurarse mediante un archivo JSON y/o variables de entorno. Copia el ejemplo proporcionado para empezar:

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

Las variables de entorno sobrescriben los valores del archivo.

La configuración no contiene ningún ajuste de credenciales de proveedor porque esta versión no realiza llamadas a modelos ni a proveedores. Si una extensión futura requiere credenciales, pásalas mediante variables de entorno; no las añadas a un repositorio, archivo de configuración o prompt de recuperación.

Referencia de herramientas

Todos los argumentos de texto están acotados y se les censuran las credenciales antes de que L-Dopa los persista o los devuelva. sessionId tiene "default" como valor predeterminado, pero los agentes deberían usar un ID estable por tarea o conversación para evitar que se mezclen historiales de recuperación no relacionados.

diagnose

Usa diagnose después de un fallo con todo el contexto útil que esté disponible. errorMessage, recentOperation, logs, attemptedSolution, expectedResult y actualResult son opcionales, pero un error o un resultado real preciso hace que la respuesta sea más ú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"
}

La respuesta incluye likelyCause, confidence, evidence, recommendedNextActions, retryAppropriate, tryDifferentStrategy y un indicador redacted. La detección es deliberadamente heurística en lugar de falsamente autoritativa.

stimulate

Usa stimulate cuando un agente necesite dejar de narrar y empezar a aprender. Proporciona un task obligatorio y un context opcional de alta señal.

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

La estrategia de recuperación enfatiza una acción mínima y verificable, y advierte contra los bucles sin cambios.

focus

Usa focus para convertir una tarea amplia en una secuencia deliberadamente corta. maxSteps es opcional y va de uno a cinco; tiene tres como valor predeterminado.

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

reuptake

Usa reuptake cuando el agente necesite contexto relevante de la sesión sin volcar una transcripción. limit tiene cinco como valor predeterminado y está limitado a veinte.

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

Devuelve la tarea actual, el estado de recuperación, los fallos recientes, las soluciones intentadas, los enfoques exitosos, los hechos descubiertos, los problemas no resueltos y el contador de reintentos. Las herramientas de v0.1 todavía no exponen una herramienta dedicada al registro de hechos; discoveredFacts está reservado para extensiones y sigue presente en el esquema compacto.

retry

Usa retry para crear un registro de reintento explícito o informar de su resultado. Un proposedChange debe indicar qué es diferente. L-Dopa permite registros planificados, exitosos y fallidos, pero nunca realiza el reintento por sí mismo.

{
  "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 bloquea un reintento si el límite de operación configurado está agotado, el mismo fallo se ha repetido o un reintento existente se repite sin una propuesta modificada. Su respuesta de bloqueo recomienda una vía alternativa acotada, que puede incluir entregar una subtarea bien delimitada y la evidencia recopilada a otro agente capaz.

fix_me

Usa fix_me para la versión corta de diagnose → focus → stimulate → retry guidance. Registra un fallo proporcionado, si lo hay, y luego devuelve un plan; no lo ejecuta.

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

Estado y privacidad

El almacén de estado es un archivo JSON plano escrito atómicamente con modo 0600. Tiene una forma versionada y almacena sesiones separadas por clave sessionId. Dentro de cada sesión, los registros de fallos, los registros de reintentos, las soluciones intentadas, los enfoques exitosos y los hechos descubiertos se recortan a maxHistory.

El estado es intencionadamente ligero, no un sistema de memoria a largo plazo. Es local a la máquina del usuario que lo ejecuta y L-Dopa no lo transmite. Revisa o elimina el archivo de estado configurado siempre que necesites borrar el historial de recuperación.

Importante: La censura cubre varios patrones comunes de credenciales, pero es una conveniencia defensiva, no una licencia para enviar secretos. No coloques intencionadamente contraseñas, tokens, claves privadas o cabeceras de autorización completas en la entrada de diagnóstico.

Desarrollo

npm install
npm run build
npm test

El proyecto es 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 pruebas

El conjunto de pruebas automatizadas conecta un cliente y un servidor MCP reales a través del transporte en memoria del SDK. Cubre la inicialización del servidor, el descubrimiento de herramientas MCP, cada herramienta, la persistencia del estado, la retención acotada, los límites de reintento, los reintentos sin cambios, la detección de fallos repetidos y la censura de credenciales.

Ejecútalo con:

npm test

Limitaciones y hoja de ruta

L-Dopa v0.1 usa heurísticas deterministas, por lo que reconoce clases de fallos comunes, pero no es un depurador omnisciente. No tiene almacén vectorial, persistencia remota, integración con proveedores de modelos ni capacidad de ejecución de comandos por diseño. No inspecciona la cadena de pensamiento oculta de un agente; solo trabaja con el contexto operativo proporcionado.

Las incorporaciones futuras deberían preservar estos límites: añadir una herramienta solo cuando aporte un beneficio claro de recuperación, mantener la ejecución de comandos en un componente separado controlado por permisos y mantener el estado acotado e inspeccionable.

Licencia

MIT