swarmvault mcp

Run SwarmVault as a local MCP server over stdio.

Usage

swarmvault mcp

What It Exposes

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
  • cluster_graph
  • get_node
  • get_community
  • get_neighbors
  • get_hyperedges
  • shortest_path
  • god_nodes
  • blast_radius

Query Tool Shape

query_vault accepts:

  • question - required natural-language question
  • save - optional boolean, defaults to true
  • format - optional markdown | report | slides | chart | image

That means MCP-aware clients can request the same saved visual output formats that the CLI supports.

compile_vault accepts:

  • approve - optional boolean, matching swarmvault compile --approve
  • maxTokens - optional integer token budget, matching swarmvault compile --max-tokens <n>

build_context_pack accepts:

  • goal - required handoff or review goal
  • target - optional file path, page id, node id, or graph label
  • budgetTokens - optional token budget
  • format - optional markdown | json | llms printed shape

Task tools mirror swarmvault task; memory task tools mirror the compatibility aliases:

  • start_task creates a task ledger and linked context pack
  • update_task records notes, decisions, changed paths, linked context packs, graph ids, git refs, or status
  • finish_task records an outcome and follow-ups
  • list_tasks, read_task, and resume_task expose saved task history
  • start_memory_task creates a task ledger and linked context pack
  • update_memory_task records notes, decisions, changed paths, linked context packs, graph ids, git refs, or status
  • finish_memory_task records an outcome and follow-ups
  • list_memory_tasks, read_memory_task, and resume_memory_task expose saved task history

Retrieval tools inspect and repair the local state/retrieval/ index:

  • retrieval_status returns the current backend, freshness, manifest, page count, and shard path
  • rebuild_retrieval rebuilds the SQLite FTS shard and manifest
  • doctor_retrieval checks freshness and can repair stale artifacts

doctor_vault runs the broader vault doctor surface. It checks graph artifacts, retrieval, review queues, watch state, migrations, managed sources, page/source/task counts, and can rebuild safe derived retrieval artifacts when repair: true is passed.

Resources

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

Notes

  • The current release supports stdio transport only
  • Run the command from the root of the vault you want to expose
  • Compatible clients can use this surface to search pages, read markdown, inspect session artifacts, query the vault, ingest new input, check health, and run compile or lint without shelling out directly
  • Context-pack tools let compatible clients request bounded evidence bundles from the compiled vault without broad file search
  • Task tools let compatible clients keep a durable handoff ledger without storing full transcripts; memory-task tools remain as compatibility aliases
  • Saved chart and image MCP queries write the same wrapper pages and local assets as direct CLI queries
  • graph_report returns the machine-readable graph trust artifact, graph_stats returns lightweight graph counts, cluster_graph recomputes communities and graph report artifacts from the existing compiled graph, get_community returns members/pages/evidence edges for one community, get_hyperedges exposes multi-node group patterns directly from state/graph.json, build_context_pack writes wiki/context/ and state/context-packs/, task tools write wiki/memory/ and state/memory/tasks/, doctor_vault summarizes whole-vault health, retrieval tools inspect state/retrieval/, and blast_radius traces reverse-import impact for module changes

For a higher-level explanation of the MCP surface, see MCP Server.