Paparats MCP: Self-Hosted Semantic Code Search

@paparats/server

The MCP server for Paparats MCP — semantic code search over multiple repos with AST-aware chunking, a cross-chunk symbol graph, git-history per chunk, and an agent-maintained architectural memory layer.

Not published to npm. This package is consumed as a library by @paparats/indexer

and shipped as a Docker image: ibaz/paparats-server.

End users install through @paparats/cli.

What this package does

Three jobs in one process:

• Indexer. AST-aware chunking (tree-sitter, 11 languages), per-chunk symbol extraction, single-parse pipeline, llama-server embedding with SQLite cache, batched Qdrant upsert. Post-index passes attach git history, ticket references, and cross-chunk symbol edges (calls / called_by / references / referenced_by).
• Searcher. Task-prefixed embedding (nl2code / code2code / techqa), query expansion for the support tools (abbreviations, case variants, plurals, filler removal), in-memory LRU query cache with per-group invalidation, confidence scoring, token-savings telemetry.
• MCP server. Three endpoints — /mcp (coding), /support/mcp (support) and the opt-in, docs-only /knowledge/mcp (knowledge) — each with its own tool set and system instructions. Streamable HTTP for every client, with legacy SSE routes kept. Plus an agent-maintained architectural memory layer.

Endpoints

http://<host>:9876/health                  – liveness probe

http:// :9876/metrics – Prometheus (PAPARATS_METRICS=true) http:// :9876/ui – operator console http:// :9876/api/analytics/... – analytics REST API (UI backend)

http:// :9876/mcp – MCP, coding mode (Streamable HTTP) http:// :9876/sse – MCP, coding mode (legacy SSE) http:// :9876/messages – MCP, coding mode (SSE message channel)

http:// :9876/support/mcp – MCP, support mode http:// :9876/support/sse – MCP, support mode (SSE) http:// :9876/support/messages – MCP, support mode (SSE message channel)

http:// :9876/knowledge/mcp – MCP, knowledge mode (stateless, bearer auth, POST only; mounted only when configured)

POST /api/index registers a project; POST /api/file-changed and POST /api/file-deleted update single files. See docs/tools.md for the full tool inventory per endpoint.

Knowledge mode

A docs-only MCP endpoint for a consumer in another network — an agent backend behind a load balancer that may search curated documentation and nothing else. Off unless PAPARATS_KNOWLEDGE_TOKENS and PAPARATS_KNOWLEDGE_AUDIENCE are both set; one without the other stops the server at startup.

• Tools: search_docs and get_document only. No glossary block, no resources, no workflow prompts. search_docs returns structuredContent with an outputSchema, so a wrapping service can build citations without parsing markdown.
• Auth: Authorization: Bearer , compared in constant time, checked before the request body is read. 401 + WWW-Authenticate: Bearer otherwise.
• Scope: documents labelled with an audience in PAPARATS_KNOWLEDGE_AUDIENCE (never internal), in the projects of PAPARATS_KNOWLEDGE_PROJECTS when set. Both are intersected with PAPARATS_DOCS_AUDIENCE / PAPARATS_PROJECTS when those are set. Out-of-scope documents read exactly like missing ones.
• Transport: stateless Streamable HTTP — a fresh server and transport per POST, no session id; GET/DELETE answer 405. 64 kB body limit, 1000-character query cap.

Documents get their audience at index time: frontmatter audience: first, then docs.audience from .paparats.yml / projects.yml, otherwise internal. An invalid frontmatter value is logged and stored as internal. See the documentation search guide.

Set `PAPARATS_KNOWLEDGE_PROJECTS` — otherwise a stray audience: in some code repository's README is enough to widen what the endpoint serves.

Expose only that path, POST only. For example with nginx:

location = /knowledge/mcp {

limit_except POST { deny all; } client_max_body_size 64k; proxy_pass http://paparats:9876; proxy_http_version 1.1; proxy_buffering off; # responses stream as text/event-stream } location / { return 404; }

Architectural memory

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

Three card kinds in a separate Qdrant collection per group (paparats_ _arch), embedded with qwen3-embedding-0.6b (1024d, last-pooled):

Similarity gate (cosine on qwen3-embedding-0.6b):

• >= 0.85 → duplicate. Decisions are refused so the agent must reconcile or supersede. Lessons bump updatedAt on the existing card (Reflexion "rule confirmed").
• 0.70 – 0.85 → similar. Nothing is written; the agent should refine wording or pass supersedes.
• < 0.70 → accepted as a new card.

supersedes bypasses the gate and marks the prior decision status=superseded so it disappears from default search but stays in history.

Reading via `arch_context` accepts min_score (default 0.45). Each returned card carries an updated N ago stamp and the cosine score so the agent can detect stale or low-confidence hits.

Bootstrap with `init_arch_memory` — a workflow prompt analogous to /init in Claude Code. Walks the repo, identifies 8-20 components by domain boundary, writes the cards. Followed by audit_architecture (sweep stale cards) and record_lesson_from_correction (turn user corrections into structured lessons).

MCP resources:

• arch://schema — full card-schema reference.
• arch://stats/{group} — live counts (total / by kind / by status) and oldest/newest updatedAt.

Prometheus metrics (PAPARATS_METRICS=true):

• paparats_arch_context_calls_total{group} — counter
• paparats_arch_write_total{kind, status} — counter labelled by gate outcome
• paparats_arch_search_score — histogram of cosine scores from arch_context
• paparats_arch_collection_size{group, kind, status} — gauge

arch_context is read-only on both MCP endpoints. arch_record_* is support-only — recording belongs to the architectural-review workflow.

Module map

| arch/context.ts | arch_context query