Paparats MCP

MCP 设备

](https://www.npmjs.com/package/@paparats/cli)   ](https://lobehub.com/mcp/ibazylchuk-paparats-mcp)

帕帕拉特斯kvetka --一种来自斯拉夫民间传说的神奇花朵，在库帕拉之夜绽放 并赋予发现它的人看到隐藏事物的能力。同样，狗仔队的mcp 帮助您的代理在存储库的海洋中看到正确的代码。

🌿 适用于 克劳德密码·光标·风帆·复制品·法典·反重力 ·任何MCP兼容代理

让你的AI编码助手深入、真实地了解你的整个工作空间。 Paparats为你关心的每个repo建立索引——语义上，使用AST感知的组块和 跨块符号图——并通过模型上下文协议公开它。搜索 根据含义，遵循 who-uses-what 通过真实的符号边缘，看看谁最后一次触摸了 块以及它来自哪张票——所有这些都不需要你的代码离开你的机器。

• ⚡ 一次安装，一次配置。 paparats install → paparats add ~/code/repo → done.
• 🌳 AST感知分块和符号提取。 Tree sitter解析每个支持的

文件一次，并同时馈送分块和跨块符号图（调用/ called_by/references/reference_by）——11种语言， Go、Rust、Java、Ruby、C、C++、C#。

• 💸 保存令牌。 仅返回重要的块，并使用令牌节省遥测

以证明这一点（每个查询、每个用户、每个锚项目）。

• 🔭 生产就绪可观察性。 普罗米修斯 /metrics，OpenTetry跟踪

（Tempo、Jaeger、Honeycomb、Datadog、Grafana Cloud），本地SQLite分析，有六个 用于成本报告的内置MCP工具。

• 🏠 默认情况下为100%本地。 Qdrant+Ollama在您的机器上。没有云，没有API密钥，

没有遥测数据离开盒子。如果你愿意，可以带上你自己的Qdrant Cloud/Ollama网址。

______________________________________________________________________

目录

• 为什么是木瓜？
• 快速开始
• 安装是如何工作的
• 安装变体
• 从v1安装迁移
• 支持代理设置
• 运作原理
• 主要特点
• 用例
• 配置
• MCP工具参考
• 连接MCP
• CLI命令
• 监控
• 分析和可观察性
• 建筑
• 嵌入模型设置
• 与备选方案的比较
• 代币节省指标
• 贡献
• 链接

______________________________________________________________________

为什么是木瓜？

AI编码助手很聪明，但他们只能看到你打开的文件。他们不知道你的代码库结构、身份验证逻辑所在的位置，也不知道服务是如何连接的。 Paparats解决了这个问题。

你得到了什么

• 语义代码搜索 --问“限速逻辑在哪里？”并获得按含义排列的确切代码，而不是grep匹配
• 实时同步 --编辑一个文件，2秒后它会被重新索引。无需手动重新运行
• 跨块符号图 — find_usages 遍历AST派生的边（调用，called_by，引用，reference_by），这样代理就可以跟踪依赖关系，而无需重新进行grepping
• 代币节省 --仅返回相关块而不是完整文件，以减小上下文大小
• 多项目工作空间 --在一个查询中跨后端、前端、infrepos进行搜索
• 100%本地和私人 --Qdrant矢量数据库+Ollama嵌入。你的笔记本电脑里什么都没有
• AST感知分块 --通过树形图按AST节点（函数/类）拆分代码，而不是任意字符计数（TypeScript、JavaScript、TSX、Python、Go、Rust、Java、Ruby、C、C++、C#；用于Terraform的正则表达式回退）
• 元数据 --每个块都知道它的符号名称（来自树型AST）、服务、域上下文和来自目录结构的标签
• 每个区块的Git历史记录 --查看上次修改块的人、时间以及链接到该块的票证（Jira、GitHub）

谁受益

______________________________________________________________________

快速开始

你需要 码头工人 和 Docker Compose v2。在macOS上，也安装 Ollama本地 — 在macOS上的Docker中运行它要慢得多，因为Docker VM不能 使用Apple Silicon GPU加速。

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

# 2. macOS only — install Ollama natively (Linux uses Docker Ollama by default).
brew install ollama

# 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 git@github.com:acme/billing.git
paparats add acme/widgets

# 5. Watch it work.
paparats list

就是这样。你的IDE已经连接好了(~/.cursor/mcp.json, ~/.claude/mcp.json)to http://localhost:9876/mcp.打开Cursor或Claude Code并询问：

“在这个工作区中搜索身份验证中间件，并向我显示调用它的所有内容。”

现有v1用户？

跑 paparats install 再一次。安装程序检测每个项目的遗留问题 compose，在将其交换为新的全局设置之前询问一次，以及 保存您的 索引数据 （Qdrant集合、SQLite元数据、嵌入缓存）。您的回购 .paparats.yml 文件按照项目覆盖继续工作。

______________________________________________________________________

安装是如何工作的

paparats install 是唯一的设置命令。它创建了一个单一的全球家园 ~/.paparats/，打开一个Docker堆栈，并连接您的MCP客户端。随时重新运行 要重新配置，它会与现有的组合不同，并在覆盖手动编辑之前进行询问。

~/.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/                     jina-code-embeddings GGUF + Modelfile
└── data/                       Docker volumes (mounted by name from compose)
    ├── qdrant/                 vector index
    ├── sqlite/                 metadata.db, embeddings.db, analytics.db
    └── repos/                  cloned remote projects

Docker堆栈内部：

索引器热重新加载 projects.yml.编辑该内容 更改项目元数据 仅 （组、语言、索引调整）重新索引到位。编辑该 添加或删除 本地路径项目 需要重新启动堆栈，以便Docker获取新的绑定挂载-- CLI在上为您执行此操作 paparats add 和 paparats remove.

______________________________________________________________________

安装变体

默认值（推荐）

paparats install

在macOS上，更喜欢原生Ollama和停靠的Qdrant。Linux默认使用Docker 两者都有。

带上你自己的Qdrant

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

当 --qdrant-url 设置后，Qdrant容器将从堆栈中完全省略。

带上你自己的Ollama

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

跳过原生和Docker Ollama。

您必须自己在远程Ollama上注册嵌入模型。 安装程序 不会接触远程实例。在Ollama主机上，下载GGUF (jinaai/jina-code-embedding-1.5b-Q8_0.gguf) 并运行： ``bash echo "FROM /path/to/jina-code-embeddings-1.5b-Q8_0.gguf" > Modelfile ollama create jina-code-embeddings -f Modelfile ` 然后 paparats install --ollama-url http://that-host:11434` 木瓜会用它的。

强制Docker Ollama在macOS上运行

paparats install --ollama-mode docker

在Apple Silicon上速度较慢（没有金属GPU），但可用于奇偶校验测试或没有金属GPU的笔记本电脑 酿造。

脚本/CI

paparats install --non-interactive --force

在任何提示下失败； --force 回答Y以编写覆盖和迁移提示。

______________________________________________________________________

从v1安装迁移

当 paparats install 找到遗产 ~/.paparats/docker-compose.yml （来自 旧的每个项目流程，没有 paparats-indexer 服务），它只打印一个屏幕 在拆除遗留堆栈之前，请注意迁移通知和询问。

幸存下来的： Qdrant集合、SQLite元数据、索引器存储库和任何 .paparats.yml 存储库中的文件（这些文件仍然优先于 projects.yml 覆盖）。

已删除的内容： 遗产 docker-compose.yml 和 .env。它们在以下时间重新生成 新模式下的地点。

无需重新索引 --数据卷在新版本中以相同的名称引用 组成。添加您的项目 paparats add 它们再次出现在 paparats list 随着 他们现有的块。

如果您的安装早于 paparats-indexer.yml → projects.yml 重命名 安装程序在第一次运行时将文件迁移到位，并打印一行通知。 索引器还会读取旧名称作为回退，因此如果您 在重新运行之前展开索引器 paparats install.

通过 --force 跳过脚本中的迁移提示。

______________________________________________________________________

支持代理设置

对于使用现有Paparats服务器的机器人和支持团队——没有Docker，也没有 奥拉玛需要站在这一边。

# 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

安装程序验证服务器是否可访问，然后连接Cursor MCP (~/.cursor/mcp.json)和克劳德代码MCP(~/.claude/mcp.json)支持 终点。工具可在 /support/mcp: search_code, get_chunk, find_usages, list_projects, health_check, get_chunk_meta, search_changes, explain_feature, recent_changes, impact_analysis，加上中描述的分析工具 可观测性 在......下面

______________________________________________________________________

运作原理

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

索引管道

在每个索引器周期（cron驱动，按需通过 paparats add，或由以下因素触发 索引器的chokidar文件监视器），作用域中的每个文件都流经此管道：

 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 Ollama
 │                  │  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
 └─────────────────┘

步骤5的符号提取器仅发出 模块级 定义——本地声明 函数体内部、回调参数和钩子闭包不在图中，因为 无论如何，它们都不能从另一个块中寻址。

搜索流程

人工智能助手通过MCP查询→ 服务器检测查询类型（nl2code/code2code/techqa）→ 扩展查询（缩写、大小写变体、复数）→ 针对Qdrant并行搜索所有变体→ 按最大分数合并的结果→ 仅返回具有置信度得分和符号信息的相关块。

观看

indexer容器通过chokidar监视装入其中的项目，并进行去抖动 （默认为1秒）。更改时，只有受影响的文件会重新进入管道。内容不变 由于内容哈希缓存，它永远不会被重新嵌入。索引器也会进行热重新加载 ~/.paparats/projects.yml 本身：元数据只编辑重新索引； 添加/删除本地路径项目会通过CLI触发堆栈重启。

______________________________________________________________________

主要特点

更好的搜索质量

任务特定嵌入 --Jina代码嵌入支持3种查询类型（nl2code、code2code、techqa），具有不同的前缀，以获得更好的相关性：

• "find authentication middleware" → nl2code 前缀（自然语言→ code)
• "function validateUser(req, res)" → code2code 前缀（代码→ 类似代码）
• "how does OAuth work in this app?" → techqa 前缀（技术问题）

查询扩展 --每次搜索都会在服务器端生成2-3个变体：

• 缩写： auth ↔ authentication, db ↔ database
• 病例变体： userAuth → user_auth → UserAuth
• 复数： users → user, dependencies → dependency
• 填料移除： "how does auth work" → "auth"

所有变体并行搜索，结果按最大分数合并。

置信度分数 --每个结果都包括一个百分比分数（≥60%高，40-60%偏，\ --radius_lines 50 → 扩展周围| | **管理项目** | list_projects 和 delete_project` 用于指数卫生|

支持团队

通过连接 支持端点 (/support/mcp):

支持聊天机器人示例：

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()
   → returns who last modified it, when, linked tickets
3. Bot synthesizes response in plain language with ticket references

______________________________________________________________________

配置

Paparats使用两个配置文件。两者都是可选的——默认值适用于常见情况。

~/.paparats/projects.yml --全球项目列表

住在你的仓库外。由...编辑 paparats add / paparats remove 或手工通过 paparats edit projects.每个条目都有 path: （本地绑定挂载）或 url: （由索引器克隆的远程git），永远不要两者兼而有之。

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: git@github.com:acme/billing.git
    name: billing # override the auto-derived name
    group: prod

索引器热重新加载此文件。添加/删除 本地路径 条目会导致CLI 重启堆栈，以便Docker获取新的绑定挂载；元数据只编辑重新索引 到位。

.paparats.yml 在您的仓库中——每个项目覆盖

在项目根目录下放置一个，以覆盖全局文件中的任何内容。

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 Ollama 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

在回购中 .paparats.yml 总是赢 projects.ymlCLI从不 覆盖它。

群组

A. 群组 是Qdrant系列(paparats_).多个项目可以共享一个 组，以实现跨项目搜索；每个项目都像一个 project: 现场 块有效载荷。默认情况下 group 默认为项目名称（一个项目，一个 收集）。设置相同 group: 对多个条目进行合并。

每个区块的Git历史记录

当 metadata.git.enabled: true （默认），索引器将每个块映射到提交 使用diff-hunk重叠触及其线条范围。从提交中提取票证 消息使用 metadata.git.ticketPatterns （内置：Jira PROJ-123，GitHub #42, 交叉回购 org/repo#99).通过MCP工具进行表面处理 get_chunk_meta, search_changes, recent_changes, explain_feature非致命：非git项目索引正常。

______________________________________________________________________

MCP工具参考

Paparats为模型上下文协议提供服务 两个独立的端点，每一个都有其 自己的工具集和系统说明。

编码端点(/mcp)

适用于使用Claude Code、Cursor等的开发人员。重点：搜索代码，阅读代码块，关注 跨块符号图，管理项目。

支持端点(/support/mcp)

适用于没有直接代码访问权限的支持团队和机器人。重点：特征解释， 变更历史、成本报告——所有这些都是用通俗易懂的语言。

典型工作流程

向下钻取（编码剂）：

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

单次呼叫（支持代理）：

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

______________________________________________________________________

连接MCP

paparats install 已连接光标(~/.cursor/mcp.json)克劳德密码 (~/.claude/mcp.json)to http://localhost:9876/mcp。以下各节为 手动设置或添加 支持 端点位于默认编码端点旁边。

光标

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （项目）：

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

支持用例（功能说明、变更历史、影响分析）：

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

更改配置后重新启动Cursor。

克劳德代码

# 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

或添加到 .mcp.json 在项目根目录中：

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

验证

• paparats status --检查堆栈是否已打开
• 编码端点 (/mcp): search_code, get_chunk, find_usages,

list_projects, delete_project, health_check

• 支持端点 (/support/mcp): search_code, get_chunk, find_usages,

health_check, list_projects，再加上支持特定的工具 get_chunk_meta, search_changes, explain_feature, recent_changes, impact_analysis，以及 中列出的分析工具 可观测性 (token_savings_report, top_queries, slowest_searches, cross_project_share, retry_rate, failed_chunks)

• 问AI： _“在此工作区中搜索身份验证中间件”_

______________________________________________________________________

CLI命令

paparats install [flags]                Bootstrap or reconfigure the global stack.
paparats add 
 [flags]     Add a project (local path or git URL/shorthand).
paparats list [--json] [--group g]      Show indexed projects with status from the indexer.
paparats remove  [--yes]          Remove a project — deletes Qdrant + SQLite data.

paparats start [--logs]                 Start the Docker stack (with `--logs` follows them).
paparats stop                           Stop the stack (preserves data volumes).
paparats restart                        Recreate containers (applies new compose changes).
paparats edit compose|projects          Open the file in $EDITOR; on save, validate +
                                          regenerate compose + restart + reindex (projects).

paparats search  [flags]         Semantic search from the terminal.
paparats status                         Stack health: Docker, Ollama, server, indexer.
paparats groups [--json]                List groups and their projects.
paparats doctor                         Diagnostic checks (Docker, Ollama, ports, configs).
paparats update                         Update CLI from npm + pull latest Docker images.

每个项目的遗留命令(paparats init, paparats index, paparats watch)都是 已完成--添加项目现在已完成 paparats add，索引器中的索引是自动的 容器，看是 chokidar 索引器内的监视器。

通用旗帜

paparats install

• --ollama-mode --强制Ollama模式（默认：macOS上的原生模式，Linux上的docker模式）
• --ollama-url --外部Ollama；跳过原生和docker Ollama
• --qdrant-url --外部Qdrant；跳过Qdrant容器
• --qdrant-api-key --用于经过身份验证的Qdrant（例如Qdrant Cloud）；写信给 ~/.paparats/.env
• --mode support --仅连接MCP客户端，无Docker堆栈
• --server --支持模式的服务器URL（默认值： http://localhost:9876)
• --force --跳过覆盖/迁移提示
• --non-interactive --在任何提示下都失败，而不是问
• -v, --verbose --流式Docker输出

paparats add

• --name --重写自动派生的项目名称（路径/repo的基名）
• --group --替代组（默认值：项目名称）
• --language --覆盖语言（默认：自动检测）
• --no-restart --跳过Docker重启以添加本地路径（在脚本中很有用）
• --no-reindex --跳过每个项目的重新索引触发器
• --force --在重新索引之前删除项目的现有块（破坏性，在模式/配置更改后使用）

paparats remove

• --yes --跳过确认提示

paparats search

• -n, --limit --最大结果（默认值：5）
• -p, --project --按项目筛选
• -g, --group --限制到一个组
• --json --机器可读输出

环境覆盖

______________________________________________________________________

监控

Paparats公开了Prometheus指标以实现操作可见性。通过设置选择加入 PAPARATS_METRICS=true 在服务器环境中：

# In ~/.paparats/docker-compose.yml, under paparats service:
environment:
  PAPARATS_METRICS: 'true'

指标端点

curl http://localhost:9876/metrics

关键指标

Prometheus抓取配置

scrape_configs:
  - job_name: paparats
    scrape_interval: 15s
    static_configs:
      - targets: ['localhost:9876']

查询缓存

搜索结果缓存在内存中（LRU，默认1000个条目，5分钟TTL）。文件更改时，缓存会自动失效。通过环境变量进行配置：

• QUERY_CACHE_MAX_ENTRIES --最大缓存查询数（默认值：1000）
• QUERY_CACHE_TTL_MS --TTL（毫秒）（默认值：300000）

缓存统计信息包含在 GET /api/stats 在...之下 queryCache 现场。

______________________________________________________________________

分析和可观察性

Paparats带有三个协同工作的可观察性层：

1. 普罗米修斯 (PAPARATS_METRICS=true，见上文）--刮擦 /metrics.
2. 本地SQLite分析存储 在 ~/.paparats/analytics.db （默认ON）--原始搜索/工具/索引事件。六个MCP工具直接查询： token_savings_report, top_queries, cross_project_share, retry_rate, slowest_searches, failed_chunks.
3. 开放遥测 (PAPARATS_OTEL_ENABLED=true + OTEL_EXPORTER_OTLP_ENDPOINT)--每次搜索、MCP工具调用、嵌入、索引运行、分块错误的跨度。适用于Tempo、Jaeger、Honeycomb、Datadog、Grafana Cloud——任何支持OTLP/HTTP的东西。

身份归因

客户端（IDE插件、CLI）可以设置 X-Paparats-User, X-Paparats-Session, X-Paparats-Client, X-Paparats-Anchor-Project 标题。的标题名称 user 可通过以下方式配置 PAPARATS_IDENTITY_HEADER （默认值 X-Paparats-User).缺少标题→ 事件归因于 anonymous。没有加密验证——这是为了归因，而不是访问控制。

GET /api/stats 回显解析的身份，可用于验证报头传播：

curl -H 'X-Paparats-User: alice' http://localhost:9876/api/stats | jq .identity

代币节省估算器

三个级别，根据查询时的原始事件计算：

• 天真的基线 --如果模型为每个结果提取整个文件，它会读取什么。
• 仅搜索 --实际返回的令牌 search_code.
• 实际消费 --客户端随后通过获取的令牌 get_chunk最诚实的信号，因为它忽略了从未使用过的嘈杂结果。

跑 token_savings_report 从连接到的任何MCP客户端 /support/mcp.

跨项目噪声

当客户通过时 X-Paparats-Anchor-Project （或在搜索调用中指定单个项目），来自的结果份额 _其他_ 记录同一组中的项目。使用 cross_project_share 查看每个用户的组索引有多嘈杂。

索引器管道可见性

failed_chunks 聚合AST解析失败、正则表达式回退、零块文件和二进制跳过。 slowest_searches 按延迟对单个搜索进行排名。

配置矩阵

PII指南

• 默认情况下，文件路径和查询文本存储在本地。对于路径可能泄露敏感信息的共享部署，请设置 PAPARATS_LOG_RESULT_FILES=false 和 PAPARATS_LOG_QUERY_TEXT=false.
• 默认情况下，OTel跨度从不携带完整的查询文本——仅 paparats.query.hash 长度。

______________________________________________________________________

建筑

paparats-mcp/
├── packages/
│   ├── server/          # MCP server (Docker image: ibaz/paparats-server)
│   │   ├── src/
│   │   │   ├── lib.ts                # Public library exports (for programmatic use)
│   │   │   ├── index.ts              # HTTP server bootstrap + graceful shutdown
│   │   │   ├── app.ts                # Express app + HTTP API routes
│   │   │   ├── indexer.ts            # Group-aware indexing, single-parse chunkFile()
│   │   │   ├── searcher.ts           # Search with query expansion, cache, metrics
│   │   │   ├── query-expansion.ts    # Abbreviation, case, plural expansion
│   │   │   ├── task-prefixes.ts      # Jina task prefix detection
│   │   │   ├── query-cache.ts        # In-memory LRU search result cache
│   │   │   ├── metrics.ts            # Prometheus metrics (opt-in)
│   │   │   ├── ast-chunker.ts        # AST-based code chunking (tree-sitter, primary strategy)
│   │   │   ├── chunker.ts            # Regex-based code chunking (fallback for unsupported languages)
│   │   │   ├── ast-symbol-extractor.ts # AST-based symbol extraction (module-level only, 11 languages)
│   │   │   ├── ast-queries.ts        # Tree-sitter S-expression queries per language
│   │   │   ├── tree-sitter-parser.ts # WASM tree-sitter manager
│   │   │   ├── symbol-graph.ts       # Cross-chunk symbol edges (calls/called_by/refs)
│   │   │   ├── embeddings.ts         # Ollama provider + SQLite cache
│   │   │   ├── config.ts             # .paparats.yml reader + validation
│   │   │   ├── metadata.ts           # Tag resolution + auto-detection
│   │   │   ├── metadata-db.ts        # SQLite store for git commits + tickets + symbol edges
│   │   │   ├── git-metadata.ts       # Git history extraction + chunk mapping
│   │   │   ├── ticket-extractor.ts   # Jira/GitHub/custom ticket parsing
│   │   │   ├── mcp-handler.ts        # MCP protocol — dual-mode (coding /mcp + support /support/mcp)
│   │   │   ├── watcher.ts            # File watcher (chokidar)
│   │   │   └── types.ts              # Shared types
│   │   └── Dockerfile
│   ├── indexer/         # Automated repo indexer (Docker image: ibaz/paparats-indexer)
│   │   ├── src/
│   │   │   ├── index.ts              # Entry: Express mini-server + cron scheduler
│   │   │   ├── config-loader.ts      # projects.yml parser + per-repo overrides
│   │   │   ├── config-watcher.ts     # chokidar watcher for hot-reloading the project list
│   │   │   ├── repo-manager.ts       # parseReposEnv(), cloneOrPull() using simple-git
│   │   │   ├── scheduler.ts          # node-cron wrapper
│   │   │   └── types.ts              # IndexerConfig, RepoConfig, RepoOverrides, IndexerFileConfig
│   │   └── Dockerfile
│   ├── ollama/          # Custom Ollama with pre-baked model (Docker image: ibaz/paparats-ollama)
│   │   └── Dockerfile
│   ├── cli/             # CLI tool (npm package: @paparats/cli)
│   │   └── src/
│   │       ├── index.ts                    # Commander entry
│   │       ├── docker-compose-generator.ts # Programmatic YAML generation
│   │       ├── projects-yml.ts             # projects.yml + install.json read/write
│   │       └── commands/                   # install, projects (add/remove/list), lifecycle, edit, etc.
│   └── shared/          # Shared utilities (npm package: @paparats/shared)
│       └── src/
│           ├── path-validation.ts    # Path validation
│           ├── gitignore.ts          # Gitignore parsing
│           ├── exclude-patterns.ts   # Glob exclude normalization
│           └── language-excludes.ts  # Language-specific exclude defaults
└── examples/
    └── paparats.yml.*   # Config examples per language

______________________________________________________________________

堆栈

• Qdrant --矢量数据库（每组1个集合 paparats_ 前缀、余弦相似度、有效载荷过滤）
• 奥拉玛 --通过具有特定任务前缀的Jina代码嵌入1.5B进行本地嵌入
• SQLite --嵌入缓存(~/.paparats/cache/embeddings.db)+git元数据+符号边存储(~/.paparats/metadata.db)
• 主控程序 --模型上下文协议（SSE用于游标，可流式HTTP用于克劳德代码）。双端点： /mcp （编码）和 /support/mcp （支持）
• TypeScript 带有Yarn工作区的monorepo

______________________________________________________________________

集成示例

支持聊天机器人

使用狗仔队作为产品支持机器人的知识后端。将机器人连接到 支持端点 (/support/mcp)访问 explain_feature, recent_changes, find_usages，以及其他面向支持的工具：

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()
   → returns who last modified it, when, linked tickets
3. Bot synthesizes response in plain language with ticket references

CI/CD重新索引推送

索引存在于索引器容器中。为了强制CI重新索引项目， 触发索引器的HTTP端点：

name: Reindex Paparats
on:
  push:
    branches: [main]

jobs:
  reindex:
    runs-on: ubuntu-latest
    steps:
      - run: |
          curl -X POST http://your-paparats-host:9877/trigger \
            -H 'Content-Type: application/json' \
            -d '{"repos": ["your-org/your-repo"]}'

通过 "force": true 在主体中首先删除现有块（破坏性-在之后使用 模式/配置更改）。如果项目尚未完成 projects.yml，添加一次 在初始设置期间，索引器的cron+热重载将使其保持同步 向前地。

代码审查助理

结合多种工具来分析pull请求的影响：

1. explain_feature("the feature being changed")
   → understand what the code does and how it connects
2. find_usages({chunk_id: "", direction: "both"})
   → blast radius via the symbol graph
3. search_changes("related area", since="2024-01-01")
   → recent changes that might conflict or overlap

______________________________________________________________________

嵌入模型设置

违约： jinaai/jina-code-embedding-1.5b-GGUF --代码优化，1.5B参数，1536 dims，32k上下文。不在Ollama注册表中，因此我们创建了一个本地别名。

推荐： paparats install 自动执行以下操作：

• 原生模式 (--ollama-mode native，macOS上的默认设置）：下载GGUF（约1.65 GB）至 ~/.paparats/models/，创建模型文件并运行 ollama create jina-code-embeddings
• Docker模式 (--ollama-mode docker，Linux上的默认设置）：使用 ibaz/paparats-ollama 预烘焙模型的图像——零设置

手动设置：

# 1. Download GGUF
curl -L -o jina-code-embeddings-1.5b-Q8_0.gguf \
  "https://huggingface.co/jinaai/jina-code-embeddings-1.5b-GGUF/resolve/main/jina-code-embeddings-1.5b-Q8_0.gguf"

# 2. Create Modelfile
cat > Modelfile 
Notes

1. Bloop于2025年1月2日存档
1. 增强上下文引擎在本地索引，但将向量存储在云中
1. 带有任务特定前缀（nl2code、code2code、techqa）的Jina代码嵌入1.5B（1536 dims）
1. Vexify支持Ollama模型，但仅限于特定的嵌入（jina-embeddings-2-base-code、nomic嵌入文本）
1. SeaGOAT锁定为全MiniLM-L6-v2（384调光，通用）
1. 缩写、大小写变体、复数、填充词删除

______________________________________________________________________

## 代币节省指标

### 我们衡量什么（以及我们不衡量什么）

木瓜提供 **估计的** 令牌节省，以帮助您了解上下文缩减的数量级。这些是试探性的，不是精确的测量。

#### 每次搜索响应

{ "metrics": { "tokensReturned": 150, "estimatedFullFileTokens": 5000, "tokensSaved": 4850, "savingsPercent": 97 } }

|字段|计算|现实检查|
| ------------------------- | --------------------------- | -------------------------------------------------------------- |
| `tokensReturned` | `ceil(content.length / 4)` |基于实际返回的内容；/4是粗略的近似值|
| `estimatedFullFileTokens` | `ceil(endLine * 50 / 4)` | **启发式**：假设每行50个字符，从不加载实际文件|
| `tokensSaved` | `estimated - returned` | **衍生的**：两个估计值之间的差异|
| `savingsPercent` | `(saved / estimated) * 100` | **相对的**：启发式估计的百分比|

#### 累积统计数据

curl -s http://localhost:9876/api/stats | jq '.usage'

{ "searchCount": 47, "totalTokensSaved": 152340, "avgTokensSavedPerSearch": 3241 }

这些是 **估计数之和**，而不是来自真实标记器的测量标记计数。

______________________________________________________________________

## 许可证

麻省理工学院

______________________________________________________________________

## 释放（维护者）

发布由以下因素驱动 [变更集](https://github.com/changesets/changesets)版本控制+CHANGELOG生成发生在CI中； **发布到npm和标记发生在本地** 来自经过npm身份验证的维护者机器。CI中没有npm凭据。

### 编写变更集（根据PR）

yarn changeset

Pick affected packages, bump type (patch/minor/major), and write the user-facing summary.

git add .changeset/ git commit -m "chore: changeset"

所有四个包(`@paparats/shared`, `@paparats/cli`, `@paparats/server`, `@paparats/indexer`)保持在a **固定版本** --挑一个，其余的就撞到匹配。

### 释放是如何发生的

**1.CI打开发布PR（自动）。** 这 [发布工作流程](.github/workflows/release.yml) 每次推都会跑 `main`.如果待定 `.changeset/*.md` 文件存在时，它会打开（或更新）a `chore: release` PR：每个版本都有颠簸 `package.json`，按包装再生 `CHANGELOG.md` 文件夹， `server.json` 通过同步 `scripts/sync-server-json.js`，和消耗 `.changeset/*.md` 文件已删除。

**2.维护者合并发布PR。** 不再运行CI发布步骤。

**3.维护者在本地发布。** 从一个干净的结账 `main` 合并后：

git checkout main && git pull yarn release:local # or --dry-run to preview

`yarn release:local` 跑 `scripts/release-local.sh`，其中：

- 除非你在场，否则拒绝逃跑 `main`，树是干净的，你与 `origin/main`;
- 如有未决，则拒绝 `.changeset/*.md` 存在（意味着发布PR未合并）；
- 从以下位置读取新版本 `packages/cli/package.json`;
- 构建、运行 `yarn changeset publish` （跳过已发布的版本），然后标记 `vX.Y.Z` 并按下标签。

**4.下游工作流程在标签上着火。** 推动 `vX.Y.Z` 触发器  和 [publish-mcp.yml](.github/workflows/publish-mcp.yml) 自动。

### 所需凭据

|地点|内容|目的|
| ----- | ----------------------------------- | ------------------------------------------------- |
|CI| `GITHUB_TOKEN` （自动）|打开/更新 `chore: release` PR|
|本地| `npm login` （或 `NPM_TOKEN` 在env中）| `yarn changeset publish` 发表 `@paparats/*` |

没有npm令牌存在于GitHub secrets中——发布是一个手动的、经过身份验证的步骤。

### 手动/回退流程

`./scripts/release-docker.sh --push` 如果需要（例如在正式发布之间），仍然可以手动构建和推送Docker镜像。它从以下内容读取版本 `package.json`.

### Docker镜像

|图像|来源|大小|
| ----------------------- | ----------------------------- | ---------------------- |
| `ibaz/paparats-server` | `packages/server/Dockerfile` |约200 MB|
| `ibaz/paparats-indexer` | `packages/indexer/Dockerfile` |约200 MB|
| `ibaz/paparats-ollama` | `packages/ollama/Dockerfile` |约3 GB（包括型号）|

______________________________________________________________________

## 贡献

欢迎投稿！感兴趣的领域：

- 额外的语言支持（PHP、Elixir、Scala、Kotlin、Swift）
- 替代嵌入提供商（OpenAI、Cohere、通过llama.cpp的本地GGUF）
- 性能优化（分块策略、缓存驱逐）
- 代理用例（支持机器人、QA自动化、代码分析）

打开问题或拉取请求以开始。

______________________________________________________________________

## 链接

- [Jina代码嵌入](https://huggingface.co/jinaai/jina-code-embeddings-1.5b-GGUF) --嵌入模型
- [Qdrant](https://qdrant.tech) --矢量数据库
- [奥拉玛](https://ollama.com) --本地LLM运行时
- [主控程序](https://modelcontextprotocol.io) --模型上下文协议

______________________________________________________________________

**如果Paparats能帮助你更快地编码，请在代码库中添加星号！**