@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://<host>:9876/metrics β Prometheus (PAPARATS_METRICS=true)
http://<host>:9876/ui β operator console
http://<host>:9876/api/analytics/... β analytics REST API (UI backend)
http://<host>:9876/mcp β MCP, coding mode (Streamable HTTP)
http://<host>:9876/sse β MCP, coding mode (legacy SSE)
http://<host>:9876/messages β MCP, coding mode (SSE message channel)
http://<host>:9876/support/mcp β MCP, support mode
http://<host>:9876/support/sse β MCP, support mode (SSE)
http://<host>:9876/support/messages β MCP, support mode (SSE message channel)
http://<host>: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 <token>, 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_<group>_arch),
embedded with qwen3-embedding-0.6b (1024d, last-pooled):
| Kind | Fields | Idempotency |
|---|
| Component | name, summary (markdown: Does / Owns / Does not / Touched when), files, neighbours, anchors | By name (structural) |
| Decision | title, context, decision, alternatives_rejected, consequences, scope, supersedes | Server-side similarity gate |
| Lesson | rule, why, when, scope, severity, evidence | Server-side similarity gate |
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
| Module | Responsibility |
|---|
types.ts | Shared interfaces |
lib.ts | Public library entry point (re-exports for programmatic use) |
config.ts | .paparats.yml reader, 11 language profiles, autoProjectConfig() |
app.ts | Express app factory, HTTP API routes, request wiring |
index.ts | Server bootstrap β starts HTTP server, wires components, graceful shutdown |
ast-chunker.ts | AST-based chunking via tree-sitter |
chunker.ts | Regex chunking fallback (4 strategies) |
ast-symbol-extractor.ts | AST-based per-chunk symbol extraction |
ast-queries.ts | Tree-sitter S-expression queries per language |
tree-sitter-parser.ts | WASM tree-sitter manager β lazy grammar loading |
symbol-graph.ts | Cross-chunk symbol edges |
embeddings.ts | llama-server provider + SQLite cache + cached wrapper |
indexer.ts | Group-aware Qdrant indexing β createQdrantClient(), toCollectionName(), single-parse chunkFile() |
searcher.ts | Vector search, query expansion (support tools only), cache, metrics |
query-expansion.ts | Abbreviation / case / plural / filler expansion |
task-prefixes.ts | Query-type detection + bge-code-v1 / Qwen3 query instructions |
query-cache.ts | In-memory LRU cache with TTL and per-group invalidation |
metrics.ts | Prometheus metrics (prom-client) + NoOpMetrics fallback |
metadata.ts | Tag resolution + auto-detection from directory structure |
metadata-db.ts | SQLite store for git commits, tickets, symbol edges |
git-metadata.ts | Git history extraction β diff-hunk mapping to chunks |
ticket-extractor.ts | Jira / GitHub / custom ticket parsing |
mcp-handler.ts | MCP protocol β coding, support and knowledge endpoints with isolated tool sets and instructions |
knowledge-mode.ts | Knowledge mode β env parsing, bearer auth, body limit, scope intersection |
arch/types.ts | Architectural-memory types |
arch/collection.ts | Per-group paparats_<group>_arch collection lifecycle |
arch/text-embeddings.ts | qwen3-embedding-0.6b text embedder via llama-server |
arch/store.ts | CRUD + server-side similarity gate + stats() aggregation |
arch/context.ts | arch_context query β top-N across kinds with min_score and age stamps |
Configuration (env vars)
| Variable | Default | Notes |
|---|
PORT | 9876 | HTTP port |
QDRANT_URL | http://localhost:6333 | Qdrant endpoint (https β port 443, http β 6333) |
QDRANT_API_KEY | β | Qdrant Cloud API key |
EMBED_URL | http://127.0.0.1:18434 | Embed server endpoint (llama-swap; internal port 8080, host port 18434 in the generated stack) |
EMBED_BATCH_SIZE | β | Embeddings per llama-server call |
EMBED_TTL | 0 | Idle seconds before a model unloads; 0 = never (default) |
EMBEDDING_PROVIDER | llama | Code embedding provider: llama | openai | voyage |
EMBEDDING_MODEL | bge-code-v1 | Code embedding model |
EMBEDDING_DIMENSIONS | 1536 | Code embedding dimensions |
TEXT_EMBEDDING_PROVIDER | llama | llama, openai or voyage for the arch layer |
TEXT_EMBEDDING_MODEL | qwen3-embedding-0.6b | Arch-layer text embedding model |
TEXT_EMBEDDING_DIMENSIONS | 1024 | Arch-layer text embedding dimensions |
PAPARATS_METRICS | false | Set to true to expose /metrics |
PAPARATS_PROJECTS | β | Comma-separated allow-list of project names |
PAPARATS_DOCS_AUDIENCE | β | Comma-separated audience ceiling for search_docs / get_document on the coding and support endpoints |
PAPARATS_KNOWLEDGE_TOKENS | β | Comma-separated bearer tokens (β₯ 16 characters) for /knowledge/mcp. Set together with PAPARATS_KNOWLEDGE_AUDIENCE, or neither |
PAPARATS_KNOWLEDGE_AUDIENCE | β | Audience ceiling of /knowledge/mcp; internal is refused |
PAPARATS_KNOWLEDGE_PROJECTS | β | Optional project allowlist of /knowledge/mcp β recommended |
PAPARATS_API_KEY | β | Optional: comma-separated keys (β₯ 16 characters); every route but /health and /knowledge/mcp then wants Authorization: Bearer <key>. Unset, the server is open (localhost, VPN). A malformed key stops startup |
PAPARATS_UI_BASIC_AUTH | β | user:pass for /ui, /api/analytics/... and /api/module-map/... (else they take the API key as a basic-auth password); a malformed value stops startup |
PAPARATS_CORS_ORIGINS | β | Comma-separated exact origins (e.g. https://app.example.com) browsers may call the server from. Unset = no CORS headers, and any request whose Origin is neither this server nor listed gets 403. Requests without Origin (MCP clients, curl) are unaffected |
OTEL_* | β | Standard OpenTelemetry env vars (Tempo / Honeycomb / Datadog / Elastic APM) |
Programmatic use (library)
The package.json exports map points at dist/lib.js, not the server bootstrap.
Importing @paparats/server does not start the HTTP server β @paparats/indexer
uses this to embed the Indexer class as a library:
import { Indexer, createQdrantClient } from '@paparats/server';
const qdrant = createQdrantClient({ url: process.env.QDRANT_URL! });
const indexer = new Indexer({ qdrant, });
await indexer.indexProject(group, project);
Docker
docker pull ibaz/paparats-server:latest
docker run --rm -p 9876:9876 \
-e QDRANT_URL=http://qdrant:6333 \
-e EMBED_URL=http://embed:8080 \
ibaz/paparats-server:latest
See examples/docker-compose for a complete
stack (Qdrant + embed server + server + indexer).
Development
yarn install
yarn workspace @paparats/server build
yarn workspace @paparats/server test
yarn workspace @paparats/server typecheck
License
MIT