mcp-debug-recorder

mcp-debug-recorder는 "이 문제를 이전에 해결한 적이 있는가?"라는 간단한 질문에 빠르게 답해줍니다.

이 도구는 디버그 세션, 터미널 명령어, 실패한 시도 및 성공적인 수정 사항을 로컬 SQLite 데이터베이스에 기록하여, MCP 클라이언트가 자연어로 자신의 디버깅 기록을 조회할 수 있도록 합니다.

빠른 시작

npx mcp-debug-recorder

기본적으로 데이터는 ~/.mcp-debug-recorder/sessions.db에 저장됩니다.

아키텍처

src/
├── db.ts           - openDb(), createTestDb(), versioned MIGRATIONS[]
├── store.ts        - Store class with dependency-injected SQLite access
├── search.ts       - FTS5 + Fuse.js hybrid search
├── tools/          - MCP tool handlers grouped by session/search/admin concerns
├── types.ts        - Zod schemas and TypeScript types
├── mcp.ts          - MCP server wiring + tool registration
├── server-http.ts  - Streamable HTTP transport
├── logging.ts      - Structured logging with secret redaction
└── version.ts      - Package version helper

스키마 버전 관리

데이터베이스 스키마는 PRAGMA user_version을 통해 버전이 관리됩니다. 마이그레이션은 시작 시 자동으로 실행되므로 업그레이드 시 수동 SQL 작업이 필요하지 않습니다.

사용자 지정 데이터베이스 경로 추가

DEBUG_RECORDER_DB=/path/to/custom.db npx mcp-debug-recorder

구성

환경 변수

• DEBUG_RECORDER_DB: SQLite 데이터베이스 경로 재정의

• PORT: 스트리밍 HTTP 모드를 위한 HTTP 서버 포트 재정의

• LOG_LEVEL: 최소 구조화된 로그 레벨 (debug, info, warn, error)

• FUZZY_THRESHOLD: 순위 재조정(reranking) 시 사용되는 Fuse.js 임계값 재정의

사용 가능한 도구

• start_debug_session: 새로운 이슈 추적 시작

• add_fix: 실패했거나 성공한 수정 시도 기록

• record_command: 터미널 명령어와 그 출력 저장

• close_session: 세션을 해결됨 또는 포기됨으로 표시

• update_session: 제목, 설명 또는 태그 편집

• delete_session: 명시적 확인을 통해 세션을 영구적으로 삭제

• search_sessions: FTS5 + 퍼지 순위 재조정을 사용하여 과거 세션 검색

• find_similar_errors: 이전에 유사한 오류를 본 적이 있는지 확인

• get_session: 전체 세션 세부 정보 가져오기

• get_session_context: AI가 이해하기 쉬운 세션 요약 가져오기

• list_sessions: 필터를 사용하여 세션 탐색

• get_stats: 디버그 기록 요약

• export_sessions: 백업 또는 마이그레이션을 위해 로컬 기록 내보내기

• import_sessions: 이전에 내보낸 JSON 페이로드 가져오기

Claude Desktop 구성

{
  "mcpServers": {
    "mcp-debug-recorder": {
      "command": "npx",
      "args": ["mcp-debug-recorder"]
    }
  }
}

VS Code MCP 구성

{
  "servers": {
    "mcp-debug-recorder": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-debug-recorder"]
    }
  }
}

실제 사용 예시

이전에 본 적이 있는가?

"TypeError: Cannot read properties of undefined 오류가 발생하는데, 이전에 본 적이 있나요?"

현재 오류 텍스트로 find_similar_errors를 호출한 다음, get_session_context로 가장 일치하는 항목을 검사합니다.

활성 인시던트 기록

1. start_debug_session 호출

2. record_command로 터미널 명령어 추가

3. add_fix로 각 수정 시도 추가

4. 제목이나 메모가 명확해지면 update_session 사용

5. close_session으로 세션 종료

로컬 디버그 기록 백업

1. format: "json"으로 export_sessions 호출

2. 반환된 JSON을 선호하는 백업 시스템에 저장

3. 나중에 import_sessions로 복원

데이터 저장소

• 기본 경로: ~/.mcp-debug-recorder/sessions.db

• better-sqlite3를 사용한 휴대용 SQLite 저장소

• 대규모 기록을 위한 FTS5 기반 검색 인덱스

• 외부 데이터베이스 서버 불필요

참고: better-sqlite3는 네이티브 애드온을 사용합니다. 바인딩 오류가 발생하면 사용 중인 Node 버전에 맞춰 npm rebuild better-sqlite3를 실행하세요.

HTTP 전송

이 패키지는 스트리밍 HTTP도 지원합니다:

npm run start:http

유용한 경로:

• GET /health

• GET /version

• MCP 엔드포인트: POST/GET/DELETE /mcp

개발

npm ci
npm run lint
npm test
npm run build
npm run test:e2e
npm run docs:api

릴리스 검증:

npm run format:check
npm run test:coverage
npm run prepublishOnly

추가 프로젝트 문서:

• 사용법

• 구성

• 아키텍처

• 검색 알고리즘

• 릴리스 흐름

• 버전 관리 정책

• 로드맵