Snail.MCP.CodeContext¶
An MCP server that indexes a C# codebase with Roslyn and answers an agent with that codebase's own idioms, so generated code reads like the code around it rather than like generic C#.
Principles¶
- Whole declarations, never text chunks. The index holds methods, constructors, records and interfaces as Roslyn sees them, together with the documentation comment written for them.
- The natural language is what gets embedded. A unit's card — its summary, its names, its dependencies — carries the vector. The code is returned, never embedded: the model has a 510-piece window and a method body would arrive as noise.
- Nothing is indexed until asked.
index_codebasebuilds the index; every other tool answers from it and never opens a workspace. - A root can be a whole folder of repositories. Point it at the folder your team keeps its solutions in and every one of them is indexed together, searched as a single corporate codebase.
- An empty answer explains itself. "Nothing is indexed" and "nothing matched" are different facts, and only the second one says anything about the codebase.
Why it is shaped this way — what the centre of the system is, where the line with long-term memory runs, and what this server will not do — is in docs/architecture.md.
Tools¶
| Tool | Answers |
|---|---|
index_codebase |
Builds or refreshes the index as a job: answers the pass's report within wait, or the job still running to read; a subscribed client is told when it ends, and a pass that stopped ends its job failed. |
search_code_patterns |
Finds declarations by concept — "cache a validated config and log the failure". |
get_di_conventions |
How a contract is registered, which module owns it, what lifetimes are normal here. |
get_dto_format |
The written contract style, with real declarations that follow it. |
get_guidelines |
The rules this codebase is written by, as written: all of them, or the ones a topic is about, each with the build check that holds it. |
Every answer is the envelope of every Snail server, JSON with an ok flag: {"ok":true,"data":…} on success,
{"ok":false,"error":…,"hint":…,"type":…} flagged isError when it failed — refused before it ran, or a pass that
started and stopped, whose work up to then did happen. The data is what the
tools always answered — the page of search_code_patterns, the registrations of get_di_conventions, the contract
style of get_dto_format, the report of a pass — with its notes inside it; get_guidelines answers the rules as
data.guidelines. The kinds of failure are nothingToIndex (no path and no configured root, or a path that is not
there), indexFailed (a pass that stopped, its job ended failed, the report as data.result), arguments and
internal.
{"ok":true,"data":{"found":[…],"total":1,"truncated":false,"notes":["Answered from '/repos' (12 projects), indexed 2026-11-08, 0 days old."]}}
{"ok":true,"data":{"guidelines":"> These rules were read from '/repos/.snail/guidelines.md'.\n\n# Guidelines\n…"}}
{"ok":false,"error":"index_codebase: No codebase to index: pass a path, or configure Roots in the server's settings.","hint":"Pass path — a .slnx, .sln, .csproj or a folder holding them — or set Roots in the settings (SNAIL_MCP_CODECONTEXT_ROOTS__0) and call index_codebase again.","type":"nothingToIndex"}
The notes of every answer open with where it came from — which codebase, how many projects, when that reading was taken — and the guidelines name the file the rules were read from. The lookup chain has more than one link, so an answer that did not name its source could not be told from one that read something else.
Resource codebase://architecture-guidelines returns the same text as get_guidelines, as Markdown rather than in the envelope. It is a tool as
well as a resource on purpose: most clients surface a resource only when a person mentions it by hand, so
rules offered only as a resource never reach the agent that is writing the code.
Guidelines are written, not counted¶
get_guidelines, get_dto_format and the resource read .snail/guidelines.md at the codebase root, falling back to
GuidelinesPath. Frequency is deliberately not used as a standard: on any codebase with history the
legacy way outnumbers the agreed one. The index supplies the examples; the prose stays authored.
There is deliberately no tool that writes guidelines. The chain reads .snail/guidelines.md at the first
configured root before it reads GuidelinesPath, so anything writing a file at that root would take the
authority away from the configured one without saying so — and a draft of counts would be answering in
place of the rules. A measurement may not overrule a decision, and the surest way to keep that true is
that nothing here writes into the chain at all.
Refactoring a codebase into another one's style¶
This server is the reference, not the enforcer. It answers what the target should look like; it never sees the code being changed, never reports a violation, and never edits anything. Wired for that job:
- Index the codebase whose style you want, not the one you are rewriting. A root is one index: point it at two or three exemplary repositories, and never at the project under refactoring — its own style would come back as the convention.
.snail/guidelines.mdcarries the rules. Naming, comments and layout are decisions, not measurements: they exist nowhere in the code, sosearch_code_patternscannot answer them and will return plausible declarations at a low score instead of nothing. Any answer whose hits all score below the confident range says so, and points atget_guidelines.search_code_patterns,get_di_conventionsandget_dto_formatsupply the shapes — how a service is registered here, how a result type is written, how a contract is declared.- Mechanical rules — indentation,
var, member order, missing documentation — belong in.editorconfigand analyzers, which enforce them on every build and cost nothing to run. - The transformation itself belongs to a tool that can rename and move safely across a compiled solution.
What a root may be¶
index_codebase accepts a .sln, .slnx or .csproj, and equally a folder. Given a folder it
walks it, indexes every solution found anywhere beneath it under one root key, and searches them as one
codebase. Loose .csproj files are used only where a folder holds no solution at all; any that belong
to no discovered solution are reported in the answer's notes rather than skipped silently. obj, bin,
.git, .vs, node_modules and anything in Excludes are never walked into.
A root is keyed by the path you point at, so pointing at a folder and pointing at one solution inside it are two different roots.
Requirements¶
The .NET SDK must be installed: the server loads MSBuild from it through MSBuildLocator, so it is
deliberately not self-contained. Package restore must have run for the codebase being indexed —
without it symbols do not bind, and the server refuses to store dependencies and tags it could not read.
Configuration¶
Flat keys from the settings file, ~/.config/s3l-mcp-codecontext/config.json, or SNAIL_MCP_CODECONTEXT_*
environment variables over it (ROOTS__0 is the first of Roots). The file is found by the one chain of every Snail
server (Snail.Sdk's ServerSettings): a file named in SNAIL_MCP_CODECONTEXT_CONFIG is the only one read, and when it
is missing no file is; otherwise the first that exists of ./.s3l-mcp-codecontext.json, ./s3l-mcp-codecontext.json,
~/.config/s3l-mcp-codecontext/config.json, ~/.s3l-mcp-codecontext.json. A machine's settings — and any secret above
all — belong in that file (chmod 600), never in a launchd job or a client's registration, which travel wherever they
are copied.
{
"Directory": "~/.s3l-mcp-codecontext",
"Roots": ["/path/to/company-repositories"],
"GuidelinesPath": "",
"EmbeddingEnabled": true,
"Excludes": [],
"IdleTimeoutMinutes": 60
}
| Setting | Means |
|---|---|
Directory |
Where the index database and the downloaded model live. |
Roots |
Codebases to index; the first is what index_codebase takes with no path. A root may be a folder holding many solutions. |
GuidelinesPath |
Guidelines used for roots that keep none of their own. |
EmbeddingEnabled |
Off stores no vectors and leaves search matching text. |
Excludes |
Extra folder names to skip, added to .git, .vs, node_modules, Migrations. |
IdleTimeoutMinutes |
Over stdio, minutes without a message from the client before the server stops — never while a pass runs; 60 by default, 0 never. The HTTP server is never stopped for being quiet. |
Transport |
Stdio (the default) or Http: one server for every session — see below. |
Url |
Where the HTTP server listens, http://127.0.0.1:9231 by default; only a loopback address is accepted, and a start inside a container is refused. |
Port |
A port alone also means Http, on that port of the default address. |
The embedding model (multilingual-e5-small, int8, ~118 MB) is downloaded into {Directory}/models on
first use. A machine that cannot download it still indexes: the units are stored without vectors and
search says it is matching text.
Running it¶
{
"mcpServers": {
"codecontext": {
"command": "dotnet",
"args": ["/path/to/src/bin/Debug/net10.0/Snail.MCP.CodeContext.dll"]
}
}
}
Do not use dotnet run: it writes build output to standard output, which belongs to the protocol.
One server for every session¶
Over stdio each session starts its own server, with Roslyn and the model, ~83 MB each. The roots come from the
configuration, not from a session, so one server can answer them all: Transport Http, kept running by launchd on
macOS. Publishing with -p:SnailMcpInstall=true writes the job, with this machine's paths, to
~/.s3l-mcp/Snail.MCP.CodeContext/s3l.mcp.codecontext.plist (from deploy/) and restarts it when it is
loaded. The settings go into ~/.config/s3l-mcp-codecontext/config.json; loading the job is done once:
cp ~/.s3l-mcp/Snail.MCP.CodeContext/s3l.mcp.codecontext.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/s3l.mcp.codecontext.plist
claude mcp add -s user --transport http codecontext http://127.0.0.1:9231/mcp
The endpoint has no key: it listens on loopback only — a Url beyond loopback, ListensOnEveryInterface or a start
inside a container is refused at start, naming the setting (Snail.Sdk's McpReach.LoopbackOnly) — and refuses any
request carrying an Origin, which every browser page sends and no agent client does. GET /healthz answers 200 once the server is up.
A session opened at /mcp?tool=<name>&tool=… — an address a platform writes when it opens the server for a role — is
given those tools alone: the others are left out of its list and a call to one of them is refused with type
notGranted. An address that names no tool is given all of them.