Hoplite MCP
Another weapon from the MSL Armory
A knowledge graph over markdown documents. Claude Code MCP plugin that organizes your agent's thoughts.
What hoplite is
The corpus is a directory of .md files with structured headers — Obsidian-compatible YAML frontmatter. Hoplite builds an in-memory graph from the corpus during Claude session start and exposes four query tools so agents can discover documents, traverse the graph, refresh after writing, and dump state as SQLite for debugging.
Content reads happen through the agent's built-in Read tool; writes happen through Write and Edit. There is no CRUD surface on hoplite itself.
The corpus of .md files is the only persistent state in the system. Everything else — edges, MinHash signatures, the FTS5 text index, alias and casefold lookup tables — derives at startup and lives in RAM.
Install
From inside Claude Code, with <repo> as the absolute path to your clone (the directory holding .claude-plugin/marketplace.json):
/plugin marketplace add <repo>
/plugin install [email protected]
After first install, fully restart Claude Code. The plugin's MCP server runs under a venv that a SessionStart hook builds in ${CLAUDE_PLUGIN_DATA} — this is Anthropic's recommended pattern for plugins that ship language dependencies. SessionStart fires on session start, not on /plugin install, so the very first install requires one full Claude Code restart for the venv to build before the MCP server can connect. /reload-plugins alone is not enough — the supervisor would keep retrying against an empty venv and time out at 30 s.
After source changes, run /plugin uninstall [email protected] followed by /plugin install [email protected] to refresh the cached SKILL.md and components. /reload-plugins alone respawns the MCP server but keeps stale cached prose.
Prerequisites
python3 on PATH. The MCP server runs under a bootstrapped venv built at SessionStart; the bootstrap itself runs under system python3.
On Windows: install Python 3.x from the Microsoft Store for the simplest path — it registers both python and python3 as working executables on PATH.
Modern Windows ships a python3.exe App Execution Alias at %LOCALAPPDATA%\Microsoft\WindowsApps\python3.exe that looks like Python but is actually a stub that opens the Microsoft Store page when invoked. If you skip the Store install (or installed only from python.org, which ships python but not python3), this stub is what python3 resolves to. The SessionStart hook then silently fails to bootstrap the venv, and the MCP server reports connection timed out after 30000ms with no obvious cause.
To verify your python3 is real, not the stub:
python3 --version # should print "Python 3.x.y", not open the Store
where.exe python3 # the first hit should NOT be under WindowsApps\python3.exe
If the first where.exe hit is the WindowsApps stub, either install Python from the Microsoft Store, or disable the alias under Settings → Apps → Advanced app settings → App execution aliases and symlink python3.exe → python.exe in your python.org install directory.
Linux distributions vary — python3 resolves out of the box on most. If your distribution ships only python, install python-is-python3 or the equivalent.
What you get
Skills
Three agent-facing skills compose with the knowledge graph:
graph-reference — query the graph. Loads the tool reference and edge vocabulary only; use this when you want to search, traverse, reindex, or dump without loading the authoring workflow.taking-notes — author atomic notes under docs/notes/, each capturing the current state of one idea.journaling — author dated, append-only entries under docs/journal/.
The graph-reference skill is a thin wrapper over components/hoplite/mcp-reference.md. The authoring skills (taking-notes, journaling) inject that same reference alongside shape/artifact-structure.md, shape/frontmatter.md, and prose/writing-prose.md — covering structure, frontmatter, query surface, and prose virtues. One canonical source per component; multiple invocation paths.
MCP tools
Four tools register under the plugin:hoplite:graph_mcp server:
