Servidor MCP de Trailmark

El servidor MCP de Trailmark es un envoltorio MCP independiente para .

Aunque entiendo el uso que hace ToB con , mi caso de uso requiere un servidor MCP que pueda analizar y servir múltiples grafos. El servidor puede escanear múltiples repositorios y el LLM puede solicitar información de cada uno por separado.

Creado principalmente con OpenAI GPT-5.5 a través de Github Copilot en VS Code. Dirija su LLM al directorio ai-docs para obtener documentación y soporte de desarrollo.

Requisitos

• Python 3.12+

• uv

Metadatos del proyecto:

• nombre del paquete: trailmark-mcp

• comando CLI: trailmark-mcp

Instalación

Instale las dependencias de tiempo de ejecución y desarrollo:

uv sync --group dev

Inicio rápido

Inicie el servidor a través de stdio:

uv run trailmark-mcp serve --transport stdio

Prueba de humo de la ruta de escaneo directo sin un cliente MCP:

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

Omita el preanálisis durante el escaneo cuando sea necesario:

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

Cómo funciona el servidor

El punto de entrada principal del ciclo de vida es open_repository(...).

Resumen del comportamiento:

• si no existe ninguna instantánea, el servidor escanea la fuente, ejecuta opcionalmente el preanálisis y guarda la primera instantánea

• si existe una instantánea y rescan=False, el servidor recarga la última instantánea en una sesión activa

• si rescan=True, el servidor reconstruye desde la fuente y guarda una instantánea nueva

Esto significa que el flujo común es:

1. llamar a open_repository

2. usar herramientas de grafo contra la sesión devuelta

3. llamar a save_snapshot después de mutaciones significativas en memoria cuando desee persistencia

Modelo de sesión

session_id es el estado del envoltorio MCP, no el estado central de Trailmark.

Semántica actual:

• cada llamada a open_repository(...) crea un nuevo ID de sesión

• pueden coexistir múltiples sesiones activas

• las herramientas aceptan session_id para apuntar a un grafo específico

• el session_id omitido utiliza la sesión abierta más recientemente que aún esté abierta

• cerrar la sesión predeterminada promueve la sesión restante abierta más recientemente

Utilice current_repository(session_id=...) para verificar a qué repositorio apunta una sesión.

Herramientas MCP públicas

Ciclo de vida:

• open_repository

• current_repository

• close_repository

• save_snapshot

Navegación:

• 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

Contexto y mutación:

• subgraph

• annotations_of

• findings

• nodes_with_annotation

• run_preanalysis

• annotate_node

• clear_annotations

• augment_findings

Notas:

• diff_graphs(before_session_id, after_session_id) trata a after como el nuevo estado

• search_nodes admite contains, exact y suffix

• las superficies auxiliares eliminadas como scan_repository y tool_manifest ya no forman parte intencionalmente del tiempo de ejecución público

Comportamiento de las instantáneas

Las instantáneas se escriben bajo el repositorio analizado, no bajo este repositorio del servidor:

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

Los artefactos de instantánea actuales incluyen:

• graph.json

• summary.json

• entrypoints.json

• hotspots.json

• subgraphs.json

• scan-metadata.json

Las instantáneas admiten la recarga en una sesión activa. Use rescan=True cuando necesite explícitamente una reconstrucción nueva desde la fuente.

Diseño del repositorio

Archivos clave:

• src/trailmark_mcp/cli.py: punto de entrada CLI para scan y serve

• src/trailmark_mcp/mcp_app.py: registro de herramientas MCP

• src/trailmark_mcp/tool_catalog.py: metadatos declarativos para herramientas expuestas

• src/trailmark_mcp/services/registry.py: seguimiento de sesiones

• src/trailmark_mcp/services/runtime.py: comportamiento principal del tiempo de ejecución respaldado por Trailmark

Desarrollo

Ejecute la suite de pruebas enfocada:

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

La CI actual ejecuta esa misma suite enfocada en Python 3.12.

Regla de extensión:

1. agregar o cambiar el comportamiento del tiempo de ejecución

2. registrar la herramienta en mcp_app.py

3. actualizar los metadatos en tool_catalog.py

4. actualizar las pruebas

5. actualizar la documentación si cambió el comportamiento público

Uso en VS Code

VS Code puede iniciar este servidor directamente a través de MCP utilizando un archivo mcp.json a nivel de espacio de trabajo.

Configuración típica:

1. abra este repositorio en VS Code

2. asegúrese de que las dependencias estén instaladas con uv sync --group dev

3. mantenga la definición del servidor en .vscode/mcp.json

4. deje que el cliente MCP inicie el servidor a través de stdio

Este repositorio ya incluye .vscode/mcp.json para uso local.

Ejemplo de mcp.json:

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

Si utiliza este servidor desde un espacio de trabajo multiproyecto más grande, copie la misma definición en el .vscode/mcp.json de la raíz de ese espacio de trabajo y asegúrese de que el comando se ejecute en un entorno donde uv y este proyecto estén disponibles.