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는 선택 사항이며 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

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

상태 및 개인정보 보호

상태 저장소는 모드 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