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
  • graph_status
  • graph_callers
  • update_graph
  • 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.

graph_status is the read-only graph freshness check, mirroring swarmvault graph status: it reports graph/report presence, tracked repo changes, and whether a code-only refresh or full compile is recommended without writing watch state.

update_graph runs the code-only graph refresh, mirroring swarmvault graph update. It accepts an optional files array to refresh just the named files (the per-file fast path used by agent hooks); concurrent refreshes coalesce through the same lock plus queue under state/watch/.

graph_callers mirrors swarmvault graph callers <symbol>: it lists every caller of a symbol from graph calls edges with exact file:line call-site evidence, scanning only the files the graph identifies as callers, so who-calls and impact-of-change questions resolve without a repo-wide grep.

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, graph_status is the read-only freshness check, update_graph runs the code-only (optionally per-file) graph refresh, 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/, blast_radius traces reverse-import impact for module changes, and graph_callers lists every caller of a symbol with file:line call-site evidence

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