Paparats MCP

← try the full stack in your browser, no install (details)

Paparats-kvetka — a magical flower from Slavic folklore that blooms on Kupala Night and grants whoever finds it the power to see hidden things. Likewise, paparats-mcp helps your agent see the right code across a sea of repositories.

🌿 Works with Claude Code · Cursor · Windsurf · Copilot · Codex · Antigravity · any MCP-compatible agent

Give your AI coding assistant deep, real understanding of your entire workspace. Paparats indexes every repo you care about — semantically, with AST-aware chunking and a cross-chunk symbol graph — and exposes it through the Model Context Protocol. Search by meaning, follow who-uses-what through real symbol edges, see who last touched a chunk and which ticket it came from — all without your code ever leaving your machine.

📊 The built-in /ui operator console — ROI, query quality, cross-project usage, per-user activity, indexer health. Screenshot uses synthetic data (?demo=1) — no real queries, users, or project names.

⚡ One install, one config. paparats install → paparats add ~/code/repo → done.
🌳 AST-aware chunking and symbol extraction. Tree-sitter parses every supported file once and feeds both chunking and the cross-chunk symbol graph (calls / called_by / references / referenced_by) — 11 languages including TypeScript, Python, Go, Rust, Java, Ruby, C, C++, C#.
🧠 Architectural memory that the agent maintains itself. A second vector store per group holds components, decisions (ADRs) and lessons learned — your agent writes them as it works and reads them before answering. Bootstrap on day one with the init_arch_memory MCP prompt (the /init of architectural memory). Server-side similarity gate prevents duplicates, supersedes links replace stale decisions, a min_score threshold gates low-confidence reads, every card carries an "updated N ago" stamp, and Prometheus metrics tell you whether your memory is actually being used.
💸 Saves tokens. Returns only the chunks that matter, with token-savings telemetry to prove it (per-query, per-user, per-anchor-project).
🔭 Production-ready observability. Prometheus /metrics, OpenTelemetry traces (Tempo, Jaeger, Honeycomb, Datadog, Grafana Cloud, Elastic APM), local SQLite analytics, and a built-in /ui operator console that visualises ROI, query quality, cross-project usage and indexer health in one screen.
🏠 100% local by default. Qdrant + a local embed server (llama.cpp llama-server + llama-swap) on your machine. No cloud, no API keys, no telemetry leaving the box. Bring your own Qdrant Cloud / embed server URL if you want.

Why Paparats?
Quick Start
How the install works
Install variants
Migrating from a v1 install
Support agent setup
How It Works
Key Features
Use Cases
Architectural memory
Configuration
MCP Tools Reference
Connecting MCP
CLI Commands
Monitoring
Analytics & Observability
Architecture
Embedding Model Setup
Comparison with Alternatives
Token Savings Metrics
Contributing
Links

Why Paparats?

AI coding assistants are smart, but they can only see files you open. They don't know your codebase structure, where the authentication logic lives, or how services connect. Paparats fixes that.

What you get

Semantic code search — ask "where is the rate limiting logic?" and get exact code ranked by meaning, not grep matches
Real-time sync — edit a file, and 2 seconds later it's re-indexed. No manual re-runs
Cross-chunk symbol graph — find_usages walks AST-derived edges (calls, called_by, references, referenced_by) so the agent can trace dependencies without re-grepping
Token savings — return only relevant chunks instead of full files to reduce context size
Multi-project workspaces — search across backend, frontend, infra repos in one query
100% local & private — Qdrant vector database + local llama-server embeddings. Nothing leaves your laptop
AST-aware chunking — code split by AST nodes (functions/classes) via tree-sitter, not arbitrary character counts (TypeScript, JavaScript, TSX, Python, Go, Rust, Java, Ruby, C, C++, C#; regex fallback for Terraform)
Rich metadata — each chunk knows its symbol name (from tree-sitter AST), service, domain context, and tags from directory structure
Git history per chunk — see who last modified a chunk, when, and which tickets (Jira, GitHub) are linked to it
Architectural memory — a living knowledge base of components, decisions (ADRs) and lessons learned, written by the agent as it learns, deduplicated server-side by vector similarity, and consulted on every support query so the agent stays consistent across sessions

Who benefits

Use Case	How Paparats Helps
Solo developers	Quickly navigate unfamiliar codebases, find examples of patterns, reduce context-switching
Multi-repo teams	Cross-project search (backend + frontend + infra), consistent patterns, faster onboarding
AI agents	Foundation for product support bots, QA automation, dev assistants — any agent that needs code context
Legacy modernization	Find all usages of deprecated APIs, identify migration patterns, discover hidden dependencies
Contractors/consultants	Accelerate ramp-up on client codebases, reduce "where is X?" questions

Quick Start

Try it in the browser (no install)

Spin up a full Qdrant + embed server + paparats stack in a Codespace. A small slice of the repo (packages/shared/src) is auto-indexed on first start so you can run

paparats search -g demo 'gitignore filter'

within a few minutes. Codespace forwards port 9876 for MCP — point Cursor/Claude Code at it via the URL VS Code shows in the Ports panel.

Note: Codespaces is for demo only. With CPU embedding the full repo would take 15+ minutes and can hit batch timeouts on large files. For real workloads run locally — or set OPENAI_API_KEY (or VOYAGE_API_KEY) as a Codespaces user secret and indexing drops to a couple of seconds; see the Embedding providers section below.

Run locally

You need Docker and Docker Compose v2. On macOS, also install the embed server natively — running it inside Docker on macOS is significantly slower because the Docker VM cannot use Apple Silicon GPU (Metal) acceleration.

# 1. Install the CLI.
npm install -g @paparats/cli

# 2. macOS only — install the native embed server (Linux uses the Docker embed
#    image by default). Metal-accelerated.
brew install llama.cpp mostlygeek/llama-swap/llama-swap

# 3. One-time bootstrap. Generates ~/.paparats/{docker-compose.yml,projects.yml},
#    starts the stack, downloads the embedding model, wires Cursor/Claude Code MCP.
paparats install

# 4. Add the projects you want indexed. Local paths bind-mount read-only into the
#    indexer; git URLs and owner/repo shorthand get cloned.
paparats add ~/code/my-project
paparats add [email protected]:acme/billing.git
paparats add acme/widgets

# 5. Watch it work.
paparats list

That's it. Your IDE is already wired (~/.cursor/mcp.json, ~/.claude/mcp.json) to http://localhost:9876/mcp. Open Cursor or Claude Code and ask:

"Search this workspace for the auth middleware and show me everything that calls it."

Existing v1 user?

Just run paparats install again. The installer detects the legacy per-project compose, asks once before swapping it for the new global setup, and preserves your indexed data (Qdrant collections, SQLite metadata, embedding cache). Your in-repo .paparats.yml files keep working as per-project overrides.

How the install works

paparats install is the only setup command. It creates a single global home at ~/.paparats/, brings up a Docker stack, and wires your MCP clients. Re-run it any time to reconfigure — it diffs the existing compose and asks before overwriting hand edits.

~/.paparats/
├── docker-compose.yml          generated; hand-editable; install asks before overwriting
├── projects.yml        project list (CLI rewrites it; comments survive your manual edits)
├── install.json                install flags persisted so add/remove can regenerate compose
├── .env                        secrets — Qdrant API key, GitHub token; chmod 600
├── models/                     bge-code-v1 + qwen3-embedding-0.6b GGUF (native embed mode)
└── data/                       Docker volumes (mounted by name from compose)
    ├── qdrant/                 vector index
    ├── sqlite/                 metadata.db, embeddings.db, analytics.db
    └── repos/                  cloned remote projects

Inside the Docker stack:

Service	Image	Port	Role
`paparats-mcp`	`ibaz/paparats-server:latest`	9876	MCP HTTP/SSE endpoints, search, metadata API
`paparats-indexer`	`ibaz/paparats-indexer:latest`	9877	Cron + on-demand indexing, hot-reload of project list
`qdrant`	`qdrant/qdrant:latest`	6333	Vector DB (skipped when you pass `--qdrant-url`)
`embed`	`ibaz/paparats-embed:latest`	11434	Embed server — llama-server + llama-swap, `bge-code-v1` + `qwen3-embedding-0.6b` pre-baked (Linux default; macOS uses native embed server). llama-swap listens on 8080 inside the container

The indexer hot-reloads projects.yml. Edits that change project metadata only (group, language, indexing tweaks) reindex in place. Edits that add or remove local-path projects require a stack restart so Docker picks up the new bind-mount — the CLI does this for you on paparats add and paparats remove.

Install variants

Default (recommended)

paparats install

On macOS prefers the native embed server and dockerized Qdrant. On Linux defaults to Docker for both.

Bring your own Qdrant

paparats install --qdrant-url https://qdrant.example.com
# Asks for an API key after; stored in ~/.paparats/.env as QDRANT_API_KEY.

When --qdrant-url is set the Qdrant container is omitted from the stack entirely.

Bring your own embed server

paparats install --embed-url http://10.0.0.5:11434

Skips both the native and Docker embed server.

The remote endpoint must serve the bge-code-v1 model (and qwen3-embedding-0.6b for the arch-memory layer) over an OpenAI-style /v1/embeddings API. The installer will not touch a remote instance. The simplest way is to run the pre-baked image on that host — no model registration needed, llama-swap loads GGUF by name on first request:
docker run -d -p 11434:8080 ibaz/paparats-embed:latest
Then paparats install --embed-url http://that-host:11434 and Paparats will use it.

Force Docker embed server on macOS

paparats install --embed-mode docker

Slower on Apple Silicon (no Metal GPU), but useful for parity testing or laptops without brew.

Scripted / CI

paparats install --non-interactive --force

Fails on any prompt; --force answers Y to compose-overwrite and migration prompts.

Migrating from a v1 install

When paparats install finds a legacy ~/.paparats/docker-compose.yml (the one from the old per-project flow with no paparats-indexer service), it prints a one-screen migration notice and asks before tearing the legacy stack down.

What survives: Qdrant collections, SQLite metadata, indexer repos, and any .paparats.yml files inside your repos (those still take precedence over projects.yml overrides).

What's deleted: the legacy docker-compose.yml and .env. They are regenerated on the spot under the new schema.

No re-indexing needed — the data volumes are referenced by the same names in the new compose. Add your projects with paparats add and they re-appear in paparats list with their existing chunks.

If your install predates the paparats-indexer.yml → projects.yml rename, the installer migrates the file in place on first run and prints a one-line notice. The indexer also reads the legacy name as a fallback, so nothing breaks if you roll out the indexer before re-running paparats install.

Pass --force to skip the migration prompt in scripts.

Support agent setup

For bots and support teams that consume an existing Paparats server — no Docker, no embed server needed on this side.

# Connect to a running server (default: localhost:9876)
paparats install --mode support

# Connect to a remote server
paparats install --mode support --server http://prod-server:9876

The installer verifies the server is reachable, then wires Cursor MCP (~/.cursor/mcp.json) and Claude Code MCP (~/.claude/mcp.json) to the support endpoint. Tools available on /support/mcp: search_code, get_chunk, find_usages, list_projects, health_check, get_chunk_meta, search_changes, explain_feature, recent_changes, impact_analysis, arch_context, arch_record_component, arch_record_decision, arch_record_lesson (architectural memory — see Key Features), plus the analytics tools described in Observability below.

How It Works

Your projects                   Paparats                       AI assistant
                                                               (Claude Code / Cursor)
  backend/                 ┌──────────────────────┐
    .paparats.yml ────────►│  Indexer              │
  frontend/                │   - chunks code       │          ┌──────────────┐
    .paparats.yml ────────►│   - embeds via llama  │─────────►│ MCP search   │
  infra/                   │   - stores in Qdrant  │          │ tool call    │
    .paparats.yml ────────►│   - watches changes   │          └──────────────┘
                           └──────────────────────┘

Indexing Pipeline

During each indexer cycle (cron-driven, on-demand via paparats add, or triggered by the indexer's chokidar file watcher), every file in scope flows through this pipeline:

 Source file
     │
     ▼
 ┌─────────────────┐
 │ 1. File discovery│  Collect files from indexing.paths, apply
 │    & filtering   │  gitignore + exclude patterns, skip binary
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 2. Content hash  │  SHA-256 of file content → compare with
 │    check         │  existing Qdrant chunks → skip unchanged
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 3. AST parsing   │  tree-sitter parses the file once (WASM)
 │    (single pass) │  → reused for chunking AND symbol extraction
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 4. Chunking      │  AST nodes → chunks at function/class
 │                  │  boundaries. Regex fallback for unsupported
 │                  │  languages (brace/indent/block strategies)
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 5. Symbol        │  AST queries extract module-level defines
 │    extraction    │  (function/class/variable names) and uses
 │                  │  (calls, references) per chunk. 11 languages
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 6. Metadata      │  Service name, bounded_context, tags from
 │    enrichment    │  config + auto-detected directory tags
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 7. Embedding     │  Jina Code Embeddings 1.5B via llama-server
 │                  │  SQLite cache (content-hash key) → skip
 │                  │  already-embedded content
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 8. Qdrant upsert │  Vectors + payload (content, file, lines,
 │                  │  symbols, metadata) → batched upsert
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │ 9. Git history   │  git log per file → diff hunks → map
 │    (post-index)  │  commits to chunks by line overlap →
 │                  │  extract ticket refs → store in SQLite
 └────────┬────────┘
          ▼
 ┌─────────────────┐
 │10. Symbol graph  │  Cross-chunk edges: calls ↔ called_by,
 │    (post-index)  │  references ↔ referenced_by → SQLite
 └─────────────────┘

Step 5's symbol extractor only emits module-level definitions — locals declared inside function bodies, callback args, and hook closures stay out of the graph because they're not addressable from another chunk anyway.

Search Flow

AI assistant queries via MCP → server detects query type (nl2code / code2code / techqa) → expands query (abbreviations, case variants, plurals) → all variants searched in parallel against Qdrant → results merged by max score → only relevant chunks returned with confidence scores and symbol info.

Watching

The indexer container watches the projects mounted into it via chokidar with debouncing (1s default). On change, only the affected file re-enters the pipeline. Unchanged content is never re-embedded thanks to the content-hash cache. The indexer also hot-reloads ~/.paparats/projects.yml itself: metadata-only edits reindex in place; add/remove of local-path projects triggers a stack restart through the CLI.

Key Features

Better Search Quality

Task-specific embeddings — Jina Code Embeddings supports 3 query types (nl2code, code2code, techqa) with different prefixes for better relevance:

"find authentication middleware" → nl2code prefix (natural language → code)
"function validateUser(req, res)" → code2code prefix (code → similar code)
"how does OAuth work in this app?" → techqa prefix (technical questions)

Query expansion — every search generates 2-3 variations server-side:

Abbreviations: auth ↔ authentication, db ↔ database
Case variants: userAuth → user_auth → UserAuth
Plurals: users → user, dependencies → dependency
Filler removal: "how does auth work" → "auth"

All variants searched in parallel, results merged by max score.

Confidence scores — each result includes a percentage score (≥60% high, 40–60% partial, <40% low) to guide AI next steps.

Performance

Embedding cache — SQLite cache with content-hash keys + Float32 vectors. Unchanged code never re-embedded. LRU cleanup at 100k entries.

AST-aware chunking — tree-sitter AST nodes define natural chunk boundaries for 11 languages. Falls back to regex strategies (block-based for Ruby, brace-based for JS/TS, indent-based for Python, fixed-size) for unsupported languages.

Real-time watching — the indexer's chokidar watcher reindexes a project on file changes with debouncing (1s default). For local-path projects bind-mounted into the indexer, edits on your host show up in MCP queries within seconds.

Cross-chunk symbol graph

The post-index pass walks every chunk's defines_symbols / uses_symbols lists and materializes edges into SQLite — calls, called_by, references, referenced_by. find_usages returns those edges grouped by direction so the agent can traverse the graph without re-searching. Because extraction is AST-driven, function locals don't pollute the graph.

Architectural memory (agent-maintained ADRs, components, lessons)

Code search tells the agent what the code does. Architectural memory tells it why — and the agent maintains that knowledge itself, across sessions, without you authoring a single doc.

Three card kinds, structured by design:

Kind	Captures	Fields
Component	A unit with a clear responsibility (service, module, subsystem)	`name`, `summary` with `Does / Owns / Does not / Touched when`
Decision	An architectural choice (ADR-style)	`title`, `context`, `decision`, `alternatives_rejected`, `consequences`
Lesson	A rule learned from an incident, a code review, a bug, or a user correction (Reflexion-style)	`rule`, `why`, `when`

The agent reads them via arch_context before any architectural answer, and writes them via arch_record_component, arch_record_decision, and arch_record_lesson whenever it discovers something new or learns from a correction. Each card carries an updated N ago stamp in the read tool so the agent can spot stale memory and verify against current code.

Server-side similarity gate (cosine over Qwen3-Embedding-0.6B text embeddings, 1024d):

≥ 0.85 is a duplicate — decisions are refused (the agent must reconcile or supersede); lessons bump updatedAt (Reflexion-style "rule confirmed").
0.70 – 0.85 is similar — surfaced to the agent so it can refine the wording or chain a supersede.
< 0.70 is new — accepted as a fresh card.

supersedes links bypass the gate and mark the prior decision as status=superseded so it disappears from default search but remains in history.

Why this matters:

🧠 Cross-session continuity — what the agent learned last week, today's agent still knows.
📝 ADRs without the ceremony — no markdown files to maintain, no review process, no doc drift. The agent writes when it learns.
🔄 Reflexion built in — corrections become lessons; repeated mistakes get caught.
🚦 No memory rot — similarity gate kills duplicates, supersedes link replaces stale decisions, age stamps trigger verification against code.

Lives in a separate Qdrant collection per group (paparats_<group>_arch). Reading (arch_context) is available on both endpoints — coding agents need to know about prior decisions before refactoring. Writing (arch_record_*) is support-only: recording belongs to the architectural-review workflow, not to every line edit.

arch_context accepts a min_score parameter (default 0.45, cosine over Qwen3-Embedding-0.6B). Lower it to broaden recall on a sparse arch memory; raise it to demand only high-confidence cards. The tool also emits an explicit low-confidence hint when the question matched nothing above the threshold, so the agent knows to either rephrase or lower min_score instead of inventing context.

Initialise the arch layer on day one. Two purpose-built MCP workflow prompts make the boring scaffolding work disappear:

init_arch_memory — the /init of architectural memory. Walks the repo, identifies 8-20 components by domain boundary, writes them, and captures any obvious decisions inferable from comments or README. Run it once per group, right after installing.
audit_architecture — sweeps the memory of one group, flags cards older than 90 days, verifies anchors against the live code, and surfaces a punch list of updates / supersedes for your approval.
record_lesson_from_correction — converts a user correction into a structured lesson card (rule / why / when) without overrecording typos.

MCP resources for live introspection:

arch://schema — the full card-schema reference (fields, similarity-gate thresholds, write semantics). Cite it from the agent when explaining the model.
arch://stats/{group} — live counts (total / by kind / by status) and the oldest/newest updatedAt per group. The same numbers are also pushed to Prometheus.

Observability built in. When PAPARATS_METRICS=true, every read/write hits a counter and the cosine score of returned cards lands in a histogram:

paparats_arch_context_calls_total{group} — calls per group
paparats_arch_write_total{kind, status} — writes by card kind and gate outcome
paparats_arch_search_score — histogram of cosine scores in arch_context results (post min_score)
paparats_arch_collection_size{group, kind, status} — gauge updated whenever arch://stats/{group} is read

These let you spot a memory that's not being written to, a similarity gate that's too aggressive, or a sparse group where every query returns low-confidence hits.

Use Cases

For Developers (Coding)

Connect via the coding endpoint (/mcp):

Use Case	How
Navigate unfamiliar code	`search_code "authentication middleware"` → exact locations
Find similar patterns	`search_code "retry with exponential backoff"` → examples
Trace dependencies	`find_usages {chunk_id, direction: "incoming"}` → callers via the graph
Explore context	`get_chunk <chunk_id> --radius_lines 50` → expand around
Manage projects	`list_projects` and `delete_project` for index hygiene

For Support Teams

Connect via the support endpoint (/support/mcp):

Use Case	How
Explain a feature	`explain_feature "rate limiting"` → code locations + changes
Recent changes	`recent_changes "auth" --since 2024-01-01` → timeline with tickets
Trace usages	`find_usages {chunk_id}` → who calls/references this chunk
Change history	`get_chunk_meta <chunk_id>` → authors, dates, linked tickets
Blast radius	`impact_analysis <chunk_id>` → cross-chunk + cross-project impact
Architectural Q&A	`arch_context "why X"` → components / decisions / lessons (with age)
Capture decisions & lessons	`arch_record_decision` / `arch_record_lesson` — agent writes as it learns, server-side dedup

Support chatbot example:

User: "How do I configure rate limiting?"

Bot workflow (via /support/mcp):
1. explain_feature("rate limiting", group="my-app")
   → returns code locations + recent changes + related modules
2. get_chunk_meta(<chunk_id>)
   → returns who last modified it, when, linked tickets
3. Bot synthesizes response in plain language with ticket references

Configuration

Paparats uses two config files. Both are optional — defaults work for the common case.

`~/.paparats/projects.yml` — global project list

Lives outside your repos. Edited by paparats add / paparats remove or by hand via paparats edit projects. Every entry has either path: (local bind-mount) or url: (remote git, cloned by the indexer), never both.

defaults:
  cron: '0 */6 * * *' # global indexer schedule
  group: workspace # default group when an entry doesn't specify one

repos:
  - path: /Users/alice/code/billing # local bind-mount
    group: dev
    language: typescript

  - url: org/widgets # remote git, cloned by the indexer
    group: prod
    language: ruby

  - url: [email protected]:acme/billing.git
    name: billing # override the auto-derived name
    group: prod

The indexer hot-reloads this file. Adding/removing local-path entries causes the CLI to restart the stack so Docker picks up the new bind-mount; metadata-only edits reindex in place.

`.paparats.yml` in your repo — per-project overrides

Drop one at the project root to override anything from the global file.

group: my-app
language: typescript

# Indexing tuning (all optional)
indexing:
  paths: [src, packages] # restrict to these subdirectories
  exclude: [node_modules, dist, '**/*.test.ts']
  exclude_extra: ['**/__fixtures__/**'] # added on top of language defaults
  chunkSize: 1500 # characters per chunk (default: 1200)
  overlap: 100 # chunk overlap (default: 100)
  concurrency: 4 # parallel embedding requests
  batchSize: 8 # embeddings per llama-server call

# Metadata
metadata:
  service: billing
  bounded_context: payments
  tags: [backend, critical]
  directory_tags:
    src/api: [public-api]
    src/internal: [internal]

  # Git history per chunk (Jira / GitHub ticket extraction included)
  git:
    enabled: true
    maxCommitsPerFile: 50
    ticketPatterns:
      - '\b([A-Z]+-\d+)\b' # Jira-style PROJ-123
      - '#(\d+)' # GitHub-style #123

In-repo .paparats.yml always wins over projects.yml. The CLI never overwrites it.

Groups

A group is a Qdrant collection (paparats_<group>). Multiple projects can share a group to enable cross-project search; each project lives as a project: field in the chunk payload. By default group defaults to the project name (one project, one collection). Set the same group: on multiple entries to consolidate them.

Git history per chunk

When metadata.git.enabled: true (default), the indexer maps each chunk to the commits that touched its line range using diff-hunk overlap. Tickets are extracted from commit messages using metadata.git.ticketPatterns (built-in: Jira PROJ-123, GitHub #42, cross-repo org/repo#99). Surfaced through MCP tools get_chunk_meta, search_changes, recent_changes, explain_feature. Non-fatal: non-git projects index normally.

MCP Tools Reference

Paparats serves the Model Context Protocol on two separate endpoints, each with its own tool set and system instructions.

Coding endpoint (`/mcp`)

For developers using Claude Code, Cursor, etc. Focus: search code, read chunks, follow the cross-chunk symbol graph, manage projects.

Tool	Description
`search_code`	Semantic search across indexed projects. Returns chunks with symbol info and confidence scores.
`get_chunk`	Retrieve a chunk by ID with optional surrounding context.
`find_usages`	Walk the symbol graph from a `chunk_id` — `incoming` (callers/references in), `outgoing` (calls/references out), or `both`.
`list_projects`	List indexed projects with chunk counts and detected languages.
`delete_project`	Wipe Qdrant chunks + SQLite metadata for a project (CLI's `paparats remove` calls it).
`health_check`	Indexing status, chunks per group, running jobs.
`arch_context`	Read-only architectural memory. Returns components, decisions, and lessons relevant to the query with `updated N ago` stamps and a `min_score` cutoff.

Support endpoint (`/support/mcp`)

For support teams and bots without direct code access. Focus: feature explanations, change history, cost reporting — all in plain language.

Tool	Description
`search_code`	Same as coding endpoint.
`get_chunk`	Same.
`find_usages`	Same.
`list_projects`	Same.
`health_check`	Same.
`get_chunk_meta`	Git history and ticket references for a chunk — commits, authors, dates. No code.
`search_changes`	Semantic search filtered by last-commit date. Each result shows when it last changed.
`explain_feature`	Comprehensive feature analysis: locations + recent changes for a question.
`recent_changes`	Timeline grouped by date with commits, tickets, affected files. `since` filter.
`impact_analysis`	Cross-chunk impact for a `chunk_id` — symbol graph traversal + cross-project blast radius.
`arch_context`	Read the architectural memory for a group — top-matching components, decisions and lessons, each stamped with "updated N ago" and a cosine score. Accepts a `min_score` parameter (default 0.45) to gate low-confidence hits. Call before any architectural answer. Also available on `/mcp`.
`arch_record_component`	Record a component with `Does / Owns / Does not / Touched when` fields. Idempotent by `name`.
`arch_record_decision`	Record an ADR-style decision (`context / decision / alternatives_rejected / consequences`). Server-side similarity gate refuses duplicates and surfaces near-matches; `supersedes` links replace prior decisions.
`arch_record_lesson`	Record a lesson as `rule / why / when`. Duplicates bump `updatedAt` (Reflexion confirmation) instead of overwriting.
`token_savings_report`	Aggregate token-savings stats (naive baseline vs search-only vs actually consumed).
`top_queries`	Most frequent queries by user/session/project anchor.
`slowest_searches`	Top-N slowest searches with timing + chunk counts.
`cross_project_share`	Off-anchor result share per user — indicator of search noise.
`retry_rate`	Tool-call retry rate per user — indicator of unhelpful results.
`failed_chunks`	AST parse failures, regex fallbacks, zero-chunk files, binary skips.

Typical workflows

Drill-down (coding agent):

1. search_code "authentication middleware"           → relevant chunks with symbols
2. get_chunk <chunk_id> --radius_lines 50            → expand context around a hit
3. find_usages {chunk_id, direction: "incoming"}     → who calls / references this chunk

Single-call (support agent):

1. explain_feature "How does authentication work?"   → locations + recent changes
2. recent_changes "auth" --since 2024-01-01          → timeline with tickets
3. token_savings_report                              → cost report for the last 7 days

Architectural memory (support agent):

1. arch_context "why do we use qwen3-embedding-0.6b for the arch layer?"
                                                     → top components / decisions / lessons,
                                                       each with an "updated N ago" stamp
2. arch_record_decision { title, context, decision, alternatives_rejected, consequences }
                                                     → status=created | duplicate | similar
                                                       (gate refuses duplicates server-side)
3. arch_record_lesson   { rule, why, when }          → status=created | updated (Reflexion bump)

Connecting MCP

paparats install already wires Cursor (~/.cursor/mcp.json) and Claude Code (~/.claude/mcp.json) to http://localhost:9876/mcp. The sections below are for manual setup or for adding the support endpoint alongside the default coding one.

Cursor

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (project):

{
  "mcpServers": {
    "paparats": {
      "type": "http",
      "url": "http://localhost:9876/mcp"
    }
  }
}

For support use case (feature explanations, change history, impact analysis):

{
  "mcpServers": {
    "paparats-support": {
      "type": "http",
      "url": "http://localhost:9876/support/mcp"
    }
  }
}

Restart Cursor after changing config.

Claude Code

# Coding endpoint (default)
claude mcp add --transport http paparats http://localhost:9876/mcp

# Support endpoint (for support bots/agents)
claude mcp add --transport http paparats-support http://localhost:9876/support/mcp

Or add to .mcp.json in project root:

{
  "mcpServers": {
    "paparats": {
      "type": "http",
      "url": "http://localhost:9876/mcp"
    }
  }
}

Verify

paparats status — check stack is up
Coding endpoint (/mcp): search_code, get_chunk, find_usages, list_projects, delete_project, health_check
Support endpoint (/support/mcp): search_code, get_chunk, find_usages, health_check, list_projects, plus the support-specific tools get_chunk_meta, search_changes, explain_feature, recent_changes, impact_analysis, and the analytics tools listed in Observability (token_savings_report, top_queries, slowest_searches, cross_project_share, retry_rate, failed_chunks)
Ask the AI: "Search this workspace for the auth middleware"

CLI Commands

paparats install [flags]                Bootstrap or reconfigure the global stack.
paparats add <path-or-repo> [flags]     Add a project (local path or git URL/shorthand).
paparats list [--json] [--group g]      Show indexed projects with status from the i

Paparats MCP

README

Paparats MCP

Table of Contents

Why Paparats?

What you get

Who benefits

Quick Start

Try it in the browser (no install)

Run locally

Existing v1 user?

How the install works

Install variants

Default (recommended)

Bring your own Qdrant

Bring your own embed server

Force Docker embed server on macOS

Scripted / CI

Migrating from a v1 install

Support agent setup

How It Works

Indexing Pipeline

Search Flow

Watching

Key Features

Better Search Quality

Performance

Cross-chunk symbol graph

Architectural memory (agent-maintained ADRs, components, lessons)

Use Cases

For Developers (Coding)

For Support Teams

Configuration

~/.paparats/projects.yml — global project list

.paparats.yml in your repo — per-project overrides

Groups

Git history per chunk

MCP Tools Reference

Coding endpoint (/mcp)

Support endpoint (/support/mcp)

Typical workflows

Connecting MCP

Cursor

Claude Code

Verify

CLI Commands

Comments (0)

`~/.paparats/projects.yml` — global project list

`.paparats.yml` in your repo — per-project overrides

Coding endpoint (`/mcp`)

Support endpoint (`/support/mcp`)