El-Dopa

L-Dopa

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

L-Dopa me arregló, ¿de acuerdo?

L-Dopa es un servidor pequeño y orientado a 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, retiene estado de recuperación acotado y propone un siguiente movimiento 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 contexto relevante y gestionar reintentos de forma deliberada.

Herramienta	Úsala cuando	Devuelve
diagnose	Una operación falló y el agente tiene un error o un extracto de registro.	Causa probable, confianza calibrada, evidencia redactada, próximas acciones y orientación de reintento.
stimulate	El agente está dando vueltas sin hacer una observación útil.	Un reinicio conciso que se centra en una suposición y una verificación mínima segura.
focus	Una tarea es demasiado amplia o enredada.	Una lista priorizada de una a cinco acciones concretas; tres es el valor predeterminado.
reuptake	El agente necesita contexto de recuperación relevante de su sesión de L-Dopa.	Un resumen compacto de fallos recientes, intentos, éxitos, hechos y problemas no resueltos.
retry	El agente está considerando o informando un reintento.	Un reintento registrado y acotado, o un bloqueo con una recomendación de estrategia alternativa.
fix_me	El agente está atascado y quiere una secuencia de recuperación concisa.	Diagnóstico, acciones enfocadas, un empujón de recuperación y orientación de reintento.

Principios de diseño

Principio	Implementación en v0.1
Sin certeza mágica	La confianza diagnóstica es low, medium o high; la evidencia débil sigue siendo débil.
Sin bucles ciegos	Fallos repetidos materialmente similares, propuestas de reintento sin cambios y límites de reintento por operación bloquean reintentos adicionales.
Memoria acotada	El estado respaldado por JSON retiene solo el número configurado de registros por categoría para cada sesión.
Seguro por defecto	L-Dopa ofrece solo diagnóstico y planificación. Nunca ejecuta comandos de shell ni acciones externas.
Salida consciente de credenciales	Los patrones comunes de tokens, encabezados de autorización, contraseñas, claves de API, JWT, claves de AWS y tokens de GitHub se redactan antes del estado, los registros y la salida de las herramientas.
Implementación simple	El servidor usa transporte estándar MCP stdio y requiere Node.js 18 o superior.

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 aparece intencionalmente para esperar entrada. Los servidores MCP hablan JSON-RPC a través de la entrada y salida estándar, por lo que normalmente un cliente MCP lo inicia 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 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 se puede configurar mediante un archivo JSON y/o variables de entorno. Copia el ejemplo proporcionado para comenzar:

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

Las variables de entorno anulan los valores del archivo.

Configuración	Propiedad JSON	Variable de entorno	Predeterminado	Significado
Ruta de estado	stateFile	LDOPA_STATE_FILE	~/.l-dopa/state.json	Ubicación del almacén de sesiones JSON acotado.
Límite de historial	maxHistory	LDOPA_MAX_HISTORY	50	Máximo positivo de registros retenidos para cada categoría en una sesión.
Límite de reintentos	retryLimit	LDOPA_RETRY_LIMIT	3	Máximo positivo de reintentos planificados/informados retenidos para una operación antes de que se bloqueen nuevos reintentos.
Nivel de registro	logLevel	LDOPA_LOG_LEVEL	info	Uno de debug, info, warn o error.
Archivo de configuración	—	LDOPA_CONFIG	—	Ruta opcional a un archivo de configuración JSON.

La configuración no contiene configuraciones de credenciales de proveedor porque esta versión no realiza llamadas a modelos ni proveedores. Si una extensión futura requiere credenciales, pásalas a través de variables de entorno; no las agregues a un repositorio, archivo de configuración o mensaje de recuperación.

Referencia de herramientas

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

diagnose

Usa diagnose después de un fallo con tanto contexto útil como esté disponible. errorMessage, recentOperation, logs, attemptedSolution, expectedResult y actualResult son opcionales, pero un error preciso o un resultado real hacen 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 de 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 requerido 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 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 como predeterminado tres.

{
  "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 de sesión relevante sin volcar una transcripción. limit tiene como predeterminado cinco y está limitado a veinte.

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

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

retry

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

{
  "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 ha reaparecido o un reintento existente se repite sin una propuesta cambiada. Su respuesta de bloqueo recomienda una ruta alternativa acotada, que puede incluir entregar una subtarea bien delimitada y 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, cuando esté presente, 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 simple escrito atómicamente con modo 0600. Tiene una forma versionada y almacena sesiones separadas claveadas por sessionId. Dentro de cada sesión, los registros de fallos, registros de reintentos, soluciones intentadas, enfoques exitosos y hechos descubiertos se recortan a maxHistory.

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

Importante: La redacción cubre varios patrones comunes de credenciales, pero es una conveniencia defensiva, no una licencia para enviar secretos. No coloques intencionalmente contraseñas, tokens, claves privadas o encabezados de autorización completos 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 automatizado conecta un cliente y 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 de estado, la retención acotada, los límites de reintentos, los reintentos sin cambios, la detección de fallos repetidos y la redacción 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 comunes de fallos, pero no es un depurador omnisciente. No tiene almacén de vectores, 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 adiciones futuras deben preservar estos límites: agrega una herramienta solo cuando proporcione un beneficio claro de recuperación, mantén la ejecución de comandos en un componente separado controlado por permisos y mantén el estado acotado e inspeccionable.

Licencia

MIT