Skip to main content
Glama
Paparats: Local Semantic Code Search

Paparats: Local Semantic Code Search

Paparats MCP: self-hosted semantic code search for AI coding agents

npm version License: MIT PulseMCP MCP Badge Glama

Paparats MCP is an open-source, self-hosted MCP server that gives Claude Code, Cursor, Codex, GitHub Copilot and any other MCP client semantic code search across many repositories: by meaning, with who calls what, and what a change will touch. It runs on your machine or your server in Docker, with local embedding models by default, so your code stays with you.

Your agent asks "where do we retry failed payments?" and gets the few functions that do it, with file and line, instead of grepping and reading whole files. Before changing one, it asks what depends on it and gets the callers two steps out (up to three) and the tests that reach them.

With Paparats the agent answered 25% faster and read 23% fewer new tokens. Claude Code, the same question about this repository, without Paparats (left) and with it (right), at 5× speed. Averages over three runs each: 99 s against 74 s, 23% fewer new input tokens and 21% fewer output tokens. This repository is small, about 300 files. On large legacy codebases spread over many repositories, where I use Paparats every day, the difference is much bigger.

Quick start

You need Docker with Compose v2. Two files and one command:

mkdir paparats && cd paparats
curl -fsSLO https://raw.githubusercontent.com/IBazylchuk/paparats-mcp/main/examples/docker-compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/IBazylchuk/paparats-mcp/main/examples/docker-compose/projects.yml
docker compose up -d
claude mcp add --scope user --transport http paparats http://localhost:9876/mcp

projects.yml indexes this repository, so there is something to ask about right away (docker compose logs -f paparats-indexer shows the progress). Put your own GitHub repositories there; the file is reloaded on save, and private ones need GITHUB_TOKEN in a .env next to it. Any other MCP client takes the same URL, http://localhost:9876/mcp (setup for each).

Then ask your agent:

Search the codebase for where we handle failed payments, show me what calls it, and what would be affected if I changed it.

Without local models: download docker-compose.voyage.yml instead, put VOYAGE_API_KEY=... into .env and run docker compose -f docker-compose.voyage.yml up -d. Code is then sent to Voyage AI to be embedded, and the 2.3 GB of models are not needed.

With the CLI

Easier for folders on your machine (it mounts them for you) and on macOS, where the models run natively with Metal; in Docker on a Mac they only get the CPU. Needs Node.js 24+.

npm install -g @paparats/cli
brew install llama.cpp mostlygeek/llama-swap/llama-swap   # macOS only: local models with Metal

paparats install            # starts the stack, connects Claude Code and Cursor
paparats add ~/code/my-app  # or `.`, or a GitHub repo: paparats add acme/widgets
paparats list               # wait until the project shows as indexed

Nothing local: Open in GitHub Codespaces runs the whole stack in your own Codespace, on this repository.

All install options, hardware and upgrading: docs/install.md.

Related MCP server: Serena

What your agent gets

  • search_code: finds code by what it does, across every repository in a group. The file path is embedded with each chunk, and a query naming a class or function ranks its definition higher.

  • find_usages and change_impact: a call graph by method, built from the syntax tree. change_impact lists what depends on the code you are about to change, marks the uncertain links and lists the tests apart.

  • module_map: the modules of a codebase, worked out from who calls whom, with their main files and how they depend on each other. Also a page you can walk: http://localhost:9876/ui/map.

  • Git history per chunk: who changed it, when, and the tickets named in the commit messages.

  • Architectural memory: components, decisions and lessons the agent records as it works and reads before changes that cross components. More.

  • Documentation search and a glossary: your markdown, searched by meaning and keywords (opt-in), and a shared list of team terms. More.

The code map at /ui/map: this repository folder by folder, with arrows for who calls whom.

Tools come on three endpoints: coding (/mcp) for the agent you write code with, support (/support/mcp), read-only, for support people and bots, and knowledge (/knowledge/mcp), documentation only, behind a token, for a service outside your network. Every tool: docs/tools.md.

FAQ

What is Paparats MCP?

An open-source (MIT) MCP server for semantic code search over many repositories. It runs on your machine or server with Qdrant and local llama.cpp embeddings, and adds a call graph, git history per chunk and agent-maintained architectural memory on top of the search.

How do I add semantic code search to Claude Code?

Start the stack from the quick start and add it to Claude Code with one command (paparats install does this step for you):

claude mcp add --scope user --transport http paparats http://localhost:9876/mcp

The Claude Code plugin does the same and adds a skill that tells Claude when to search by meaning and when to grep.

Which MCP clients work?

Any client with Streamable HTTP, at http://localhost:9876/mcp. docs/clients.md has the setup for Claude Code, Cursor, Codex, GitHub Copilot in VS Code, Windsurf, Antigravity, Gemini CLI, Grok Build, Cline and clients that only start a process (stdio).

Does my code leave my machine?

Not by default. Indexing, the embedding models (bge-code-v1 for code, Qwen3-Embedding-0.6B for prose, served by llama.cpp) and the vector store (Qdrant) all run locally in Docker. Cloud embeddings (Voyage, OpenAI), a remote Qdrant and trace export are opt-in. See PRIVACY.md.

When should I use it, and when not?

Use it when grep-and-read loops eat your agent's context on a large codebase or many repositories, or when several people and agents should share one index. Skip it for one small repository, or for precise refactoring: that is a job for a language-server tool such as Serena, which works well alongside Paparats.

Can it search several repositories at once?

Yes. Projects in one group share a Qdrant collection, so one query covers backend, frontend and infrastructure together. The call graph is built per project; calls from one repository into another are not linked yet.

How fresh is the index after I change code?

Within about 10 minutes. The indexer checks every repository every 10 minutes and indexes only the files that changed, call graph included; a full pass runs every few hours. POST /trigger on the indexer updates it at once, for example from CI. There is no file watcher, so an edit is not searchable within seconds.

Which branch is indexed?

A GitHub repository (url: in projects.yml) is indexed from its default branch. A local folder (path:) is reindexed when its files change, so after a branch switch the index follows the checkout at the next change check (every 10 minutes by default). Index main and let the agent read its own branch: with several worktrees open, indexing each copy is a full index per copy, and mixing branches in one index would answer from code that is not on the agent's branch. The index tells the agent where to look; the files on its branch give the current code. A team shares one server that reindexes main.

Does it replace grep?

No. grep is fast and exact when the agent knows the word: an error message, a field name, every use of a name before a rename. When it does not, it has to guess words and finds nothing where the code is named differently from what it looks for. Search by meaning finds that code; each result lists what the chunk defines and uses, with a chunk id for find_usages and change_impact. Then the agent reads the exact places with grep and plain file reads.

Which languages are supported?

Syntax-based chunking and the call graph cover 11 languages: TypeScript (with TSX), JavaScript, Python, Go, Rust, Java, Ruby, C, C++, C# and Terraform/HCL. Other files are cut into runs of lines of a fixed size and have no call graph.

What hardware does it need?

Docker with Compose v2; the paparats CLI also needs Node.js 24+ (a plain docker compose up of the examples does not). Local models take about 2.3 GB of disk, and the embed container 2–6 GB of RAM. CPU only works; on macOS the native build with Metal is much faster. With a cloud provider there are no local models at all.

Is there a hosted version or a public demo?

No, Paparats is self-hosted only. To try it without installing anything locally, open the repository in GitHub Codespaces.

How is Paparats different from Graphify, codegraph, GitNexus or Serena?

Graphify, codegraph, GitNexus and codebase-memory-mcp build a code graph from the syntax tree and let the agent walk it; they are lighter to install. Graphify and codegraph have no search by meaning, and GitNexus has it only with embeddings turned on; codebase-memory-mcp bundles an embedding model. Across repositories, codebase-memory-mcp links them in one local store, Graphify and GitNexus do it in Graphify Cloud and GitNexus Enterprise, and codegraph queries one project per call. Paparats searches by meaning with local models across many repositories in one query, adds git history and tickets per result, and runs as one server that a whole team and its agents share, with a read-only support endpoint and a docs-only one. Serena drives language servers for precise lookup and editing; Paparats has no editing tools, and the two work well together. All of them, claude-context and Sourcegraph side by side: comparison with alternatives.

Documentation

Page

What is in it

Install

paparats install and its options, plain docker compose, Codespaces, support mode, hardware, v1 migration

Clients

Setup for every MCP client, the note that tells an agent when to use it

Tools

Every tool on each endpoint, workflow prompts, typical flows

Configuration

projects.yml, .paparats.yml, groups, freshness, CLI, environment variables

How it works

Indexing, search and ranking, the call graph, the module map

Architectural memory

Components, decisions, lessons, the glossary

Documentation search

Docs indexing, audience labels, the knowledge endpoint

Embedding models

Local and cloud models, how they were chosen

Monitoring

Prometheus, OpenTelemetry, the /ui console, token-savings estimates

Comparison with alternatives

Graphify, codegraph, GitNexus, codebase-memory-mcp, claude-context, Serena, ast-grep, Sourcegraph side by side

Benchmarking, Chunking, Replacing models, Releasing

For contributors

Contributing

Issues and pull requests are welcome: more languages (PHP, Elixir, Scala, Kotlin, Swift), more embedding providers, faster indexing, new agent use cases. Every pull request carries a changeset; the release process is in docs/releasing.md. Changes to search quality come with a yarn bench compare against main.

The name

Paparats-kvetka, the fern flower, blooms in Slavic folklore on Kupala Night and lets whoever finds it see hidden things. Paparats helps your agent see the right code in a sea of repositories.

MIT license.

Available Tools

18 tools
arch_contextArchitecture ContextA
Read-only

Retrieve architectural memory relevant to a question or set of touched files. Returns three card kinds, each with an updated-at age stamp:

  • Components: what parts the system is made of.

  • Decisions: why they were built that way.

  • Lessons: rules that survived previous mistakes — each rule comes with why (incident context) and when (when to apply) continuation bullets. Superseded and deprecated cards are hidden by default. Cards older than 90 days are prefixed with ⚠ stale — verify them against the current code before acting. Call this BEFORE any non-trivial change. Returns an init hint when the arch layer is empty.

Each kind has its own independent top-N budget — a verbose decision bucket can't starve components. Pass limits: { component, decision, lesson } to override the per-kind cap (default 5 each, max 50; 0 suppresses the kind). When you pass project, cards whose payload matches that project also get a small additive rank boost (~one calibrated tier) so short global cards don't drown out longer project-scoped ones on raw cosine — globals stay visible but no longer dominate. When you suspect ranking issues, prefer arch_list for ground-truth enumeration.

Inputs: question (required), group, limits, project, +1 more.

arch_deleteDelete Architecture CardsA
Idempotent

Hard-delete one or more arch cards by id. No undo, no audit trail — the cards are gone from Qdrant. Use for: cleaning up obsolete cards left over from a refactor, dropping cards for a removed feature, migrating away from old payload schemas. Idempotent: ids that no longer exist are reported in notFound but do not fail the call. Always re-fetch ids via arch_context immediately before calling — ids from earlier in the conversation may point to cards that have since been re-upserted (a re-upsert allocates a fresh UUID), so deleting by a stale id will silently miss the intended card and could wipe a now-current one if the id was reassigned. Prefer supersedes on arch_record_decision when you have a replacement decision; use arch_delete only when there is no replacement.

Inputs: ids (required), group (required).

arch_listList Architecture CardsA
Read-only

Enumerate arch cards in a group — no vector search, no ranking, no similarity threshold. Use this when you need every card (audit, dedupe, migration) rather than the top-N most similar to a query. arch_context is for relevance-ranked retrieval; arch_list is for ground truth.

Optional filters:

  • project: components must match this project (hard filter); decisions/lessons match this project OR have no project field (soft filter — group-wide guidance still surfaces).

  • kinds: subset of ['component', 'decision', 'lesson'].

  • include_history: include superseded/deprecated cards (default false).

  • limit (default 50, max 200), offset: pagination — pass next_offset from the previous response to resume.

Returns each card with id, kind, project (or 'global'), status, and a short label (name/title/rule). Use the ids with arch_delete or as input to follow-up arch_record_* calls (e.g. supersedes on arch_record_decision).

Inputs: group (required), kinds, limit, offset, +2 more.

arch_record_componentRecord ComponentA
Idempotent

Record (or update by name — idempotent) an architectural component. Use when you discover a logical unit not already in arch_context, or when an existing component's boundary changes. The summary field is structured markdown with four sections (Does / Owns / Does not / Touched when); anchors are stable exported symbol names that survive a refactor. Returns status created or updated.

Inputs: name (required), group (required), project (required), summary (required), +3 more.

arch_record_decisionRecord DecisionA

Record an architectural decision. Use when you pick a library, pattern, or boundary that wasn't obvious. The server runs a similarity gate against existing decisions in the group; possible outcomes:

  • created: a new decision was written.

  • duplicate: a nearly identical decision already exists — nothing is written. Ask the user why arch_context did not surface it earlier.

  • similar: a related decision exists — nothing is written. To explicitly replace it, re-call with supersedes set to its id; otherwise sharpen the wording. Passing supersedes bypasses the gate and marks the named prior decision as superseded.

Inputs: group (required), title (required), context (required), decision (required), +5 more.

arch_record_lessonRecord LessonA
Idempotent

Record a lesson — a rule the agent should follow next time. Use when the user corrects a non-obvious mistake of yours, OR when you accept an unusual approach that would surprise a future reader. Skip typos, parser errors, and facts trivially visible in code.

Belongs here (arch) vs. agent-side memory (auto-memory / CLAUDE.md / AGENTS.md):

  • arch (this tool) — rules about the code: contracts, boundaries, patterns, API shape, type invariants, framework gotchas, schema/migration constraints, security rules tied to the codebase. Examples: "GraphQL admin mutations require a non-null ID and a corresponding picker query", "Always preserve createdAt on re-upsert", "Run integration tests against a real database, not mocks".

  • agent-side memory (not here) — rules about the user's workflow or how to collaborate with them: preferred commit style, branch naming, when to ask vs act, formatting preferences. Those live in auto-memory or a CLAUDE.md / AGENTS.md file — not in arch.

  • Heuristic: if a new engineer joining the codebase would need it → write it here. If only this specific user needs it → it's agent-side memory.

Three fields, each markdown:

  • rule: one imperative sentence (the rule).

  • why: 1-3 sentences with the incident — quote the user verbatim when possible.

  • when: one sentence describing the situation in which the rule applies. The server runs a similarity gate; possible outcomes:

  • created: a new lesson was written.

  • updated: a near-duplicate already existed — its updatedAt was bumped (confirmation signal). Refine the existing card if your wording was better.

  • similar: a related lesson exists — nothing is written. Decide whether to refine the existing or write a clearly distinct one.

Inputs: why (required), rule (required), when (required), group (required), +4 more.

arch_suggest_componentsSuggest ComponentsA
Read-only

Suggest candidate components to record. Reads the symbol-graph in-degree (how often a chunk is called from the rest of the indexed code) and surfaces the most-called files that are not yet covered by an existing component card. Ranked by in-degree.

Use this when initialising the arch layer for a group (instead of guessing where the boundaries are) or after a large refactor to spot newly important modules. The tool only reads — it does not write component cards. Read each suggestion, decide whether it represents a meaningful architectural boundary (some high-degree files are utilities, not components), and call arch_record_component for the ones that do.

Optional project restricts suggestions to one project in the group. Optional limit (default 10, max 50) caps how many uncovered files to return.

Inputs: group (required), limit, project.

delete_projectDelete ProjectA
Idempotent

Delete all indexed data for a specific project: chunks from Qdrant, metadata from SQLite, and query cache. The project will be re-indexed on the next indexer cycle if configured. Use when a project's index is corrupted or stale.

Inputs: group (required), project (required).

find_usagesFind UsagesA
Read-only

Find symbol relationships: what calls this code, and what this code calls. Supports incoming (callers), outgoing (dependencies), or both directions. Use after search_code or get_chunk when the user asks 'where is this used?', 'what calls this?', or 'what does this depend on?'. Pass chunk_id from search results.

Inputs: chunk_id (required), limit, direction, include_hubs, +1 more.

get_chunkGet ChunkA
Read-only

Get a code chunk by ID with optional surrounding context. Returns code with symbol definitions and usage info. Use to expand on search results.

Inputs: chunk_id (required), radius_lines.

health_checkHealth CheckA
Read-only

Check indexing status: number of indexed chunks per group.

Use to verify projects are indexed before searching or debugging empty results.

Inputs: no named parameters.

list_projectsList ProjectsA
Read-only

List all indexed projects with metadata: chunk count and languages per project, grouped by collection. Use when the user asks 'what projects are indexed?', 'which repos are available?', or 'show me all projects'. Optionally filter by group name.

Inputs: group.

search_codeSearch CodeA
Read-only

REQUIRED — call this FIRST for ANY code question.

Semantic code search across all indexed projects. Returns relevant code chunks ranked by confidence score with symbol definitions and usages.

Triggers (call this when the user asks about): code location, implementation, "how X works", "how many X", "what versions of X", "count X", "list X", patterns, flows, error handling, auth, API usage, or ANY reference to project code.

WHY: Returns only relevant chunks (50-90% fewer tokens vs full files). Searches by meaning, not just keywords.

WORKFLOW: Search first → evaluate scores → get_chunk for details → find_usages for dependencies.

Project names are directory basenames, not org/repo format. Example: "billing" not "org/billing".

Inputs: query (required), group, limit, project.

search_docsSearch DocumentationA
Read-only

Hybrid (dense semantic + BM25 keyword) search over indexed markdown documentation, fused with RRF. Returns EXCERPTS, not whole documents: each hit is the best-matching passage plus its neighbouring sections, carrying the document title, heading breadcrumb, project, file, and source link when available. When a hit covers only part of its document an Excerpt: line says which sections you got and how many exist — read the named file directly when you need the rest, because the passage may not be the document's full answer. The top hit is usually right but not always; scan the alternatives before concluding. Use for questions answered by prose docs (runbooks, RFCs, onboarding, business docs), not code. For code use search_code. Optional audience restricts results to visibility labels (e.g. ["internal"], ["client","public"]); omit to search every audience the endpoint is allowed to see. Some deployments enforce an audience ceiling — there, audience can only narrow within it, never widen past it. Results are filtered by a semantic-similarity floor, so a question the corpus does not cover returns nothing rather than the nearest unrelated page; treat an empty result as "not documented". Two floors apply: min_score (default 0.45) for long-form prose, and min_score_code (default 0.6) for markdown that ships inside code repositories (README, CLAUDE.md, design notes) — those are written as overviews and score deceptively well against questions they do not answer, so they are held to a stricter bar. A Last updated ... ago line marks a document untouched for over a year: docs checked in beside code go stale quietly, so prefer a recent source when they disagree, and verify against the code before relying on it. Absence of that line means recent OR unknown age, not verified-current. The reported score is a fusion rank, not a similarity — use it to order hits, not to judge how good a match is.

Inputs: query (required), group, limit, project, +3 more.

term_deleteDelete Glossary TermA
Idempotent

Hard-delete a glossary term by id. No undo. Use to remove obsolete or wrong terms.

Inputs: id (required), group (required).

term_listList Glossary TermsB
Read-only

List recorded glossary terms in a group (optionally scoped to a project). Use to audit coverage or review what terminology has been captured.

Inputs: group, limit, project.

term_recordRecord Glossary TermA
Idempotent

Record a glossary term (canonical name, definition, aliases, optional project scope). Goes through a duplicate/similar gate like arch_record_decision: if a near-identical term already exists it is returned instead of writing a duplicate — reconcile by updating that term. Authored by the agent as it learns domain vocabulary, or in bulk via the extract-terminology skill.

Inputs: term (required), group (required), definition (required), aliases, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 18 tools

    Disambiguation4/5

    The three tool families (code search, glossary, arch memory) are clearly separated, and the pairings that could collide — search_code vs search_docs, get_chunk vs find_usages, arch_context vs arch_list, term_search vs term_list — are explicitly distinguished in their descriptions (ranked retrieval vs ground-truth enumeration, chunks vs prose, symbol graph vs glossary). The only mild residual overlap is term_search vs search_docs for domain questions, but the guidance ('glossary first for acronyms') resolves it. An agent should reliably pick the right tool.

    Naming Consistency3/5

    All names are snake_case, but the ordering convention flips between verb_noun (search_code, get_chunk, find_usages, list_projects, delete_project, health_check) and noun_verb (term_search, term_record, arch_context, arch_list, arch_delete, arch_record_component). The prefix-grouping is readable and even praiseworthy for discoverability, yet inconsistent with the search/code family. Readable overall, but not a single predictable pattern.

    Tool Count4/5

    18 tools spans three genuinely distinct sub-domains (semantic code search, glossary, architectural memory), so the count is roughly proportional rather than padded. Still, it sits at the top of the comfortable range, and the seven arch_* tools plus four term_* tools make the surface heavier than a pure search server would need. Slightly over a lean ideal but each tool maps to a real operation.

    Completeness4/5

    Glossary (record/search/list/delete) and arch memory (record/list/context/delete/suggest) have near-full lifecycles, and code search covers discovery, expansion, and dependency tracing. The notable gap is indexing control — there is no reindex/refresh tool, only delete_project with a note that re-indexing happens on the next cycle — and term updates are only implicit through the duplicate gate. Workarounds exist, so nothing is a dead end.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A fully featured coding agent that uses symbolic operations (enabled by language servers) and works well even in large code bases. Essentially a free to use alternative to Cursor and Windsurf Agents, Cline, Roo Code and others.
      29
      31,250 PyPI
      31,560
      GPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides semantic code search capabilities that run 100% locally using EmbeddingGemma embeddings. Enables finding code by meaning across 15 file extensions and 9+ programming languages without API costs or sending code to the cloud.
      238
      -