Trailmark MCP 服务器

Trailmark MCP 服务器是 的一个独立 MCP 封装。

虽然我了解 ToB 在 中的用法，但我的用例需要一个能够分析并服务于多个图表的 MCP 服务器。该服务器可以扫描多个仓库，LLM 可以分别从每个仓库请求信息。

主要由 OpenAI GPT-5.5 通过 VS Code 中的 Github Copilot 创建。请将您的 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(...) 调用都会创建一个新的会话 ID

• 多个实时会话可以共存

• 工具接受 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: 用于 scan 和 serve 的 CLI 入口点

• 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.json 文件直接通过 MCP 启动此服务器。

典型设置：

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 和此项目的环境中运行。