Trailmark MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Trailmark MCP Server Open repository /workspace/project and show its graph summary"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Trailmark MCP Server
Trailmark MCP Server is a standalone MCP wrapper around railofbits/trailmark.
While I do understand the ToB's usage with Claude skills, my usecase requires an MCP server that can analyze and server multiple graphs. The server can scan multiple repositories and the LLM can request information from each separately.
Mostly created with OpenAI GPT-5.5 via Github Copilot in VS Code. Point your LLM to the ai-docs directory for documentation and development support.
Requirements
Python 3.12+
uv
Project metadata:
package name:
trailmark-mcpCLI command:
trailmark-mcp
Related MCP server: graphward
Install
Install runtime and development dependencies:
uv sync --group devQuick Start
Start server over stdio:
uv run trailmark-mcp serve --transport stdioSmoke-test direct scan path without an MCP client:
uv run trailmark-mcp scan /path/to/repoSkip preanalysis during scan when needed:
uv run trailmark-mcp scan /path/to/repo --skip-preanalysisHow The Server Works
Primary lifecycle entrypoint is open_repository(...).
Behavior summary:
if no snapshot exists, the server scans source, optionally runs preanalysis, and saves the first snapshot
if a snapshot exists and
rescan=False, the server reloads the latest snapshot into a live sessionif
rescan=True, the server rebuilds from source and saves a fresh snapshot
This means the common flow is:
call
open_repositoryuse graph tools against returned session
call
save_snapshotafter meaningful in-memory mutations when you want persistence
Session Model
session_id is MCP wrapper state, not Trailmark core state.
Current semantics:
each
open_repository(...)call creates a new session idmultiple live sessions can coexist
tools accept
session_idto target a specific graphomitted
session_iduses the most recently opened still-open sessionclosing the default session promotes the most recently opened remaining session
Use current_repository(session_id=...) to verify which repository a session points to.
Public MCP Tools
Lifecycle:
open_repositorycurrent_repositoryclose_repositorysave_snapshot
Navigation:
graph_summarydiff_graphssearch_nodescallers_ofcallees_ofancestors_ofreachable_frompaths_betweenentrypoint_paths_toattack_surfacecomplexity_hotspotsfunctions_that_raise
Context and mutation:
subgraphannotations_offindingsnodes_with_annotationrun_preanalysisannotate_nodeclear_annotationsaugment_findings
Notes:
diff_graphs(before_session_id, after_session_id)treatsafteras the new statesearch_nodessupportscontains,exact, andsuffixremoved helper surfaces like
scan_repositoryandtool_manifestare intentionally not part of the public runtime anymore
Snapshot Behavior
Snapshots are written under the analyzed repository, not under this server repository:
<target-repo>/.trailmark/snapshots/<timestamp>/Current snapshot artifacts include:
graph.jsonsummary.jsonentrypoints.jsonhotspots.jsonsubgraphs.jsonscan-metadata.json
Snapshots support reload into a live session. Use rescan=True when you explicitly need a fresh rebuild from source.
Repository Layout
Key files:
src/trailmark_mcp/cli.py: CLI entrypoint forscanandservesrc/trailmark_mcp/mcp_app.py: MCP tool registrationsrc/trailmark_mcp/tool_catalog.py: declarative metadata for exposed toolssrc/trailmark_mcp/services/registry.py: session trackingsrc/trailmark_mcp/services/runtime.py: main Trailmark-backed runtime behavior
Development
Run focused test suite:
uv run --group dev pytest tests/test_tool_catalog.py tests/test_registry.py tests/test_stdio_server.pyCurrent CI runs that same focused suite on Python 3.12.
Extension rule:
add or change runtime behavior
register tool in
mcp_app.pyupdate metadata in
tool_catalog.pyupdate tests
update docs if public behavior changed
Use In VS Code
VS Code can launch this server directly through MCP using a workspace-level mcp.json file.
Typical setup:
open this repository in VS Code
make sure dependencies are installed with
uv sync --group devkeep the server definition in
.vscode/mcp.jsonlet the MCP client start the server over
stdio
This repository already includes .vscode/mcp.json for local use.
Example mcp.json:
{
"servers": {
"trailmark-mcp": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"trailmark-mcp",
"serve",
"--transport",
"stdio"
]
}
}
}If you use this server from a larger multi-project workspace, copy the same definition into that workspace root's .vscode/mcp.json and make sure the command runs in an environment where uv and this project are available.
Available Tools
24 toolsancestors_ofC
Return transitive callers that can reach the node.
Inputs: name (required), session_id. Returns: result
annotate_nodeC
Attach an annotation to a graph node.
Inputs: name (required), kind (required), description (required), source, +1 more. Returns: object
annotations_ofB
Return annotations for a node, optionally filtered by kind.
Inputs: name (required), kind, session_id. Returns: result
attack_surfaceC
Return detected entrypoints and trust metadata.
Inputs: session_id. Returns: result
augment_findingsB
Import findings into the current graph from SARIF or weAudit.
Inputs: path (required), format (required), session_id. Returns: object
callees_ofC
Return direct callees of a node.
Inputs: name (required), session_id. Returns: result
callers_ofC
Return direct callers of a node.
Inputs: name (required), session_id. Returns: result
clear_annotationsC
Remove annotations from a node.
Inputs: name (required), kind, session_id. Returns: object
close_repositoryB
Close an active repository session.
Inputs: session_id. Returns: object
complexity_hotspotsC
Return nodes whose cyclomatic complexity meets the threshold.
Inputs: threshold, session_id. Returns: result
current_repositoryC
Return metadata for the active repository session.
Inputs: session_id. Returns: object
diff_graphsC
Return a structured diff of the after graph relative to the before graph.
Inputs: before_session_id (required), after_session_id (required). Returns: object
entrypoint_paths_toC
Return paths from detected entrypoints to the target node.
Inputs: name (required), max_depth, session_id. Returns: result
findingsC
Return nodes carrying finding-style annotations.
Inputs: kind, session_id. Returns: result
functions_that_raiseC
Return functions whose parser-detected exception list includes the named exception.
Inputs: exception_name (required), session_id. Returns: result
graph_summaryC
Return graph counts and dependency summary.
Inputs: session_id. Returns: object
nodes_with_annotationC
Return nodes carrying a specific annotation kind.
Inputs: kind (required), session_id. Returns: result
open_repositoryC
Open a repository, loading latest snapshot or scanning source as needed.
Inputs: repo_path (required), language, rescan, run_preanalysis. Returns: object
paths_betweenC
Return call paths between two nodes.
Inputs: src (required), dst (required), session_id. Returns: result
reachable_fromC
Return nodes transitively reachable from the source node.
Inputs: name (required), session_id. Returns: result
run_preanalysisD
Run Trailmark preanalysis on the active engine.
Inputs: session_id. Returns: object
save_snapshotC
Persist the current graph state under .trailmark/snapshots.
Inputs: session_id. Returns: object
search_nodesC
Search graph nodes using contains, exact, or suffix matching.
Inputs: query (required), match_mode, limit, session_id. Returns: result
subgraphC
Return available subgraph names or the nodes in a named subgraph.
Inputs: name, session_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool targets a distinct operation: graph traversal (ancestors_of, callees_of, callers_of, reachable_from), annotation management (annotate_node, annotations_of, clear_annotations, nodes_with_annotation), repository lifecycle (open_repository, close_repository, current_repository, save_snapshot), and analysis (attack_surface, complexity_hotspots, findings, etc.). No two tools have overlapping purposes.
Tool names follow two predictable patterns: query-like operations use noun_of (e.g., ancestors_of, callees_of, callers_of) and action operations use verb_noun (e.g., annotate_node, open_repository, save_snapshot). This pattern is consistent throughout the set, with no mixing of casing styles or ambiguous verbs.
With 24 tools, the count is slightly above the typical well-scoped range (3-15) but still appropriate for a comprehensive code analysis server covering graph traversal, annotations, repository management, and analysis features. The tools are logically grouped and each serves a distinct purpose, so the number does not feel excessive.
The tool surface covers core workflows: opening/closing repositories, scanning, traversing the call graph, managing annotations, and querying findings. Minor gaps exist, such as no tool to list all repositories (only current_repository) or to delete nodes/annotations, but these do not critically hinder typical use cases for a static analysis tool.
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Read-only MCP server for repository context: context packs, graph impact analysis, and validation.
Shared context for your codebase: a hosted code knowledge graph over MCP. Free plan, OAuth sign-up.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceStandalone MCP harness for cross-system process evidence, code-change impact review, and natural-language repository checkout mapping, with optional accelerators like CodeGraph.1MIT
- AlicenseNot gradedqualityBmaintenancePrivate, local-first code intelligence MCP server that builds a static graph of repositories and exposes search, architecture, impact analysis, and review tools via MCP.MIT
- AlicenseNot gradedqualityDmaintenanceExposes code graphs across multi-program repositories via MCP, enabling humans and agents to query the fleet with evidence.MIT
- AlicenseNot gradedqualityDmaintenanceProvides a code graph querying and visualization MCP server, enabling users to search, trace, and describe code components, overlay diffs, and explore architecture through natural language.MIT