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-сервера для режима Streamable HTTP

• LOG_LEVEL: минимальный уровень структурированного логирования (debug, info, warn, error)

• FUZZY_THRESHOLD: переопределить порог 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: получить краткую сводку сеанса, удобную для ИИ

• list_sessions: просматривать сеансы с фильтрами

• get_stats: получить сводку вашей истории отладки

• export_sessions: экспортировать вашу локальную историю для резервного копирования или миграции

• import_sessions: импортировать ранее экспортированные данные в формате JSON

Настройка клиента

Claude Desktop

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

VS Code / GitHub Copilot

Создайте или обновите .vscode/mcp.json:

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

Codex CLI

codex mcp add mcp-debug-recorder -- npx mcp-debug-recorder
codex mcp list

Gemini CLI

gemini mcp add mcp-debug-recorder npx mcp-debug-recorder
gemini mcp list

Antigravity

antigravity --add-mcp "{\"name\":\"mcp-debug-recorder\",\"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. Вызовите export_sessions с параметром format: "json"

2. Сохраните полученный JSON в вашей предпочтительной системе резервного копирования

3. Восстановите позже с помощью import_sessions

Хранение данных

• Путь по умолчанию: ~/.mcp-debug-recorder/sessions.db

• Портативное хранилище SQLite с использованием better-sqlite3

• Поисковый индекс на базе FTS5 для больших историй

• Не требуется внешний сервер базы данных

Примечание: better-sqlite3 использует нативный аддон. Если вы видите ошибки привязки, выполните npm rebuild better-sqlite3 для вашей версии Node.

HTTP-транспорт

Пакет также поддерживает Streamable 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

Дополнительная документация проекта:

• Использование

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

• Архитектура

• Алгоритм поиска

• Процесс релиза

• Политика версионирования

• Дорожная карта