MCP Server

SwarmVault can expose a vault as a local MCP server with:

swarmvault mcp

The current release uses stdio transport and is meant for local agent and tooling integrations.

Why MCP Matters

MCP lets a compatible client treat the vault as a structured tool surface instead of a pile of files. That means an agent can:

  • search compiled pages
  • read generated markdown directly
  • inspect manifests and graph state
  • ask questions against the vault
  • build bounded context packs for handoff and review
  • record task ledgers with decisions, changed paths, outcomes, and follow-ups
  • inspect whole-vault health before deeper work
  • inspect and repair local retrieval health
  • ingest new material
  • trigger compile and lint runs

Tool Surface

SwarmVault currently exposes these tools:

  • workspace_info
  • search_pages
  • read_page
  • list_sources
  • query_vault
  • ingest_input
  • compile_vault
  • lint_vault
  • build_context_pack
  • list_context_packs
  • read_context_pack
  • start_task
  • update_task
  • finish_task
  • list_tasks
  • read_task
  • resume_task
  • start_memory_task
  • update_memory_task
  • finish_memory_task
  • list_memory_tasks
  • read_memory_task
  • resume_memory_task
  • retrieval_status
  • rebuild_retrieval
  • doctor_retrieval
  • doctor_vault
  • query_graph
  • graph_report
  • graph_stats
  • get_node
  • get_community
  • get_neighbors
  • get_hyperedges
  • shortest_path
  • god_nodes
  • blast_radius

Query Semantics

query_vault mirrors the core CLI query flow:

  • save defaults to true
  • format supports markdown, report, slides, chart, and image
  • saved visual queries write wrapper markdown pages plus local assets under wiki/outputs/assets/

That keeps MCP clients on the same durable artifact path as terminal users instead of creating a second-class query surface.

compile_vault mirrors the core compile flow too:

  • approve stages an approval bundle instead of mutating active pages
  • maxTokens trims lower-priority generated pages to keep the compiled vault inside a token budget

build_context_pack mirrors swarmvault context build. It accepts a goal, optional target, token budget, and output format, then writes the same wiki/context/ and state/context-packs/ artifacts used by CLI workflows.

The task tools mirror swarmvault task. They write task JSON under state/memory/tasks/, markdown companions under wiki/memory/tasks/, and let a client resume a task in markdown, json, or llms form without storing full transcripts. The memory tools remain compatibility aliases over the same records.

doctor_vault mirrors swarmvault doctor: it summarizes graph, retrieval, review queue, watch, migration, managed-source, and task health, with optional safe retrieval repair. The retrieval tools mirror swarmvault retrieval. They report freshness, rebuild the local SQLite FTS shard, and can repair stale artifacts under state/retrieval/.

The graph tools stay read-only and deterministic. They work from the compiled graph plus local search state rather than calling an external model. graph_stats returns lightweight graph counts, get_community resolves one community by id or label, and blast_radius adds a reverse-import impact surface for module and file changes.

Resource Surface

SwarmVault also exposes read-oriented resources:

  • swarmvault://config
  • swarmvault://graph
  • swarmvault://manifests
  • swarmvault://context-packs
  • swarmvault://tasks
  • swarmvault://memory-tasks
  • swarmvault://sessions
  • swarmvault://sessions/{path}
  • swarmvault://pages/{path}

Client Setup Pattern

The basic pattern is simple:

  1. Open a terminal in the vault root
  2. Configure your MCP-aware client to launch swarmvault mcp
  3. Let the client call tools and read resources against that workspace

Because the server uses the current working directory as the vault root, you do not need a separate MCP config block inside swarmvault.config.json for the current release.