L-Dopa

一个帮助 AI 智能体恢复、重新聚焦并把事情搞定的 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 为扩展而保留，并继续存在于精简 schema 中。

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

测试覆盖

自动化测试套件通过 SDK 的内存传输连接真实的 MCP 客户端和服务器。它覆盖服务器初始化、MCP 工具发现、每个工具、状态持久化、有界保留、重试上限、未改变的重试、重复失败检测和凭据脱敏。

运行测试：

npm test

局限与路线图

L-Dopa v0.1 使用确定性启发式，因此它能识别常见的失败类型，但并非无所不知的调试器。它刻意没有向量存储、远程持久化、模型提供商集成或命令执行能力。它不检查智能体的隐藏思维链；它只处理提供的操作上下文。

未来的新增功能应保持这些边界：只有在工具能提供明确的恢复效益时才添加工具，将命令执行保留在单独的权限控制组件中，并保持状态有界且可检查。

许可证

MIT