3.8. The index as an MCP server
The corpus index is not reserved to SPEAR’s own sessions. spear-mcp serves
it over the Model Context Protocol, so any MCP client – another assistant, an
editor – searches the same corpora with the same retrieval: dense and lexical
candidates fused by rank, over one corpus or the federation it declares.
$ docker run --rm -i --entrypoint spear-mcp <image> --corpus <name>
The server speaks on stdin and stdout and exits when its input closes. It needs no mounted tree and no model endpoint: the image carries the index and the embedding model a query is embedded with.
3.8.1. Tools
Tool |
What it does |
|---|---|
|
names the indexed corpora, their size, and the corpora each one is searched with |
|
|
A path in a result is relative to the root of the corpus that was asked for, a
federated sub-corpus included (linux/linux/drivers/...). That is how the
client’s own checkout of the same tree names the file, so the client can open
it directly.
--corpus, or SPEAR_MCP_CORPUS, names the corpus a search uses when it
does not say. Without it, a search has to name one unless the image holds a
single indexed corpus.
3.8.2. Reaching an image on another machine
stdio is the only transport, deliberately. The server holds private source,
and a transport that listens on a port would need authentication and
encryption of its own. Over stdio the client starts the server through
whatever already provides both, and ssh does:
$ ssh <host> docker run --rm -i --entrypoint spear-mcp <image> --corpus <name>
Registered as the command of a stdio MCP server, that line is the whole deployment: no port is opened on the host, and who may search is who may log in.
The first search of a server process loads the embedding model and the index, which takes some tens of seconds on a CPU and, for a large corpus, several gigabytes of memory. Later searches of the same process do not pay it again.
3.8.3. Rules and skills for Claude Code
The index is one half of what an image knows about a project; its rules and
skills are the other. spear-claude-export writes the ones that apply to a
corpus as Claude Code project files, on stdout as a tar:
$ ssh <host> docker run --rm --entrypoint spear-claude-export <image> \
--corpus <name> | tar -x -C <project tree>
File |
From |
|---|---|
|
a |
|
a skill whose scope covers the corpus; its description is the skill’s summary |
Inside the container none of this is needed: the image’s claude command
does the export and registers the server before it starts
(Running the reds image, step 6).
A rule scoped to a path is left out, since the path is one of the image and not of the reader’s machine. Running the export again replaces the files it wrote before and touches no other.