Skip to main content
Glama
librarian-mcp

librarian-mcp

by Peacho97

librarian-mcp

grader self-check

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_brief before starting work: what already exists, what to reuse, what is missing.

  • librarian_locate before grep: current file:line from a code index, with a flag when a file changed recently.

  • Two-way feedback: librarian_tell (supply knowledge the engine lacked or got wrong) and librarian_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 notes

The 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

librarian_brief(task)

Start-of-task briefing

librarian_locate(query)

Exact location of a function, route, config key, entry or file

librarian_ask(query)

Grounded question answering

librarian_discuss(message, reset)

Multi-turn conversation, one thread per caller

librarian_depends(entry_id)

Dependents and dependencies of a catalog entry

librarian_status()

Engine and index health

librarian_tell(subject, info)

Give the engine knowledge

librarian_gap(subject, missing)

Report missing knowledge

librarian_guide(text, exclude, expect, reset)

Lead session registers guidance and exclusions for its workers

librarian_session_log(limit)

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.py

Environment:

  • LIBRARIAN_URL: engine base URL, default http://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 when LIBRARIAN_PROJECT is set) and caller (only when set) in the JSON body.

  • locate: session and optional caller as query parameters; no project.

  • guide: session and optional caller in the body (or session query for DELETE).

  • session_log: session query parameter.

  • depends, status: no tags.

Method and path

Request

Response fields read by the client

GET /api/library/locate

query: q, limit (10), surface (mcp), session, optional caller

hits[] with kind, name, file, line, signature, stale, depends_on (for kind=entry); source; excluded_hits (int); footer (string)

POST /api/library/brief

{task, surface, session, project?, caller?}

brief; or busy, position, eta_s; or error

POST /api/library/ask

{query, surface, session, project?, caller?, history?[{role, content}]}

answer, provider; or busy, position, eta_s; or error

GET /api/library/depends

query: eid

dependents[], depends_on[]

GET /api/library/status

none

any JSON; index.built_at (epoch seconds) is used to compute index age

POST /api/library/tell

{subject, info, source, session, project?, caller?}

stored (string) or error

POST /api/library/gap

{subject, missing, source, session, project?, caller?}

stored (string) or error

POST /api/library/guide

{session, text, exclude[], expect, caller?}

stored (bool), version, expires_at; on rejection reason (or detail)

DELETE /api/library/guide

query: session

cleared (bool)

GET /api/library/interactions

query: session, limit

list, or object with rows / interactions / items; each row may carry t, caller, kind, guidance_version, excluded_hits, query, served[], provider, session

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-store

Eval

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   # offline

What 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 tests

License

MIT. See LICENSE.

Available Tools

10 tools
librarian_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

    A3.8/5.0

    Scored across 10 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      8
      2
      Apache 2.0
    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An 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.
      3
      328 npm
      31
      Apache 2.0