librarian-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@librarian-mcp brief me on existing auth code before I add OAuth support"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
librarian-mcp
An MCP server that gives coding agents whole-machine code retrieval. It is a thin stdio client. The retrieval engine is a separate, private service that this repository does not include.
Agent habits it supports:
librarian_briefbefore starting work: what already exists, what to reuse, what is missing.librarian_locatebefore grep: currentfile:linefrom a code index, with a flag when a file changed recently.Two-way feedback:
librarian_tell(supply knowledge the engine lacked or got wrong) andlibrarian_gap(report something it could not answer).
Architecture
coding agent
| MCP over stdio
v
librarian-mcp (this repo, mcp_server.py)
| HTTP + JSON, LIBRARIAN_URL
v
private engine (runs on a local AI fleet)
|
+-- full-text index (FTS) over code, routes, config keys, symbols
+-- embeddings index + catalog of tools and notesThe client holds no retrieval logic. It formats engine responses for the agent, tags each call with a session id, retries connection failures, and keeps a per-caller discussion history.
Related MCP server: reflens
Tools
Tool | Purpose |
| Start-of-task briefing |
| Exact location of a function, route, config key, entry or file |
| Grounded question answering |
| Multi-turn conversation, one thread per caller |
| Dependents and dependencies of a catalog entry |
| Engine and index health |
| Give the engine knowledge |
| Report missing knowledge |
| Lead session registers guidance and exclusions for its workers |
| What this session's callers asked and were served |
Install and register
Requires Python 3.12+.
pip install -e .
claude mcp add -s user librarian -- python /path/to/mcp_server.pyEnvironment:
LIBRARIAN_URL: engine base URL, defaulthttp://127.0.0.1:8000; use any port you run the engine on.LIBRARIAN_PROJECT: optional project tag sent with each call.CLAUDE_CODE_SESSION_ID: used as the session id when present, otherwise a random id per launch.
Pointing it at your own engine
Any HTTP service implementing the following contract works. All bodies are JSON.
Paths are under $LIBRARIAN_URL. Which tools send which tags:
brief,ask,discuss,tell,gap:session,project(only whenLIBRARIAN_PROJECTis set) andcaller(only when set) in the JSON body.locate:sessionand optionalcalleras query parameters; noproject.guide:sessionand optionalcallerin the body (orsessionquery for DELETE).session_log:sessionquery parameter.depends,status: no tags.
Method and path | Request | Response fields read by the client |
| query: |
|
|
|
|
|
|
|
| query: |
|
| none | any JSON; |
|
|
|
|
|
|
|
|
|
| query: |
|
| query: | list, or object with |
Error handling in the client: connection failures retry after 2, 4 and 8 seconds,
then report the engine as unreachable. A read timeout (30 s for GET, 180 s for
POST) is reported as a slow engine and is not retried. An HTTP error status is
reported as "engine answered N" and is not retried. librarian_guide uses a
separate path with a 30 s timeout and no retry; on a 4xx it passes the engine's JSON
body through so rejection reasons reach the agent.
What the engine returns
Example GET /api/library/locate?q=auth+middleware response (synthetic):
{
"source": "index",
"hits": [
{"kind": "function", "name": "require_session", "file": "src/web/auth_middleware.py",
"line": 24, "signature": "(request)", "stale": false},
{"kind": "entry", "name": "auth-middleware", "file": "", "depends_on": "session-store"}
],
"excluded_hits": 0
}The client renders this as:
Locations for 'auth middleware' (source: index):
- [function] require_session -> src/web/auth_middleware.py:24 (request)
- [entry] auth-middleware ->
depends_on: session-storeEval
eval/questions.jsonl holds 22 questions about a fictional web application, across
the skills locate, ask_librarian, brief and depends. Each has
expect.any_of: a case-insensitive substring match against the answer decides
pass or fail. eval/run.py prints per-question results and the score, and exits 1
if the score is below 90%.
python eval/run.py # live engine at LIBRARIAN_URL
python eval/run.py --fixture eval/fixtures/answers.jsonl # offlineWhat CI measures: the offline run answers from hand-authored fixture answers in
eval/fixtures/answers.jsonl that contain the expected substrings. It scores 100%
by construction. The fixture gate proves the grader and runner work; it does not
measure retrieval quality. The 86.4% to 100% history was measured on the original
private question set against the private engine, so it does not apply to the
published questions; see eval/HISTORY.md.
To evaluate your own engine, edit the questions and expect strings to match your
corpus and run the live mode.
Tests
python -m unittest discover testsLicense
MIT. See LICENSE.
Available Tools
10 toolslibrarian_askA
Ask the librarian a question about this PC's systems: what exists, where it
lives, which tool to use, or how something works. Returns a grounded answer
(WHAT / WHERE file:line / TOOLS / NEXT) over the whole-PC corpus (catalog +
tools + machine map + project memory + a live code index). AI sessions should
USE THIS instead of guessing, saying they can't find something, or calling a
premium model just to rediscover local context. If the coordinating session registered guidance (librarian_guide), the answer already accounts for it and shows its version. caller is an optional caller label; leave it empty.
Inputs: query (required), caller. Returns: result
librarian_briefA
START-OF-TASK BRIEF for AI sessions. Call this FIRST when beginning any non-trivial task:
pass the task/goal and the librarian reviews everything that already exists on
this PC and tells you what's relevant, HOW it helps here, what to reuse, and -
honestly - what we DON'T have. Lets you start with most of what you need
instead of hunting. If we have nothing, it says so plainly. If the coordinating session registered guidance (librarian_guide), the answer already accounts for it and shows its version. caller is an optional caller label; leave it empty.
Inputs: task (required), caller. Returns: result
librarian_dependsA
Show what depends on / connects to a catalog entry id (the 'what breaks if
I change X' graph). Use after librarian_locate returns an [entry] to see its
blast radius. Pass the entry id, e.g. 'payments-module'. caller is an optional caller label; leave it empty.
Inputs: entry_id (required), caller. Returns: result
librarian_discussA
DISCUSS with the librarian - a running two-way conversation (it remembers
your prior turns). Use for hashing out a task together: verify your
understanding of the project, ask about paths/tools, and ANSWER the questions
it asks back (its ASK: line). Multiple trips are encouraged - keep going until
both sides agree the picture is complete. Pass reset=true to start a fresh
discussion for a new topic. Threads are per caller: workers do not see the
the coordinator's turns (and reset clears only your own thread). caller is an optional caller label; leave it empty.
Inputs: message (required), reset, caller. Returns: result
librarian_gapA
REPORT a gap - the librarian was missing something you needed (and you
don't have the answer yourself, otherwise use librarian_tell). It goes on the
librarian's gap ledger; every review it re-hunts open gaps and escalates the
still-unanswerable ones to the operator. This is how the librarian learns what to
go back and get. caller is an optional caller label; leave it empty.
Inputs: missing (required), subject (required), caller. Returns: result
librarian_guideA
For the coordinating session, before delegating to workers: register this session's intent so every worker's librarian_brief / librarian_ask / librarian_discuss is steered by it (their answers show the guidance version). Freeform intent about code/projects only - never client names, emails, health, or personal data (the engine rejects PII). Replaced on every call (version bumps); expires after 6h. reset=true clears it first (reset with empty text = just clear). Re-guide per phase.
exclude: path prefixes/substrings, project names, or catalog entry ids the
librarian must NOT serve this session. They are hard-filtered on the engine
before the model sees them, and librarian_locate hits are filtered too. Use
it to stop cross-project bleed, e.g. another app's UI palette/layout leaking
into a worker's build (["apps/other-app", "legacy-service"]). Max 40 items,
200 chars each.
expect: one line (<=500 chars) predicting the effect this guidance should
have on worker output; workers quote the guidance footer in their
report, and the coordinator compares that against this prediction.
Replace-on-write: every call replaces text, exclude AND expect, so a call
without exclude clears the exclusions. caller is an optional caller label; leave it empty.
Inputs: text (required), reset, caller, expect, +1 more. Returns: result
librarian_locateA
Find the EXACT, current location of something on this PC (file:line) - a
function, route, config key, catalog entry, tool, or file. AI sessions should
USE THIS BEFORE grep-scanning the codebase; the answer is generated from a fresh code index,
so line numbers are current and a [changed] flag warns when a file was just
edited. Pass a natural query like 'where is the catalog search code' or
'route that handles checkout'. caller is an optional caller label; leave it empty.
Inputs: query (required), caller. Returns: result
librarian_session_logB
For the coordinating session when judging a worker report: what this session's
workers (and the coordinator) asked the librarian and what they were served - one
line per interaction, newest last, with caller, kind, guidance version,
withheld-hit count (xN, only when exclusions filtered something), query,
cite count and provider. caller is an optional caller label; leave it empty.
Inputs: limit, caller. Returns: result
librarian_statusA
Health of the librarian: catalog availability + index counts (files,
symbols, routes, config keys, entries, changed files) + index age. caller is an optional caller label; leave it empty.
Inputs: caller. Returns: result
librarian_tellA
GIVE the librarian knowledge it doesn't have - something you built or
discovered this session, a decision made, a path/tool it didn't know, or
context you think matters even if the librarian might not. It is ALWAYS
accepted (never rejected as irrelevant) and offered to future sessions.
Use whenever you know something the librarian got wrong or lacked. caller is an optional caller label; leave it empty.
Inputs: info (required), subject (required), caller. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools are distinct (locate, depends, status, tell, gap, guide, session_log), but librarian_brief, librarian_ask, and librarian_discuss all retrieve context from the same corpus and their boundaries are fuzzy—an agent could easily pick the wrong one. Descriptions help (brief=start-of-task, discuss=multi-turn), but the overlap remains real.
All tools share the librarian_ prefix with short, readable suffixes, which makes them easy to scan. However, suffixes mix verbs and nouns (locate, ask, tell vs. status, gap, session_log), so it's not a strict verb_noun pattern.
10 tools is well within a healthy range for a knowledge/retrieval server. A couple (guide, session_log) are coordinator-only and add conceptual surface, but each serves a defined role.
The surface covers retrieval (locate/ask/brief/discuss), dependency graph, health, knowledge contribution (tell), gap reporting, and coordination (guide/session_log) — a full lifecycle. Minor gaps: no explicit list/update/delete of catalog entries, so knowledge can be added but not curated or removed.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
An MCP server that gives your AI access to the source code and docs of all public github repos
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
An MCP memory server. One memory your agents share — across models, devices and apps.
Related MCP Servers
- AlicenseAqualityFmaintenanceAn MCP server that retrieves contextual information from company resources and surfaces it to coding agents as rules, reasoning, skills, and commands.1416 PyPI1MIT
- AlicenseAqualityDmaintenanceAn MCP server that indexes reference repositories and provides tools for AI coding agents to retrieve lossless code context, enabling reasoning over codebases larger than the agent's context window.82Apache 2.0
- AlicenseBqualityDmaintenanceA precision code-retrieval MCP server for coding agents working in large, legacy, and air-gapped codebases. It returns exact file and line range citations from natural-language queries without requiring the agent to perform blind searches.3MIT
- AlicenseAqualityBmaintenanceAn MCP server that indexes a repository locally and provides keyword, semantic, hybrid, and SQL search tools, enabling coding agents to answer questions about the codebase efficiently without reading files one by one.3328 npm31Apache 2.0