Code Context Storage MCP

code-context-storage-mcp — это локальное хранилище базы знаний кода и сервис протокола MCP. Он сохраняет узлы кода, рёбра вызовов, семантическую информацию, доказательства, бизнес-каталог/маппинги и версионные снимки в SQLite, а через stdio transport FastMCP предоставляет наружу структурированные tools.

Проект занимает позицию между «Skill / внешним ИИ» и персистентными бизнес-возможностями: вызывающая сторона читает и пишет базу знаний через MCP tools и не должна обращаться к SQLite напрямую. MVP ориентирован на один репозиторий кода и фиксированную версию исходников, с фокусом на импорт индексов/артефактов, запросы с ограничением по версии, бизнес-маппинги, проверку доказательств, инкрементальную синхронизацию, публикацию снимков и оценку.

Features

• Персистентные факты кода в SQLite: node, edge, evidence, node_semantic.

• Поиск узлов на основе семантики и бизнес-слов, а также контекст графа, пути и анализ влияния с ограничением бюджета.

• Бизнес-каталог, context, mapping и шаги маппинга; кандидаты и подтверждённые результаты имеют явные статусы.

• Процесс публикации снимков staging → published с идемпотентными операциями, защитой от гонок через CAS и распространением/восстановлением stale.

• MCP protocol v2 envelope: request_id, operation_id, версии schema/tool и структурированные ошибки.

• Тестовое покрытие: unit, контрактные, black-box и сценарии реального stdio MCP-адаптера.

Вне области проекта: генерация/исполнение кода, единый граф по нескольким репозиториям, автоматическое бизнес-моделирование без подтверждения человеком и смешивание runtime-наблюдений со статическими фактами кода. Полные границы — в документе MVP-дизайна.

Related MCP server: local-code-intel-mcp

Requirements

• Python 3.11 или новее

• pip

• В примерах для Windows PowerShell рабочей директорией является корень репозитория

Зависимости объявлены в pyproject.toml; ключевая runtime-зависимость — fastmcp==3.4.7.

Install

Рекомендуется использовать виртуальное окружение:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

Если PowerShell запрещает активацию скриптов, можно не активировать окружение и выполнять команды ниже напрямую через .\.venv\Scripts\python.exe.

Run the MCP server

После установки используйте предоставленную командную точку входа проекта:

code-context-storage-mcp --database .data\context.db

Или напрямую модульную точку входа:

python -m code_context_storage_mcp.server --database .data\context.db

Оба способа запуска используют stdio transport. Процесс читает MCP JSON-RPC сообщения из stdin и пишет ответы в stdout, поэтому не добавляйте обычные логи в stdout; путь к базе данных по умолчанию — .data/context.db, другой SQLite-файл можно указать через --database.

Просмотр аргументов командной строки:

code-context-storage-mcp --help

MCP client configuration

stdio-клиент должен запускать следующую команду и писать запросы в stdin:

{
  "mcpServers": {
    "code-context-storage": {
      "command": "code-context-storage-mcp",
      "args": ["--database", ".data/context.db"]
    }
  }
}

Если console script не установлен, можно заменить command на Python, а args на:

["-m", "code_context_storage_mcp.server", "--database", ".data/context.db"]

После подключения клиент сначала вызывает tools/list MCP, чтобы увидеть зарегистрированные tools и их входные schema. Tools покрывают запись/чтение фактов кода, запросы к графу, бизнес-каталог и маппинги, управление синхронизацией, публикацию, доказательства, генерацию знаний и оценку; конкретный набор регистраций определяется tools/list, возвращаемым сервисом в рантайме.

Development commands

Выполняется в корне репозитория:

python -m pytest tests -q

Запуск black-box тестов:

python -m pytest tests\blackbox -q

Для сценариев black-box тестов, которым нужен реальный MCP stdio-сервис, команда сервиса настраивается так:

$env:PYTHONPATH = "src"
$env:KNOWLEDGE_GENERATE_MCP_COMMAND = '["python", "-m", "code_context_storage_mcp.server"]'
python -m pytest tests\blackbox -q

Некоторые black-box тесты пропускаются при отсутствии этой конфигурации; в CI её следует задавать явно, чтобы тесты выявляли проблемы конфигурации или протокола.

Phase acceptance and evaluation

Генерация отчёта Phase acceptance и сопутствующего evaluation request:

python scripts\run_phase_acceptance.py --output artifacts\phase-acceptance.json

Запуск офлайн-оценки с использованием сгенерированного запроса и порогов:

python scripts\run_evaluation.py `
  --request artifacts\evaluation-request.json `
  --thresholds artifacts\thresholds.json `
  --output artifacts\evaluation-result.json `
  --database .data\context.db

run_evaluation.py по умолчанию использует пустой набор ответов — это подходит для проверки конвейера оценки и входных контрактов; чтобы получить содержательные результаты оценки, следует передать black-box ответы MCP-клиента через --responses. Скрипт завершается с ненулевым кодом, если статус оценки не passed.

Repository layout

src/code_context_storage_mcp/
  server.py                 CLI 入口，创建 Store 并启动 stdio MCP 服务
  fastmcp_server.py         FastMCP server、tool 注册和 protocol envelope
  tool_definitions.py       tool 输入 schema
  router.py                 tool 到 handler/service 的分发
  handlers/                 代码事实、图查询和业务操作处理器
  services/                 查询、同步、索引、幂等、追踪等业务服务
  publication/              发布适配与发布服务
  store.py                  SQLite 持久化
  entities.py/contracts.py  数据实体与协议契约
migrations/                 SQLite schema migrations
tests/                      单元、契约、集成和黑盒测试
scripts/                    验收与评测脚本
docs/design/                设计文档

Основной путь выполнения: server.main -> Store -> create_mcp_server -> ToolRouter -> handlers/services -> SQLite. Операции записи обычно сначала попадают в staging, проходят проверки конфликтов/покрытия и лишь затем публикуют снимок; запросы фиксируются на одном снимке и версии исходников и возвращают прослеживаемый контекст выполнения.

Data and migrations

Файл базы данных по умолчанию .data/context.db — это runtime-данные, его не следует коммитить в репозиторий. Schema поддерживается SQL-файлами в migrations/; перед подключением к существующей базе данных с новым кодом следует убедиться, что соответствующая миграция применена. Тесты обычно используют временные SQLite-базы, поэтому не зависят от файла данных по умолчанию на машине разработчика.

License

В текущем репозитории нет отдельного файла лицензии; перед внешней публикацией необходимо добавить лицензию и описание вклада.