L-Dopa

MCP-сервер, который помогает ИИ-агентам восстанавливаться, перефокусироваться и реально доводить дело до конца.

L-Dopa меня вылечил, ясно??

L-Dopa — это небольшой, ориентированный на продакшн сервер Model Context Protocol (MCP), который помогает агенту восстановиться, когда подход не срабатывает, контекст разрознен, а повторные попытки превращаются в цикл. Он не выполняет команды, не изменяет внешние системы и не заменяет суждение агента. Он анализирует предоставленные ему доказательства, сохраняет ограниченное состояние восстановления и предлагает более безопасный следующий шаг.

Название — шутка. Цикл восстановления — нет.

Что он делает

L-Dopa v0.1 предоставляет шесть MCP-инструментов, которые позволяют агенту диагностировать сбои, сокращать объём задачи, восстанавливать релевантный контекст и управлять повторными попытками осознанно.

Related MCP server: nautilus-compass

Принципы дизайна

Установка

Клонируйте репозиторий и установите зависимости:

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

Запустите stdio-сервер вручную:

npm start

npm start намеренно ожидает ввода. MCP-серверы общаются через JSON-RPC по стандартному вводу и выводу, поэтому обычно клиент MCP запускает его за вас.

Подключение MCP-клиента

Сначала соберите L-Dopa, затем используйте его исполняемую точку входа. Следующая универсальная конфигурация MCP совместима с клиентами, поддерживающими локальные stdio-серверы:

{
  "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"
      }
    }
  }
}

Для установленного пакета команда может быть l-dopa, в зависимости от окружения клиента. Держите стандартный вывод зарезервированным для сообщений протокола MCP. L-Dopa записывает собственные краткие структурированные операционные логи в стандартный поток ошибок.

Конфигурация

L-Dopa работает с безопасными значениями по умолчанию и может быть настроен через JSON-файл и/или переменные окружения. Скопируйте предоставленный пример, чтобы начать:

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

Переменные окружения переопределяют значения из файла.

Конфигурация не содержит настроек учётных данных провайдера, потому что эта версия не совершает вызовов к моделям или провайдерам. Если будущему расширению потребуются учётные данные, передавайте их через переменные окружения; не добавляйте их в репозиторий, файл конфигурации или промпт восстановления.

Справочник инструментов

Все текстовые аргументы ограничиваются по длине и очищаются от учётных данных до того, как L-Dopa сохраняет или возвращает их. sessionId по умолчанию равен "default", но агентам следует использовать стабильный ID для каждой задачи или разговора, чтобы предотвратить смешивание несвязанных историй восстановления.

diagnose

Используйте diagnose после сбоя, предоставив столько полезного контекста, сколько доступно. errorMessage, recentOperation, logs, attemptedSolution, expectedResult и actualResult необязательны, но точная ошибка или фактический результат делают ответ более полезным.

{
  "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"
}

Ответ включает likelyCause, confidence, evidence, recommendedNextActions, retryAppropriate, tryDifferentStrategy и индикатор redacted. Обнаружение намеренно эвристическое, а не ложная категоричность.

stimulate

Используйте stimulate, когда агенту нужно перестать комментировать и начать учиться. Передайте обязательный task и необязательный context с высокой информативностью.

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

Стратегия восстановления делает акцент на минимальном проверяемом действии и предостерегает от неизменных циклов.

focus

Используйте focus, чтобы превратить широкую задачу в намеренно короткую последовательность. maxSteps необязателен и принимает значения от одного до пяти; по умолчанию он равен трём.

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

reuptake

Используйте reuptake, когда агенту нужен релевантный контекст сессии без выгрузки полного транскрипта. limit по умолчанию равен пяти и ограничен двадцатью.

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

Он возвращает текущую задачу, статус восстановления, недавние сбои, опробованные решения, успешные подходы, обнаруженные факты, нерешённые вопросы и количество повторных попыток. Инструменты v0.1 пока не предоставляют отдельного инструмента для записи фактов; discoveredFacts зарезервирован для расширений и остаётся в компактной схеме.

retry

Используйте retry, чтобы создать явную запись о повторной попытке или сообщить о её результате. proposedChange должен указывать, что именно изменилось. L-Dopa допускает записи о запланированных, успешных и неудачных повторах, но сам никогда не выполняет повторную попытку.

{
  "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 блокирует повторную попытку, если исчерпан настроенный лимит операции, повторился тот же сбой или существующая повторная попытка повторяется без изменённого предложения. Его ответ о блокировке рекомендует ограниченный альтернативный путь, который может включать передачу чётко очерченной подзадачи и собранных доказательств другому способному агенту.

fix_me

Используйте fix_me как краткую версию последовательности diagnose → focus → stimulate → retry guidance. Он записывает переданный сбой, если он есть, а затем возвращает план; он не выполняет его.

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

Состояние и конфиденциальность

Хранилище состояния — это обычный JSON-файл, записываемый атомарно с режимом 0600. Оно имеет версионированную структуру и хранит отдельные сессии по ключу sessionId. В пределах каждой сессии записи о сбоях, повторных попытках, опробованных решениях, успешных подходах и обнаруженных фактах сокращаются до maxHistory.

Состояние намеренно лёгкое, а не система долговременной памяти. Оно находится локально на машине текущего пользователя и не передаётся L-Dopa. Просматривайте или удаляйте настроенный файл состояния всякий раз, когда нужно очистить историю восстановления.

Важно: Редактирование охватывает несколько распространённых шаблонов учётных данных, но это защитная мера, а не разрешение отправлять секреты. Не помещайте намеренно пароли, токены, приватные ключи или полные заголовки авторизации в диагностический ввод.

Разработка

npm install
npm run build
npm test

Проект намеренно модульный:

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

Тестовое покрытие

Автоматизированный набор тестов подключает реальный клиент и сервер MCP через транспорт в памяти SDK. Он покрывает инициализацию сервера, обнаружение MCP-инструментов, каждый инструмент, сохранение состояния, ограниченное хранение, лимиты повторных попыток, неизменные повторы, обнаружение повторяющихся сбоев и редактирование учётных данных.

Запустите его с помощью:

npm test

Ограничения и дорожная карта

L-Dopa v0.1 использует детерминированные эвристики, поэтому распознаёт распространённые классы сбоев, но не является всезнающим отладчиком. В нём намеренно нет векторного хранилища, удалённого сохранения, интеграции с провайдерами моделей и возможности выполнения команд. Он не анализирует скрытую цепочку рассуждений агента; он работает только с предоставленным операционным контекстом.

Будущие дополнения должны сохранять эти границы: добавляйте инструмент только тогда, когда он даёт явную пользу для восстановления; держите выполнение команд в отдельном компоненте с контролем разрешений; сохраняйте состояние ограниченным и проверяемым.

Лицензия

MIT