L-Dopa

AIエージェントが立ち直り、集中力を取り戻し、仕事をやり遂げるためのMCPサーバー。

L-Dopaは私を直してくれたんだ、間違いない??

L-Dopaは、アプローチが失敗しつつあるとき、コンテキストが散乱しているとき、またはリトライがループになりつつあるときに、エージェントの回復を支援する、小規模で実運用を意識したModel Context Protocol (MCP)サーバーです。コマンドの実行、外部システムの変更、エージェントの判断の置き換えは行いません。 提供された証拠を分析し、範囲を限定した回復状態を保持し、より安全な次の一手を提案します。

名前は冗談です。回復ループは冗談ではありません。

できること

L-Dopa v0.1は、エージェントが障害を診断し、範囲を縮小し、関連するコンテキストを復元し、リトライを意図的に管理できるようにする6つの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はオプションで、1〜5の範囲です。デフォルトは3です。

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

reuptake

トランスクリプト全体をダンプせずに関連するセッションコンテキストが必要な場合はreuptakeを使用します。limitはデフォルトで5、上限は20です。

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

diagnose → focus → stimulate → retry guidanceの短縮版にはfix_meを使用します。指定された失敗があればそれを記録してから計画を返します。実行はしません。

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

状態とプライバシー

状態ストアは、モード0600で原子的に書き込まれるプレーンなJSONファイルです。バージョン管理された形状を持ち、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