Knowerage — Управление покрытием анализа ИИ

Локальный MCP-сервер, который отслеживает покрытие анализа устаревшего кода и его актуальность.

Исходный код: github.com/MTimma/knowerage

Быстрый старт

Требования: Node.js 18 или новее — npx должен быть в вашем PATH (он поставляется вместе с npm, который включен в Node).

Related MCP server: Atlas

Конфигурация MCP-сервера

Зарегистрируйте Knowerage там, где ваш MCP-хост ожидает определения серверов (например, некоторые клиенты используют .cursor/mcp.json или .vscode/mcp.json; другие используют переменные окружения или интерфейс — следуйте документации вашего хоста). Используйте следующую структуру записи сервера:

{
  "mcpServers": {
    "knowerage": {
      "command": "npx",
      "args": ["@mtimma/knowerage"],
      "env": {
        "KNOWERAGE_WORKSPACE_ROOT": "${workspaceFolder}",
        "KNOWERAGE_AUTO_FULL_RECONCILE": "true"
      }
    }
  }
}

Замените ${workspaceFolder} на корневой каталог вашего проекта, если ваш хост не раскрывает эту переменную автоматически.

KNOWERAGE_AUTO_FULL_RECONCILE является необязательным: если параметр не задан, пуст или не имеет истинного значения, файловый наблюдатель по умолчанию выключен. Установите значение 1, true, yes или on (без учета регистра, пробелы обрезаются), чтобы включить его. Когда параметр включен, сервер отслеживает директорию knowerage/ и после короткой задержки (debounce) запускает knowerage_reconcile_all при изменениях в файловой системе. Это не то же самое, что запуск полной сверки после каждого вызова инструмента MCP — он реагирует только на изменения файлов внутри knowerage/. Записи реестра в registry.json игнорируются наблюдателем, поэтому сохранения не вызывают циклов.

Как использовать Knowerage

После настройки MCP-сервера вы общаетесь со своим помощником обычными предложениями. Вам не нужно запоминать названия инструментов.

Анализ или документирование кода

Указывайте на файлы, классы или поведение, которые вас интересуют. Например:

• Используя Knowerage, проанализируй логику алгоритма в main.java.

• Проанализируй логику сверки сущностей данных и версионирования в сервисе ETL.

Помощник создает или обновляет Markdown-файлы в knowerage/analysis/ и записывает покрытие в knowerage/registry.json (см. Как это работает ниже).

Покрытие и пробелы (тот же проект, последующий чат или другой агент)

Когда у вас уже есть анализы в дереве, вы можете спросить:

• В процентах, какая часть кода покрыта нашим анализом?

• Какая часть этой кодовой базы еще не проанализирована?

Knowerage отвечает на эти вопросы, основываясь на реестре и вспомогательных средствах покрытия (например, обзор, статус по файлам и списки устаревших данных) — а не на общих фразах о репозитории.

Альтернативные подходы

Установка через npm

npx @mtimma/knowerage

Или сборка из исходного кода

cargo build --release
./target/release/knowerage-mcp

Как это работает

1. ИИ-агент создает .md файлы анализа с YAML-заголовком (frontmatter), объявляющим исходный файл и диапазоны покрытых строк

2. Реестр (knowerage/registry.json) отслеживает записи анализа с хешами SHA-256 для проверки актуальности

3. Инструменты MCP предоставляют операции создания, сверки, запроса и экспорта

4. Агент говорит "проанализируй X" → автоматически запускается полный рабочий процесс (создание → сверка → запись)

Структура файла реестра (knowerage/registry.json)

Формат на диске представляет собой JSON-объект, ключами которого являются пути к анализам (строки). Каждое значение — это одна запись (см. contracts/contracts.md). Полный пример с двумя записями находится в examples/registry.sample.json.

flowchart TB
  subgraph file["knowerage/registry.json"]
    O["Top-level JSON object"]
    O --> K["Each key: analysis markdown path, e.g. knowerage/analysis/.../topic.md"]
    K --> V["Value: one RegistryRecord"]
  end

  subgraph rec["RegistryRecord fields"]
    ap["analysis_path · source_path"]
    cr["covered_ranges: [[start,end], ...]"]
    h["analysis_hash · source_hash (sha256:… )"]
    t["record_created_at · record_updated_at (ISO 8601)"]
    st["status: fresh | stale_doc | stale_src | missing_src | dangling_doc"]
  end

  V --> rec

Заголовки (frontmatter) для .md файлов анализа определяются отдельно в документации по контрактам (схема метаданных), а не внутри registry.json.

Инструменты MCP

Структура проекта

knowerage/                  # Created per-project
├── analysis/              # Analysis markdown files
│   └── **/*.md
└── registry.json          # Coverage registry

src/                       # Rust MCP server
├── main.rs
├── lib.rs
├── types.rs
├── parser.rs
├── registry.rs
├── mcp.rs
├── security.rs
└── export.rs

Документация

• Онбординг пользователя — Установка, конфигурация, типичное использование

• INSTRUCTIONS.md — Инструкции для MCP-агента

• Практики Rust

• Практики JS

• Контракты — Схемы и API-контракты (реестр + заголовки)

• Пример JSON реестра — Содержимое примера registry.json

Безопасность

• Все пути проверяются относительно корня рабочей области

• Обход путей (..) отклоняется

• Атомарная запись для реестра (защита от сбоев)

• Никаких секретов в файлах анализа или отчетах

• Актуальность на основе хеша SHA-256 (сохраняется после git pull)

Лицензия

MIT — авторское право Martins Timma.

Части этого проекта были написаны или доработаны с помощью генеративных ИИ-помощников для написания кода. Человеческая проверка применяется к дизайну, критически важным для безопасности аспектам и релизам.