paparats-mcp
CLAUDE.md34 starsChanged 19 days agoMITView on GitHub
Semantic code search MCP server. Monorepo: packages/shared (shared utilities), packages/server (MCP server + HTTP API), packages/cli (CLI tool), packages/indexer (automated repo indexer), packages/embed (custom embedding server Docker image — llama.cpp llama-server + llama-swap), and packages/bench (private, unpublished offline retrieval benchmark — see docs/benchmarking.md). Nothing here may identify the organisation this was developed in, or any person. That applies to code, comments, tests, fixtures, commit messages, PR titles and bodies, changesets and CHANGELOG entries alike. Never commit, in any of those…
- Reads credentials
- Installs packages
In this repository3 other files it gives its agents.
- llms.txtllms.txt
- extract-terminologySkill
- review-pr-commentsSkill
The file
We split this CLAUDE.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
Never commit, in any of those places:
- Very specific: line 25
Verify before pushing with git diff origin/main over the whole change, not just the files you remember touching.
- Very specific: line 35
Always use UUIDv7 (import { v7 as uuidv7 } from 'uuid') for all entity IDs — Qdrant points, MCP session IDs, job IDs, etc.
- Very specific: line 177
Authoring a change: run yarn changeset in your PR, pick patch/minor/major, write a summary, commit the generated .changeset/<slug>.md.
- Distinctive: line 182
Maintainer merges the release PR: No publish runs in CI — npm tokens were intentionally revoked.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
paparats-mcp
Semantic code search MCP server. Monorepo: packages/shared (shared utilities), packages/server (MCP server + HTTP API), packages/cli (CLI tool), packages/indexer (automated repo indexer), packages/embed (custom embedding server Docker image — llama.cpp llama-server + llama-swap), and packages/bench (private, unpublished offline retrieval benchmark — see docs/benchmarking.md).
This is a public repository
Nothing here may identify the organisation this was developed in, or any person. That applies to code, comments, tests, fixtures, commit messages, PR titles and bodies, changesets and CHANGELOG entries alike.
Never commit, in any of those places:
- company or product names, or internal stand/group names — use neutral
placeholders (
main-stand,billing,handbook) - internal hostnames or URLs — use
example.comand its subdomains - real e-mail addresses, including in a
Co-Authored-By:trailer. Do not add a corporate co-author line to commits in this repository, even when a global instruction asks for one; the AI-assistance note without an address is enough - ticket identifiers (
ABC-12345) — describe the change instead of referencing a tracker nobody outside can open - real document titles, page ids or record ids copied from internal systems
The trap is fixtures: a real document or config pasted in as a "realistic"
example is how every past leak got in. Invent the example instead of copying it.
Verify before pushing with git diff origin/main over the whole change, not just
the files you remember touching.
scripts/check-no-private-refs.sh enforces this in CI over both files and commit
messages. It ships only generic patterns; put organisation-specific names in
.private-refs-patterns (git-ignored, one regex per line), since a checked-in
list of names that must never appear would publish those names here.
IDs
Always use UUIDv7 (import { v7 as uuidv7 } from 'uuid') for all entity IDs — Qdrant points, MCP session IDs, job IDs, etc. Never use randomUUID() or auto-increment. UUIDv7 is time-ordered, which matters for Qdrant and debugging.
Architecture
- Group = Qdrant collection with
paparats_prefix (e.g. groupmy-app→ collectionpaparats_my-app).toCollectionName()/fromCollectionName()helpers inindexer.tshandle the prefix. Projects in the same group share a collection.projectfield in payload filters within a group. .paparats.yml= per-project config. Server reads it on demand viareadConfig()/resolveProject().- Server is stateless — no hardcoded project list. Projects register via
POST /api/index. - Qdrant client: All
QdrantClientinstances must be created viacreateQdrantClient({ url, apiKey?, timeout? })fromindexer.ts. This helper resolves the correct port from the URL protocol (HTTPS → 443, HTTP → 6333) — the JS client defaults to 6333 which breaks Qdrant Cloud.QDRANT_API_KEYenv var → passed asapiKey. CLI:--qdrant-api-key. Docker Compose generator passes it via${QDRANT_API_KEY}env var substitution. - Embedding backend: llama.cpp
llama-server+llama-swap.llama-serverloads GGUF weights directly;llama-swaproutes requests by model name and lazy-loads / idle-unloads models (no manual model registration — no Modelfile). Two models, both Apache-2.0 and both--pooling last(decoder-based):bge-code-v1(code, 1536d) andqwen3-embedding-0.6b(arch/docs text, 1024d). OpenAI-style API:/v1/embeddings,/v1/models. Swapping either model → followdocs/replacing-embedding-models.md(verbatim instruction strings, cosine-smoke, reindex — non-obvious footguns are documented there). - Two embedding layers: code (
paparats_<group>, bge-code-v1, 1536d) and arch/docs prose (paparats_<group>_arch, qwen3, 1024d) are separate collections with separate models/dims — they never mix. Query instructions are family-specific and query-type-aware for code (bge-code has per-task strings); qwen has a single retrieval instruction, so query-type detection is a no-op on the prose layer. Instruction task strings are VERBATIM from each model's card (seetask-prefixes.ts— a paraphrase measurably degrades retrieval).
TypeScript conventions
- ESM only (
"type": "module"). Imports use.jsextension:import { Foo } from './foo.js' strict: true,noUncheckedIndexedAccess: true— always handleT | undefinedfrom array/object indexing- Target ES2022, module Node16
- Build:
yarn build(runstscin each package) - Lint:
yarn lint, format:yarn prettier
Module structure
packages/shared
path-validation.ts—validateIndexingPaths()— rejects absolute paths and path traversal inindexing.paths(used by server and CLI)exclude-patterns.ts—normalizeExcludePatterns()— bare dir names (e.g.node_modules) become**/node_modules/**for glob;anchorBuildOutputExcludes()narrows the default exclusion of build output folders (BUILD_OUTPUT_DIRS:build,dist,tmp,storage, ...) to the project root and each package root (a folder with aPACKAGE_MANIFESTSfile, found byfindPackageDirs()in the server'sconfig.ts), so source folders of those names stay indexed; a user-writtenexcludeis used as isgitignore.ts—createGitignoreFilter()(per-file checks),filterFilesByGitignore()(bulk filter) — used by CLI collectProjectFiles, server indexer, watchlanguage-excludes.ts—LANGUAGE_EXCLUDE_DEFAULTS,getDefaultExcludeForLanguages()— per-language exclude patterns
packages/server/src/
| Module | Responsibility | ||
types.ts | Shared interfaces — all type definitions live here | ||
lib.ts | Public library entry point — all re-exports for programmatic use (imported by index.ts, used by @paparats/indexer) | ||
config.ts | .paparats.yml reader, 11 built-in language profiles, loadProject(), detectLanguages(), autoProjectConfig() | ||
app.ts | Express app factory (createApp()), HTTP API routes, withTimeout(), sanitizeForLog() | ||
index.ts | Server bootstrap — starts HTTP server, wires components, graceful shutdown | ||
ast-chunker.ts | AST-based code chunking via tree-sitter — groups small nodes, splits large ones recursively | ||
chunker.ts | Regex-based code splitting (fallback) — 4 strategies (blocks, braces, indent, fixed) | ||
ast-symbol-extractor.ts | AST-based symbol extraction — extractSymbolsForChunks() (defines/uses per chunk, 11 languages). Each use also records the method it is made from (from, also when the method continues into a later chunk, and for a Ruby method defined in a block such as class_methods do, which defines nothing) and the class it is called on (on, as written plus the caller's namespace in, or a :: full path for self.x/this.x/a bare Ruby call; X.new(...).m and new X().m() are called on X), and each method its class by full path; stored as use_sites / def_owners. A Ruby constant records its lexical scope (lexical, in) and the namespace part of a path is not a use, unless a value constant is read from it (Lexer::MAX_DEPTH), and a path through a constant the file sets to a class (Saplings = ::Acme::Saplings, then Saplings::Shears) is read through that class (setting the constant holds nothing as a value; passing it on, dispatch(Saplings), holds the class); the name of a class / module statement is recorded as opens (opensRubyDefinition()); a TS/JS definition not exported is file-local (local_defs); Ruby def self.x is a class method (class_methods) and a call on a non-constant receiver is marked onObject; reopening a library class (RUBY_LIBRARY_CLASSES: Time, ActiveSupport::...) defines nothing; Ruby code in a heredoc tagged RUBY (RUBY_HEREDOC_TAG) is parsed for uses (addRubyHeredocUses()); a Ruby method called by its bare name without arguments, or through a key without a value (f(total:)), is a call on self when its class defines it in the file (addBareRubyCalls()). Calls between the methods of a chunk are kept apart as inner_calls (callee → calling methods), not as uses. A call on a variable, field or literal records its receiver's class when the file says (typedSite(), via receiver-types.ts; onObject with on = an object of that class), or external for a builtin or package (a Ruby connection, ActiveRecord's adapter, too); TS/JS uses record the import they come from (module; through import { a as b } under the exported name, and for names destructured from await import() or handed to import('./m').then(...); a member read from a module held whole, ns.Card, is a use of its Card), a call on an object of unknown type is onObject, and names read as values count (addTsValueUses(); export default X is recorded as default_export, not a use, and so is the component a wrapper exports, export default memo(X) / withAuth(X)), an export * from as a * re-export, and an import named like a definition of its own file stays a use of its module; classes record their superclass and mixins / extends / implements (parents, stored as def_classes). A Ruby module that only wraps classes and modules defines nothing (every file under a namespace reopens it). SYMBOL_FORMAT is stored as symbol_format and is part of the unchanged-file check, so bumping it after a query change re-extracts every file | ||
ast-queries.ts | Tree-sitter S-expression query patterns per language | ||
tree-sitter-parser.ts | WASM tree-sitter manager — createTreeSitterManager(), lazy grammar loading | ||
symbol-graph.ts | Cross-chunk symbol edges (calls, references, reexports, overrides — a call on self reaching a subclass override, opens — a Ruby module X in a file under the namespace another file defines, read by module_map, not followed by change_impact, impact_analysis or Called from; find_usages reads a called_by / referenced_by filter as the same edges seen from the other end). A call naming a class that defines the method links only there (resolveClass(): Ruby constant lookup on full paths — exact in one file EXTRACTED, path-suffix INFERRED, several AMBIGUOUS; a bare constant by Ruby's lexical lookup, resolveLexical(); a constant defined nowhere in the project gets no edge); edges carry the calling methods (from_symbols). A file-local TS/JS definition is reached only from its own file, where it wins; a call on an object skips class-method-only definitions; a bare call beside a top-level definition in its own file links there. A TS/JS re-export (export { x } from) is a use made from the exported name and links as reexports; module-map.ts skips those edges so a barrel file does not merge modules. A Ruby class used as a value (isRubyValue(): passed, in a hash/array/variable, Foo.new passed or stored in a hash or array, not returned or raised) links as references. A method call with a class (on, not a constant use) is resolved by resolveMember() over a ClassTable (classes by full path with their parents per file; a TS/JS class is the one its import or file declares): the nearest class up the ancestry defining the name (for a call on self, also one between a chunk's own methods via inner_calls, the overrides of the classes below too, as certain as the class: a template method calling the step its subclasses define), else a Ruby top-level method for a call on self, else the classes below it (interface implementations, a mixin's hosts; several of them each linked INFERRED, not AMBIGUOUS); a class the project lacks, or one where nothing answers, links to nothing, and so does an external use. A TS/JS use with a relative module links only to the definition that module exports (importedDefinitions(): through re-exports, export * and default exports, five files deep; EXTRACTED), under the name the definition has (import Provider from a PlanterProvider), also when nothing defines the local name, and to nothing when the module is not indexed; a name an ES module neither imports nor declares links only within its file, a member of an imported value (on + module, no class) only to its module, and nothing links to a .d.ts. Each edge also carries reach_symbols / reach_steps: the methods of the caller chunk that reach the calling methods through its inner_calls, with the calls between (innerReach()), for change_impact only — labels use from_symbols. The edges of a use depend only on it and on its name's definitions, so only builds just some uses' edges, for an incremental update. GRAPH_FORMAT is stored per project (graph_formats); a project built in an older one gets its whole graph built again from the stored symbols, no file extracted again | ||
receiver-types.ts | What a call's receiver holds, per file: RubyReceiverTypes (x = Foo.new or a Rails finder such as Foo.find_by(...) in the method, @x / `@x | =in the class, a method orattr_readerreturning one, a value constantRATES = Rates.new, literals; model = Invoiceis the class itself) andTsReceiverTypes(imports, top-level declarations, annotations on parameters / variables / fields, constructor parameter properties,this.x = new X(), a function's declared return type, builtins and Node modules as external`, installed packages too when the project's packages are known) | |
local-modules.ts | readLocalModules() — a project's own package names (every package.json outside node_modules) and tsconfig path aliases, with the folders and files under a baseUrl (core/hooks under baseUrl: "src"); any other bare import is an installed package. Null without a package.json or a directory (content sent by a client). resolveAliasImports() — a path alias import (~/lib/dates) as the relative specifier it resolves to (resolveAlias(): the nearest tsconfig.json / jsconfig.json above the file, its extends chain and baseUrl, a solution config's references), applied to the stored symbols when the graph is built, so an imported name links to its module's definition | ||
test-files.ts | readTestFiles() — a project's test files by name (*_spec.rb, *.test.ts, test_*.py, *_test.go), gitignore-filtered, whatever the index leaves out; recorded per project pass. testsNamedAfter() — the ones named after a file, of several those sharing most folders with it; change_impact lists them when no indexed test reaches the change | ||
change-impact.ts | collectDependents() — breadth-first walk over incoming edges for the coding-mode change_impact tool, by method: a dependent passes the change on only to callers of its methods that make or reach the call (from_symbols + reach_symbols; whole chunk when the call is outside a method), not through a references edge (a class held as a value) unless the class itself is the change (what a framework or job queue calls on it is not in the code: few such dependents were real in a blind check), nor through opens edges; after an overrides edge the methods reached are bound to an object of the subclass whose override changed, so a call on self into them from a class neither above that subclass (inherited or mixed in, at any depth) nor below it is not followed, each calling method of an edge judged apart (ownerOf / selfCallFrom / ancestorsOf, from the stored def_owners, use_sites and def_classes, read between walks; a class's parents are found through its file's edges; a method continued from an earlier chunk takes the class of the chunk's other methods); another method of the changed chunk reaching the change through other code (a calling a base method that calls the changed one on self) is a dependent like any other; AMBIGUOUS edges are set aside (viaAmbiguousNames), not followed; each dependent once at its nearest hop, with the other methods of its chunk reaching the calling ones (reach, from reach_symbols; listed as "further in this chunk"), certain false when every path goes through a common name kept by confirmsLink, hubs (called from many places: in-degree ≥ group p95, calledHubChunkIds) followed through the methods they are reached by, after the rest of their hop (so the limit cuts behind them first), not when reached as a whole chunk; tests listed but not expanded; tests have a cap (limit) of their own, apart from code, so they do not take the places of code the walk follows; a dependent is shown at the line its calling method is defined on (definitionLine()), not the chunk's first line; steps count method calls per method (step, from reach_steps; a lower bound, exact false, "at least N steps", on edges stored without them), methods of the changed chunk calling symbol count from their own step (seedSteps), and edgesToMethod adds the callers of a method that begins in an earlier chunk of the file; callers linked only through a common name (isCommonName() in symbol-graph.ts: a single lowercase word, or a Ruby conversion like to_s, used from more than 8 files, e.g. add, get, create; files counted from file_names in the metadata database, every use including those linked nowhere) are set aside unless their file also uses a specific name from the target's file | ||
change-impact-report.ts | changeImpactReport() — the text change_impact answers with, from a ChangeImpactSource (the server's index and metadata store, or a graph held in memory for offline checks): rows per dependent and step, the changed chunk's own methods calling it, a long method's chunks (the one it begins in included) in one row shown where it begins, at its nearest step (methodHeads(), the walk done again until no new one turns up), only what lies within depth steps listed, tests apart; shownLine() (1-indexed lines for people and agents) and callerLabel() | ||
module-map.ts | buildModuleMap() for module_map (coding + support): file-to-file weights from symbol edges (a use split over its definitions, scaled by ln(F/f)/ln(F) within the caller's project so names used everywhere count little), each project grouped on its own (its size sets the shared-file and split thresholds), Louvain communities with oversized ones split again, then split along packages and apps (splitByCodeRoot(); a part under 3 files joins the module of its own app it links to most), tests attached to the module they call most, migrations left out, shared files (clearly called from ≥15% of code files, ≥10) listed apart. A module is named after the folder that best matches its files (moduleFolders(): F1 of the module's share inside it and the folder's share in the module, or two folders joined by +, each with a fifth of the module, when they match better), and that folder's files come first among its main files. The heading says how many of the module's files those folders hold, of all their code files (folderFiles), unless the module is its folders and nothing else; each link shows its importing files, and a cut list says so in its label (Uses (top 4 of 12):). Links between modules are imports between the folders they are named after (folders), counted in importing files: only EXTRACTED edges (through an import or a known class; a name that merely matches is no link), and not overrides (a base class reaching its subclasses' code: the subclass's file names the base); a file counts there for the module whose folder holds it most closely, whichever module it is grouped into (of two modules named after that folder, the one it is grouped into, else one named after it alone), and an import into a file in no module's folder goes to the topmost folder above it holding no module's folder (usesFolders, listed apart as Uses folders; the reverse direction is not listed: on Ruby its precision stayed under 90%); each link records the file of the other module it reaches most (via). Links are kept per folder a module is named after (byFolder, PlaceLink: a module and one of its folders), and a module named after two folders lists them per folder (Uses, from X:); uses / usedBy sum them per module for the code map page and to pick the diagram's strong links. Top folders sums the imports between a project's top folders (topFoldersOf(): the root's folders, one holding over half the files opened into its own while they hold 80% of it). Modules named after one folder are named after a folder under it each when those are apart, else after their most called file (kept in links too), so no two share a name. ModuleMapService caches a map per project until its edgesVersion() changes (stored per project in the metadata database, so the indexer process's writes count), but rebuilds at most every 5 minutes; a group's map is merged from its projects' maps (mergeModuleMaps()); module_map ends with a Mermaid diagram (moduleMapDiagram(); a module named after two folders is a box per folder, arrows between folders, so no false cycle shows) | ||
graphql-contracts.ts | readGraphqlFacts() — what a project says about GraphQL, read from its files at each project pass, apart from the index (nothing here is embedded or searched): operations and fragments in .graphql / .gql files and inside source code (embeddedDocuments(): template strings, Ruby heredocs, Python gql("""...""")), schema tables from SDL files (schemaTable(): each type's fields with what they return, their line and arguments; parts without a root type join every schema of the project), graphql-ruby classes by syntax tree (rubyGraphqlClasses(): graphql_name, field also through base.field, its resolver: / mutation:, def and delegate, include / implements / Mixin.declare(self); only where a Gemfile names graphql), the files using each operation (generated names such as XDocument / useXQuery, its name quoted, its document file named from code), and the schema a graphql-codegen config assigns each document (documentSchemasOf()). What a project excludes stays out, except its tests. Recorded per project (api_facts, setApiFacts()) | ||
api-contracts.ts | linkContracts() — links between a group's projects, worked out when read from what each recorded, so a pass over one project leaves no link out of date: each operation walked over a schema (walkOperation(), through fragments, interfaces and unions; an argument the field lacks counts as a miss), the schema its code generator names, else the one it fits best, of equals those the client holds a copy of, and of an operation mostly outside every schema nothing is linked (unmatched: an outside API). Each selected Type.field joined to the code answering it (RubyProviders: a class named as the schema names the type, a mutation's fields on its XPayload; of classes sharing a type name, the one whose fields are most like the schema's; Ruby's lookup order; R#resolve of a resolver:, else the method named after the field, else the declaration), else to the schema's line. certain false when part of the operation does not fit or several schemas fit, naming different code. apiImpact() adds to change_impact and find_usages the operations reaching code (the changed chunk, or a dependent through the methods reaching the change), tests apart; apiCalls() adds to find_usages the server code answering what a chunk sends; repositoryLinks() adds to module_map who calls whose API. ApiContractsService caches per group until apiFactsVersion() changes. Only GraphQL, and server code only for graphql-ruby: elsewhere a field links to its schema line | ||
module-map-api.ts | GET /api/module-map (modules), /tree, /module, /file, /search — JSON for the console's /ui/map code map (ui/map.html + ui/map.js, vanilla SVG; every view is a URL, pushState history). Always reads the group's map so module ids match across routes; shares the ModuleMapService cache with the tool; behind PAPARATS_UI_BASIC_AUTH like /api/analytics | ||
map-explorer.ts | Views over a module map for the code map page: folderView() (a folder's children with summed calls, folders elsewhere it links to, modules with files there; a folder holding one folder opens it; at most 24 children, the rest folded into one node), moduleView(), fileView(), searchFiles() | ||
embeddings.ts | LlamaServerProvider, EmbeddingCache (SQLite), CachedEmbeddingProvider | ||
indexer.ts | Group-aware Qdrant indexing — createQdrantClient(), toCollectionName()/fromCollectionName() prefix helpers, single-parse chunkFile() (AST chunking + symbols), file CRUD. Every file written or removed is recorded with the names its old and new chunks define (graph_changes); updateSymbolGraph() then works out again only the edges of those files and every use of those names, reading just those chunks, and replaces them in one transaction — the whole graph is built only when the project has none, more than MAX_INCREMENTAL_GRAPH_FILES changed, or a file added, removed or re-parented a class (CLASSES_CHANGED); an update also reads every class its chunks call on or inherit from, up their chains (addClassChains()), and links again the imported names of the chunks with an edge into a changed file (an import under another name is not found by the names that file defines). For TS/JS, the project's packages (readLocalModules(), cached per project path) go to the extractor. A project pass records the project's test files (readTestFiles()) and updates the graph at the end; single-file writes outside one (updateFile, updateFileContent, indexFilesContent, deletes) schedule the update GRAPH_UPDATE_DELAY_MS after the last change (flushSymbolGraphs() waits for it) | ||
searcher.ts | Vector search with project filtering, query expansion (support tools only), query cache, metrics instrumentation | ||
query-expansion.ts | Abbreviation, case variant, plural, filler word expansion for search queries | ||
task-prefixes.ts | Query-type detection (nl2code / code2code / techqa) mapped to verbatim bge-code-v1 / Qwen3 query instructions | ||
embed-text.ts | chunkEmbedText() — the text a code chunk is embedded as: Filepath: <path>, ---, the chunk. Payload content stays the plain chunk. EMBED_TEXT_FORMAT is stored as embed_format and is part of the unchanged-file check, so bumping it re-embeds every file | ||
ranking.ts | rankKey() — rank-time order for search_code: test files ×0.9 unless the query mentions tests; for a query naming identifiers (identifierTokens()), chunks defining one ×1.1 (×1.25 when the query is only that name) and files named after one ×1.05, and definitionCandidatesFilter() adds the chunks that define them to the candidates; every result ×(1 + 0.05·file_churn); the shown score stays the similarity. conventionalTestPaths() — where a file's tests sit by convention, which change_impact lists when no indexed test reaches the change and the project's test files are not recorded | ||
file-churn.ts | readFileCommitCounts() (git log per file, relative to the project) and churnPercentiles() — each file's commit-count percentile in its project, rounded to 20 steps. The indexer writes it as file_churn after a project pass that wrote chunks (one payload update per step); no git history leaves it unset | ||
query-cache.ts | In-memory LRU cache with TTL and group-level invalidation for search results | ||
indexer-health.ts | fetchIndexerHealth() — the indexer's /health (with the API key when set; never throws, an unreachable one is reachable: false), indexerUrlFromEnv() (PAPARATS_INDEXER_URL). Used by the analytics page and health_check, which reports the indexer's last run and each repository's status and error | ||
qdrant-batch.ts | upsertWithRetry() — batches of 128, each tried three times; for points that exist nowhere else (an arch or glossary reindex after its collection was dropped) | ||
qdrant-errors.ts | isMissingCollection() — tells a missing collection (nothing indexed yet) apart from a Qdrant failure; describeQdrantError() — names a connection failure (ECONNREFUSED, ...) behind Node's bare fetch failed | ||
metrics.ts | Prometheus metrics (@prometheus-io/client) with NoOpMetrics fallback. Opt-in via PAPARATS_METRICS=true | ||
metadata.ts | Tag resolution (resolveTags()) + auto-detection from directory structure | ||
metadata-db.ts | SQLite store for git commits, tickets, each project's test files (test_files, paths only), symbol edges and the files their graph has not caught up with (graph_changes, kept until applyGraphChanges(), so a missed update is applied by the next one), each project's GRAPH_FORMAT (graph_formats), and per file the names its code uses that may be common (file_names: single lowercase words, so getNameUsage() counts every file using a name, linked or not); edges of a file or project are deleted by id range, not a LIKE scan | ||
git-metadata.ts | Git history extraction — commit mapping to chunks by diff hunk overlap | ||
ticket-extractor.ts | Jira/GitHub/custom ticket reference parsing from commit messages | ||
mcp-handler.ts | MCP protocol (SDK 2) — three endpoints: coding (/mcp), support (/support/mcp) and knowledge (/knowledge/mcp, opt-in) with isolated tool sets and instructions. Stays on protocol revision 2025-11-25 with sessions: search_code hides what it returned earlier in a session, and on 2026-07-28 clients send nothing that tells sessions apart. delete_project deletes only on a yes through elicitation, and refuses a client that does not declare it | ||
workflow-skills.ts | loadWorkflowSkills() — the workflow prompts as a skills catalog (Skills over MCP, in memory, no files to copy into the image), attached in coding and support; workflowSkillText() renders a prompt as a SKILL.md, required arguments as <name> | ||
knowledge-mode.ts | Knowledge mode — parseKnowledgeModeEnv(), bearer auth (constant-time), 64 kB body limit guards mounted before the global parser, scope intersection | ||
api-key-auth.ts | Optional API key — parseApiKeysEnv() (PAPARATS_API_KEY, comma-separated, ≥ 16 characters; unset = open, a malformed key stops startup), apiKeyAuth() (bearer, or a basic-auth password for browser pages; mounted before the body parser; open paths /health and /knowledge/mcp, and the UI routes when PAPARATS_UI_BASIC_AUTH guards them), hasApiKey() (/health shows only its status without the key). The indexer mounts the same guard on /trigger and /metrics; the shared token helpers (tokenMatches(), constant-time) are used by the knowledge mode too |
packages/indexer/src/
| Module | Responsibility |
index.ts | Entry point — wiring only: Express mini-server (POST /trigger, GET /health) + dual cron scheduler bootstrap (fast change-check + slow safety-net) + projects.yml hot reload, all driving IndexOrchestrator. Exposes its own GET /metrics on port 9877 when PAPARATS_METRICS=true — Prometheus must scrape both endpoints (server :9876/metrics + indexer :9877/metrics) to see indexing counters |
config-loader.ts | loadIndexerConfig(), tryLoadIndexerConfig() — parses projects.yml, merges per-repo overrides with defaults, returns RepoConfig[] + cron + cron_fast |
repo-url.ts | parseRepoSpec() — a remote entry: owner/repo (GitHub) or an https:// URL of any host (GitHub Enterprise, GitLab subgroups; fullName = host/path, clone folder host/group/...); SSH and credentials in the URL are refused |
repo-manager.ts | parseReposEnv(), cloneOrPull() using simple-git — clones are a managed cache: an existing one is re-pointed at the current URL and hard-reset to the remote default branch, re-cloned on any failure; credentials are masked in errors |
orchestrator.ts | IndexOrchestrator — runs index cycles, /trigger requests and hot-reload work through one per-repo lock; purges repos removed from (or moved within) projects.yml; persists a fingerprint only when indexing and the docs pass both succeeded |
project-resolver.ts | resolveRepoProject() — builds a raw config from .paparats.yml + projects.yml overrides and resolves it through the server's resolveProject; group precedence PAPARATS_GROUP > override > .paparats.yml |
git-auth.ts | gitAuthEnv() — GITHUB_TOKEN as an Authorization header scoped to https://github.com/ via GIT_CONFIG_* env, and each GIT_TOKENS host=token pair (parseGitTokens()) scoped to https://<host>/, applied once at startup; clone URLs never carry the token (libcurl 8.23 drops URL credentials mid-fetch → 401). createGit() — every git call goes through it: simple-git 4 strips ambient GIT_* env unless allowed by name |
keyed-serializer.ts | KeyedSerializer — one task at a time per key (repo), different keys concurrently |
trigger-queue.ts | TriggerQueue — merges full-cycle requests that arrive during a running cycle (repo sets union, force stays per repo) |
scheduler.ts | startScheduler() — node-cron wrapper for scheduled index cycles |
change-detector.ts | GitDetector (remote ls-remote HEAD), MtimeDetector (file stat hash) — produce fingerprints used to decide whether to re-index |
state-store.ts | SQLite store of per-repo fingerprints (default /data/indexer-state.db); persisted between cron ticks |
types.ts | IndexerConfig, RepoConfig, RepoOverrides, IndexerFileConfig, RunStatus, HealthResponse |
packages/embed/
| File | Responsibility |
Dockerfile | Builds a llama.cpp llama-server + llama-swap image with bge-code-v1 + qwen3-embedding-0.6b GGUF pre-baked (~2.3 GB of models, a 2.5 GB download; CPU-only, zero-config startup). llama-swap serves on port 8080, lazy-loads models by name; models stay resident by default (EMBED_TTL=0), opt-in idle unload via EMBED_TTL |
packages/cli/src/
| Module | Responsibility |
docker-compose-generator.ts | Programmatic YAML generation — generateCompose() (qdrant and embed optional, server, indexer, local project mounts). examples/docker-compose/ holds its output for plain docker compose up (scripts/generate-compose-examples.js; a test keeps them equal) |
local-urls.ts | localUrls() — server / indexer / Qdrant URLs from the ports in ~/.paparats/.env (what the compose publishes), overridden by PAPARATS_SERVER_URL / PAPARATS_INDEXER_URL / QDRANT_URL; every command's default. Also apiKey (PAPARATS_API_KEY, environment over the file) and authHeaders(), sent by ApiClient, the indexer calls and the MCP client wiring of install |
Key patterns
- Grammars: tree-sitter WASM grammars come from
tree-sitter-wasms, except TypeScript, TSX and JavaScript, which ship inpackages/server/grammars(newer builds; the old ones fail on&in JSX attribute strings). Both Dockerfiles copy that folder - AST-first chunking:
indexer.chunkFile()parses once with tree-sitter, uses the AST for both chunking (chunkByAst) and symbol extraction (extractSymbolsForChunks), then deletes the tree. Falls back to regexChunkerfor languages without a grammar - Chunk line numbers are 0-indexed throughout (chunker, AST chunker, symbol extractor, Qdrant payload). Text meant for people and agents (MCP tool output,
paparats search) shows them 1-indexed, as editors and grep do (shownLine()inchange-impact-report.ts); JSON from the HTTP API keeps the stored values - Qdrant operations use
retryQdrant()with exponential backoff (3 retries) - Embedding cache: SQLite at
~/.paparats/cache/embeddings.db, Float32 vectors, LRU cleanup at 100k entries CachedEmbeddingProviderwraps anyEmbeddingProvider— all embedding calls go through cache- Query cache: in-memory LRU with TTL (default 5min, 1000 entries).
searcher.invalidateGroupCache()drops a group's entries after the server's own writes:POST /api/index,POST /api/file-changed,POST /api/file-deleted,DELETE /api/project/:group/:nameand the MCPdelete_projecttool. The indexer container writes to Qdrant directly, so its updates reach search once cached entries expire (TTL) - Prometheus metrics: opt-in via
PAPARATS_METRICS=true.GET /metricsexposes counters (search, index), histograms (search/embedding duration), gauges (cache sizes, hit rates).NoOpMetricsfallback when disabled — zero overhead - Three MCP modes: coding (
/mcp,/sse), support (/support/mcp,/support/sse) and knowledge (/knowledge/mcponly). Each mode has its own tool set andserverInstructions. Coding:search_code,get_chunk,find_usages,change_impact,module_map,health_check,list_projects,delete_project,search_docs, allarch_*tools andterm_*tools. Support:search_code,get_chunk,find_usages,health_check,list_projects,search_docs, plusget_chunk_meta,search_changes,explain_feature,recent_changes,impact_analysis,module_map,get_document, the six analytics tools andterm_search/term_list(noarch_*, noterm_*writes — support is strictly read-only, enforced by a test over tool annotations). Knowledge:search_docs+get_document, nothing else (no resources, no prompts, no glossary). Tool sets defined byCODING_TOOLS/SUPPORT_TOOLS/KNOWLEDGE_TOOLS;createMcpServer(mode)registers only the relevant tools.node packages/server/dist/index.js --stdioserves the coding mode over stdin/stdout instead of HTTP (McpHandler.connectStdio(); all logging goes to stderr) — used by registry inspectors such as Glama that spawn the server - Knowledge mode: docs-only endpoint for consumers outside the trust boundary. Off unless
PAPARATS_KNOWLEDGE_TOKENS+PAPARATS_KNOWLEDGE_AUDIENCEare both set (one alone refuses to start); optionalPAPARATS_KNOWLEDGE_PROJECTSallowlist. Bearer auth + 64 kB body limit run before the global 50 MB parser; the handler refuses requests that skipped them. Stateless Streamable HTTP (fresh server + transport per POST,GET/DELETE→ 405). Its ceiling/allowlist are intersected withPAPARATS_DOCS_AUDIENCE/PAPARATS_PROJECTS;internalis never allowed in its ceiling. Out-of-scope documents must read exactly like missing ones; backend errors are reported generically. Texts live inprompts.jsonunderknowledgeInstructions/knowledgeTools - Docs audience labels: every docs chunk stores one
audience. Resolved per document at index time: frontmatteraudience:>docs.audience(.paparats.yml, orprojects.ymlrepo/defaults, which wins over the repo file) >internal. Labels match^[a-z0-9][a-z0-9_-]{0,63}$; invalid in config fails loading, invalid in frontmatter is logged and stored asinternal(never the project default). Each docs pass rewrites every document (newdoc_id), so label changes need no migration.get_documentkeys by (project, file), notdoc_id, for that reason - Orchestration tools (
explain_feature,recent_changes,impact_analysis): support-mode only. Compose search + metadata + edges in a single MCP call. Return structured markdown without code content. UseresolveChunkLocation()helper for payload extraction. Gracefully degrade whenmetadataStoreis null (skip metadata sections, still return search results) - Server lib extraction:
packages/server/src/lib.tsis the public library entry point (all re-exports).index.tsre-exports fromlib.ts. Server'spackage.jsonexportsmap points tolib.jsso importing@paparats/serverdoesn't execute the server bootstrap - Docker embed server:
ibaz/paparats-embed— llama.cppllama-server+llama-swapwithbge-code-v1+qwen3-embedding-0.6bGGUF pre-baked (~2.3 GB of models, a 2.5 GB download; CPU-only, both Apache-2.0). llama-swap serves on port 8080, routes by model name, lazy-loads on first request; models stay resident by default (EMBED_TTL=0— llama-swap's unload/swap path can deadlock under load, see theswap: falsegroup in the config), opt-in idle unload viaEMBED_TTL. No Modelfile, noollama create— models ready on container start. ~5–9× faster than Ollama on CPU - Docker Compose generator:
packages/cli/src/docker-compose-generator.tsbuilds YAML programmatically withgenerateCompose(): Qdrant (unless external), the embed server (Docker embed mode with local models only), server and indexer. With a cloud embedding provider the prose layer (TEXT_EMBEDDING_*) goes to the same provider. The indexer keeps its state DB on the sharedpaparats_datavolume (STATE_DB_PATH) - Install modes:
paparats install= the Docker stack with the indexer, embed mode choice (--embed-mode native|docker), wires Cursor and Claude Code, fails when a service does not come up (waitForStack()).--mode support= client-only MCP config (no Docker).--embed-urlskips the local embed server entirely (no binary check, no GGUF download). Native macOS embed mode installs viabrew install llama.cpp mostlygeek/llama-swap/llama-swap(Metal-accelerated) - Indexer container:
packages/indexer— separate Docker image that clones repos and indexes on a schedule. UsesIndexerclass from@paparats/serveras a library. HTTP trigger atPOST /trigger, health atGET /health - Indexer config file:
projects.ymlmounted at/config/in the container. Per-repo overrides (group,language,indexing.exclude, etc.) with globaldefaultssection. Priority: indexer YAML overrides >.paparats.ymlin repo > auto-detection, for the fields merged onto a repo's own file (group,docs.kind,docs.audience,indexing.*); a repo's.paparats.ymlkeeps itslanguageandmetadata. Falls back toREPOSenv when no config file present.CONFIG_DIRenv controls the lookup directory - Indexer change detection: two cron schedules run side by side. Fast
CRON_FAST(default*/10 * * * *) computes a fingerprint per repo and only invokesindexProject()when it differs from the last persisted value; slowCRON(default0 */3 * * *) is the safety-net full pass. A forced run (/triggerwithforce) over a collection built with another embedding model drops the whole collection (dropCollectionIfModelChanged()) and queues a full cycle, so every repo of it is indexed again. Remote repos fingerprint viagit ls-remote HEAD; bind-mounted local repos via mtime/size hash of the project's file set (same patterns/excludes as indexing). State persists inSTATE_DB_PATH(default/data/indexer-state.db). The fingerprint is taken before the repo is pulled and persisted only when every file and the docs pass indexed without error; detector failures fall through to a defensive reindex. Repos removed from projects.yml are purged (code, metadata, docs) on hot reload. SetCHANGE_DETECTION=falseto opt out
Testing
yarn test # vitest
yarn typecheck # tsc --noEmit
yarn bench run # opt-in retrieval benchmark; needs Qdrant + embed server (docs/benchmarking.md)Retrieval changes (ranking, chunking, models, prefixes) should come with a yarn bench compare diff against main.
Versioning
Releases are driven by Changesets in fixed mode — all four publishable packages (@paparats/shared, @paparats/cli, @paparats/server, @paparats/indexer) bump together. There is no yarn release command; never bump versions by hand.
Authoring a change: run yarn changeset in your PR, pick patch/minor/major, write a summary, commit the generated .changeset/<slug>.md.
Release flow:
- CI opens a release PR (
.github/workflows/release.yml). On every push tomainwith pending.changeset/*.mdfiles,changesets/action@v1runsyarn run versionand opens (or updates) achore: release X.Y.ZPR. Theversionscript chains:changeset version→scripts/sync-server-json.js(syncsserver.json+ rootpackage.jsonfrompackages/cli/package.json) →scripts/aggregate-changelog.js(mirrors per-package entries into rootCHANGELOG.md) →yarn install --no-immutable. - Maintainer merges the release PR. No publish runs in CI — npm tokens were intentionally revoked.
- Maintainer publishes locally:
yarn release:local(or--dry-runto preview). The script inscripts/release-local.shverifies main is clean and up-to-date, no pending changesets, then builds, runsyarn changeset publish, pushes avX.Y.Ztag and creates the GitHub Release from the version's rootCHANGELOG.mdsection. The tag (not the release) triggersdocker-publish.ymlandpublish-mcp.yml; the GitHub Release is what Glama's Auto-Release builds from.
Single source of truth for the bumped version: packages/cli/package.json. sync-server-json.js propagates it to root package.json and server.json. The aggregator merges the entries of all four packages/*/CHANGELOG.md (a changeset lands only in the changelogs of the packages it names, so no single file is complete), de-duplicates them, drops dependency-bump boilerplate and rewrites a marker-delimited block in the root CHANGELOG.md — idempotent, safe to re-run.
Docker
packages/server/Dockerfile— builds and runs the server (ibaz/paparats-server)packages/indexer/Dockerfile— builds the indexer (ibaz/paparats-indexer)packages/embed/Dockerfile— builds llama.cppllama-server+llama-swapwith pre-bakedbge-code-v1+qwen3-embedding-0.6bGGUF models (ibaz/paparats-embed)examples/docker-compose/— ready compose files (local models, Voyage) +projects.yml+.env.examplefor a plaindocker compose uppackages/cli/src/docker-compose-generator.ts— generates docker-compose.yml at install time- Qdrant at
:6333, MCP server at:9876, Indexer at:9877. The generated compose publishes Qdrant and the Docker embed server on127.0.0.1only (QDRANT_BIND/EMBED_BIND): they have no auth, andPAPARATS_API_KEYcovers only the server and the indexer - Embed server (llama-swap on internal port 8080, mapped to host 18434 — not Ollama's 11434, so both can run): native mode via
host.docker.internal:18434, Docker mode viahttp://embed:8080, external via--embed-url
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

