Trailmark MCP Server

Trailmark MCP Server — это автономная оболочка MCP вокруг .

Хотя я понимаю использование ToB с , мой сценарий использования требует MCP-сервера, который может анализировать и обслуживать несколько графов. Сервер может сканировать несколько репозиториев, а LLM может запрашивать информацию из каждого отдельно.

В основном создан с помощью OpenAI GPT-5.5 через Github Copilot в VS Code. Направьте свою LLM в директорию ai-docs для получения документации и поддержки разработки.

Требования

• Python 3.12+

• uv

Метаданные проекта:

• имя пакета: trailmark-mcp

• команда CLI: trailmark-mcp

Установка

Установите зависимости среды выполнения и разработки:

uv sync --group dev

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

Запустите сервер через stdio:

uv run trailmark-mcp serve --transport stdio

Проведите дымовое тестирование пути прямого сканирования без MCP-клиента:

uv run trailmark-mcp scan /path/to/repo

Пропустите предварительный анализ во время сканирования, когда это необходимо:

uv run trailmark-mcp scan /path/to/repo --skip-preanalysis

Как работает сервер

Основная точка входа жизненного цикла — open_repository(...).

Краткое описание поведения:

• если снимок состояния не существует, сервер сканирует исходный код, при необходимости выполняет предварительный анализ и сохраняет первый снимок

• если снимок существует и rescan=False, сервер перезагружает последний снимок в активную сессию

• если rescan=True, сервер пересобирает данные из исходного кода и сохраняет свежий снимок

Это означает, что типичный рабочий процесс выглядит так:

1. вызов open_repository

2. использование инструментов графа для возвращенной сессии

3. вызов save_snapshot после значимых изменений в памяти, когда вам нужна персистентность

Модель сессии

session_id — это состояние оболочки MCP, а не состояние ядра Trailmark.

Текущая семантика:

• каждый вызов open_repository(...) создает новый идентификатор сессии

• несколько активных сессий могут сосуществовать

• инструменты принимают session_id для работы с конкретным графом

• пропущенный session_id использует последнюю открытую сессию, которая все еще активна

• закрытие сессии по умолчанию делает последнюю открытую оставшуюся сессию текущей

Используйте current_repository(session_id=...), чтобы проверить, на какой репозиторий указывает сессия.

Публичные инструменты MCP

Жизненный цикл:

• open_repository

• current_repository

• close_repository

• save_snapshot

Навигация:

• graph_summary

• diff_graphs

• search_nodes

• callers_of

• callees_of

• ancestors_of

• reachable_from

• paths_between

• entrypoint_paths_to

• attack_surface

• complexity_hotspots

• functions_that_raise

Контекст и мутации:

• subgraph

• annotations_of

• findings

• nodes_with_annotation

• run_preanalysis

• annotate_node

• clear_annotations

• augment_findings

Примечания:

• diff_graphs(before_session_id, after_session_id) рассматривает after как новое состояние

• search_nodes поддерживает contains, exact и suffix

• удаленные вспомогательные поверхности, такие как scan_repository и tool_manifest, намеренно больше не являются частью публичной среды выполнения

Поведение снимков состояния

Снимки записываются внутри анализируемого репозитория, а не внутри репозитория этого сервера:

<target-repo>/.trailmark/snapshots/<timestamp>/

Текущие артефакты снимков включают:

• graph.json

• summary.json

• entrypoints.json

• hotspots.json

• subgraphs.json

• scan-metadata.json

Снимки поддерживают перезагрузку в активную сессию. Используйте rescan=True, когда вам явно нужна свежая пересборка из исходного кода.

Структура репозитория

Ключевые файлы:

• src/trailmark_mcp/cli.py: точка входа CLI для scan и serve

• src/trailmark_mcp/mcp_app.py: регистрация инструментов MCP

• src/trailmark_mcp/tool_catalog.py: декларативные метаданные для открытых инструментов

• src/trailmark_mcp/services/registry.py: отслеживание сессий

• src/trailmark_mcp/services/runtime.py: основное поведение среды выполнения на базе Trailmark

Разработка

Запустите целевой набор тестов:

uv run --group dev pytest tests/test_tool_catalog.py tests/test_registry.py tests/test_stdio_server.py

Текущая CI запускает тот же целевой набор тестов на Python 3.12.

Правило расширения:

1. добавьте или измените поведение среды выполнения

2. зарегистрируйте инструмент в mcp_app.py

3. обновите метаданные в tool_catalog.py

4. обновите тесты

5. обновите документацию, если изменилось публичное поведение

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

VS Code может запускать этот сервер напрямую через MCP, используя файл mcp.json на уровне рабочей области.

Типичная настройка:

1. откройте этот репозиторий в VS Code

2. убедитесь, что зависимости установлены с помощью uv sync --group dev

3. сохраните определение сервера в .vscode/mcp.json

4. позвольте MCP-клиенту запустить сервер через stdio

Этот репозиторий уже включает .vscode/mcp.json для локального использования.

Пример mcp.json:

{
  "servers": {
    "trailmark-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "trailmark-mcp",
        "serve",
        "--transport",
        "stdio"
      ]
    }
  }
}

Если вы используете этот сервер в более крупной рабочей области с несколькими проектами, скопируйте то же определение в .vscode/mcp.json в корне этой рабочей области и убедитесь, что команда выполняется в среде, где доступны uv и этот проект.