project-map-mcp

Вспомогательный MCP-сервер, который берёт на себя всю механику построения карты проекта (ID событий, даты, проценты, планы файлов, переходы между частями, синхронизацию, финализацию), чтобы маленькая локальная модель (Qwen 3.8-9B) отвечала только за контент — что читать и как классифицировать.

• Версия сервера: 1.11.2

• Поддерживаемая версия промпта: 4.10.1 (scan_prompt/4101.txt)

В начале сессии модель вызывает map_version() и сверяет версии сервера и промпта — актуальный промпт требует сервер ≥ 1.10.7.

Формат хранения событий: map/events.jsonl — один JSON-объект на строку, сервер сам его сериализует. Никакого ручного экранирования кавычек моделью больше не требуется. Совместимость со старыми events/*.json не сохраняется (это осознанное упрощение) — если нужно перенести старые события, допиши конвертер.

Сборка и запуск в Docker

cd project-map-mcp
# проверьте docker-compose.yml — путь к проекту на хосте в volumes
docker compose up -d --build

Проверить, что сервер поднялся:

curl -i http://localhost:8765/mcp

Два порта:

• 8765 — сам MCP-сервер (эндпоинт /mcp);

• 8766 — веб-dashboard карты (см. ниже), если не отключён.

Related MCP server: KnowledgeRail

Важно про пути

По умолчанию весь проект монтируется в контейнер как <хост>:/projects, а карта строится по подкаталогу scan:

volumes:
  - "E:/.../Tezam.Parser:/projects"
environment:
  MAP_ROOT: /projects/scan     # где лежит карта (parts/, map/)
  SOURCE_ROOT: /projects       # корень для путей внутри событий

Пути внутри parts/part_*.txt (например /projects/scan/chat-export-...json) должны буквально совпадать с путями внутри контейнера — тот же корень, что использует j0hanz/filesystem-mcp. Меняются через env MAP_ROOT / SOURCE_ROOT (или одноимённые поля в конфиге).

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

Параметры сервера задаются в трёх слоях по приоритету (меньший перезаписывается большим):

дефолты в server.py  <  map_config.toml  <  env-переменные

map_config.toml создаётся автоматически при первом запуске и лежит рядом с картой. Менять конфиг можно не только файлом, но и в рантайме — инструментами map_config() (показать текущие значения и их источники) и map_set_config(section, key, value) (изменить и сохранить в TOML). Не применяются на лету (нужен рестарт): server.host, server.port, paths.root, paths.source_root.

Основные env-переменные: MAP_ROOT, SOURCE_ROOT, PORT, MAP_HOST, MAP_DASHBOARD_ENABLED, MAP_DASHBOARD_PORT, лимиты MAP_MAX_BATCH_BYTES, MAP_MAX_FILES_PER_PACKET, MAP_MAX_EVENTS_PER_FILE, MAP_SOFT_EVENTS_LIMIT, MAP_MAX_PLAN_THEMES, MAP_CHUNKED_MAX_EVENTS_PER_FILE, MAP_CHUNK_CONFIDENCE_THRESHOLD, и группа embeddings (см. ниже).

Ключевые лимиты по умолчанию: max_batch_bytes=300000, max_files_per_packet=10 (размер пакета по умолчанию 3), max_events_per_file=10, max_plan_themes=20, chunked_max_events_per_file=15.

Опциональные embeddings

Для семантического поиска по связям событий (map_rebuild_parent_events) можно включить эмбеддинги через локальный эндпоинт LM Studio. По умолчанию выключено — связи считаются по lexical-пересечению описаний (IDF), а косинусная близость используется только как fallback при включённых embeddings.

• MAP_EMBEDDINGS_ENABLED (default false)

• MAP_EMBEDDINGS_URL (default http://localhost:1234/v1/embeddings)

• MAP_EMBEDDINGS_MODEL (default text-embedding-nomic-embed-text-v1.5@f32)

• MAP_EMBEDDINGS_TIMEOUT_SEC (default 35.0)

• MAP_EMBEDDINGS_MIN_SCORE (default 0.75)

Логика эмбеддингов вынесена в embeddings.py (embed_batch, cosine).

Dashboard

Если MAP_DASHBOARD_ENABLED (по умолчанию включён), на порту 8766 поднимается веб-просмотр карты: корень / отдаёт HTML-страницу (события, связи parent/related, прогресс, планы). Рядом — JSON-API: /api/status, /api/stats, /api/events?limit=N, /api/events/<id>, /api/plans, /api/config (GET читает, POST меняет конфиг в рантайме). Отключается MAP_DASHBOARD_ENABLED=false, порт — MAP_DASHBOARD_PORT.

⚠️ В текущем docker-compose.yml проброшен только 8765:8765, поэтому dashboard с хоста недоступен, пока не добавите маппинг:

ports:
  - "8765:8765"
  - "8766:8766"   # чтобы открыть http://localhost:8766/

Подключение в LM Studio

Откройте ~/.lmstudio/mcp.json (Program → Install → Edit mcp.json) и добавьте блок "project-map" из mcp.json.example к уже существующим записям для j0hanz-filesystem и mcp-filesystem — их трогать не нужно, они по-прежнему нужны для чтения (read/read_file/read_multiple_files/list/stat/ search_text). В Developer → Settings включите "Allow remote MCP", если сервер не появится в списке инструментов сразу.

⚠️ Сервер протестирован локально на тестовых данных (батчинг, генерация ID, дат, sync, finalize — см. лог smoke-теста), но не тестировался живьём внутри LM Studio — если формат mcp.json для remote-серверов будет отличаться (например потребуется "transport": "http" явно), поправьте по документации LM Studio → MCP.

Инструменты

Полный набор (докстринги — в server.py). Модель не выбирает их наугад: последовательность вызовов задаёт промпт scan_prompt/4101.txt.

Версии и конфиг:

• map_version() — версия сервера и поддерживаемая версия промпта.

• map_config() — текущая конфигурация и её источники.

• map_set_config(section, key, value) — изменить параметр в рантайме (+ TOML).

Основной цикл:

• map_status() — статус одной строкой, включая активный batch_id и планы.

• map_set_batch_size(n) — размер пакета, от 1 до 10.

• map_get_batch() — следующий пакет файлов (+ компактный recent_context).

• map_plan_file(file_path, themes, confidence) — зафиксировать план тем для файла ДО первого события; обязательный первый шаг обработки файла.

• map_create_event(...) — создать событие (ID/дату/parent_event/confidence считает сервер).

• map_complete_batch(batch_id) — завершить обычный пакет (ровно один раз).

• map_cancel_batch(batch_id, discard_events, kind) — отменить зависший пакет (kind="normal" или "recovery").

Анализ и поиск:

• map_recent_events(limit) — компактный список последних событий.

• map_find_by_path(file_path) — события по пути файла.

• map_find_related_events(query, limit) — события по теме.

• map_find_sparse_events() — события с пустыми error_logs/fixes/related_issues.

• map_rebuild_parent_events(min_overlap, force) — пересчитать parent_event у всех событий (только по явной команде пользователя).

Синхронизация и восстановление:

• map_delete_events_for_path(file_path) — убрать события файла в trash и пометить файл непройденным (активные пакеты сбрасываются).

• map_sync() — пересчитать state.json по фактическим событиям (может требовать нескольких вызовов; отказывает при активном пакете с событиями).

• map_recover_scan(scope, part_id, from_part, to_part) — собрать список файлов без событий (scope="current"|"all"|"range").

• map_recover_get_batch() / map_recover_complete_batch(batch_id) — пакетная доработка пропусков (в map_create_event передавай recovery=True).

Финализация:

• map_finalize() — собрать итоговые отчёты (только когда обработаны все файлы и нет активных пакетов).

Обновление сервера

server.py и embeddings.py монтируются в контейнер bind-mount'ом (см. volumes в docker-compose.yml), поэтому правка кода применяется простым рестартом:

docker compose restart

Пересборка образа нужна только если изменились зависимости (requirements.txt / Dockerfile):

docker compose up -d --build