Universal Context Pipeline

UCP — 通用上下文管道

一个本地优先的 MCP 服务，可让大模型基于你自己的文件生成内容。

UCP 会为你机器上的文件夹建立索引——包括笔记、代码和对话导出文件——并将它们作为单个工具 search_local_context 提供给任何兼容 MCP 的客户端（Claude Desktop、Cursor、LM Studio 及其他本地 Agent 运行时）。它支持混合检索（BM25 + 向量）、感知 tree-sitter 的代码分块、完整引用，以及基于内容哈希的嵌入缓存。单个二进制文件。无遥测。无云服务。

搭配 LM Studio 中的本地模型（或通过 ucp-local ask 使用 Ollama），整个技术栈——索引、嵌入、检索和聊天模型——都能完全离线运行。无论是在飞机上、隔离设施内，还是在任何无法使用云端大模型的地方，都能正常工作。

演示

对话记忆 — 让每次过去的 Claude 聊天都能在未来的每次会话中搜索。

隔离网络 RAG — 本地 Ollama + 本地索引，零网络流量。

快速开始 — 不到一分钟即可完成安装、建立索引并提问。

适用人群

如果你是……	UCP 能为你提供……
Claude / Cursor / LM Studio 重度用户	可搜索所有过去 AI 对话的归档，并能在未来的任何会话中作为 search_local_context 工具调用。
软件工程师	通过一个 MCP 工具统一管理代码、私有文档、关联代码仓库和过去的 Claude 聊天记录，并在 Cursor 或 Claude Code 中与其原生索引器一同使用。
研究人员、作家或学者	一个 PDF 和笔记语料库，可用来提出有依据的问题，并提供行级引用，且所有内容都不会离开本机。
处于受隐私法规约束的工作流中（法律、医疗、国防、受 NDA 约束的知识产权）	一个零遥测、零云服务的 Rust 单文件程序。搭配 LM Studio，即可构建完全离线、端到端的 RAG 技术栈。
独立创始人或顾问	通过 folder_filter 实现按文件夹隔离客户端，避免将客户端 A 的上下文泄露到客户端 B 的会话中。

关于完整的受众分析、竞争对比，以及 UCP 明确致力于胜出的两个差异化优势，请参阅 POSITIONING.md。

状态

v0.1，无头模式。在 ROADMAP.md 中查看范围规划。

当前提供：

• 混合搜索：SQLite FTS5（BM25）⨉ sqlite-vec（ANN），通过倒数排名融合进行合并。
• 使用 Tree-sitter 对 Rust、Python、TypeScript/JavaScript 进行分块。Markdown 按标题分块。普通文本回退时按句子边界分块。
• 对话记忆：导入你的 Claude conversations.json 导出文件，并搜索过去的聊天记录。
• 默认启用 PII 屏蔽——包括电子邮件、OpenAI sk-、AWS 密钥、GitHub PAT 和 JWT。
• 基于内容哈希的嵌入缓存：重新索引未更改的内容时，不会调用 Ollama。
• 文件系统监视器：编辑文件后，索引会在约 500ms 内更新。

v0.1 尚未提供：

• 桌面 UI / 托盘（已延期——原始规格中包含，目前列入 ROADMAP 第 2 级及更高优先级）。
• OS 热键注入器和 HTTP 代理拦截器（已从原始规格中移除）。
• OpenAI / Anthropic 嵌入提供方（目前仅支持 Ollama）。
• Cursor 和 ChatGPT 导出格式（目前仅支持 Claude，其他格式将在后续支持）。

前置条件

UCP 需要在你的机器上安装三样东西：Rust（用于构建）、Ollama（用于生成嵌入和可选的聊天），以及 Poppler（用于可靠地提取 PDF 文本，建议安装）。

macOS

brew install ollama poppler
ollama serve &              # or use the menu-bar app
ollama pull nomic-embed-text
# Optional, for `ucp-local ask`:  ollama pull llama3.2

Linux（Debian/Ubuntu）

sudo apt install poppler-utils
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text
# Optional, for `ucp-local ask`:  ollama pull llama3.2

Linux（Fedora/RHEL）

sudo dnf install poppler-utils
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text

Windows

choco install poppler ollama   # or install each manually
ollama pull nomic-embed-text

仅从源代码构建时需要 Rust（stable，edition 2024）。如果安装预构建的 UCP 二进制文件，可以跳过 Rust 安装。

Poppler 是可选项，但建议安装。 没有它时，UCP 处理 PDF 只会使用内置的 pdf-extract；对于正文所用字体缺少 ToUnicode CMap 的 PDF，效果不佳（你会看到标题被提取出来，但正文文本消失）。如果 PATH 中有来自 Poppler 的 pdftotext，UCP 会自动改用它。

安装

关于名称的说明。 该 crate 在 crates.io 上以 ucp-local 发布，因为裸名称 ucp 已被占用。PATH 中的二进制文件名称也是 ucp-local（这是你在命令行中输入的名称），库的导入方式为 use ucp_local::...。

从 crates.io 安装

cargo install ucp-local
# Puts the `ucp-local` binary on your PATH

从源代码安装

git clone <repo-url> ucp-local
cd ucp-local
cargo build --release
# Binary at target/release/ucp-local
cargo install --path .   # optional, to put `ucp-local` on your PATH

用法

# Index one folder
ucp-local index ~/Documents/notes

# Index multiple folders into the same store
ucp-local index ~/Documents/notes ~/code/my-project ~/research

# Watch a folder and re-index on changes (initial pass runs first)
ucp-local watch ~/code/my-project

# Clear the index — soft (keeps the embedding cache so re-index is fast)
ucp-local clear

# Clear only one folder's chunks
ucp-local clear ~/Documents/notes

# Hard reset — also wipes the embedding cache, forces re-embed on next index
ucp-local clear --hard --yes

# Ingest a Claude conversations.json export
ucp-local ingest-conversations ~/Downloads/claude-export/conversations.json

# Show config + index status
ucp-local status

# Run the MCP server over stdio (this is what MCP clients launch)
ucp-local serve

# Search the index from the terminal (no LLM) — best for debugging "did indexing actually capture this?"
ucp-local search "your query here"
ucp-local search "rate limiting" --folder ~/code/my-project --limit 10

# Ask a question — runs search internally, then a local chat model answers with citations
ucp-local ask "what does the rate limiter do when a token bucket runs out?"
ucp-local ask "summarize my Q3 plan" --model qwen2.5

配置 MCP 客户端

UCP 通过 stdio 使用 MCP，因此任何可以启动 MCP 服务的客户端都能使用它。serve 命令相同，只需为不同客户端使用不同的配置文件。

Claude Desktop

在 macOS 上将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ucp-local": {
      "command": "/full/path/to/ucp-local",
      "args": ["serve"]
    }
  }
}

重启 Claude Desktop。届时即可使用 search_local_context 工具——询问与已索引文件相关的问题，它会在回答中引用这些文件。

Cursor

Cursor 从 ~/.cursor/mcp.json（或项目级 .cursor/mcp.json）读取 MCP 服务：

{
  "mcpServers": {
    "ucp-local": {
      "command": "/full/path/to/ucp-local",
      "args": ["serve"]
    }
  }
}

重新加载 Cursor。聊天侧边栏会将 search_local_context 显示为工具，可用于让 Agent 参考代码库和文档，尤其是 Cursor 自带的 @codebase 索引器无法访问的内容（私密笔记、对话历史、同级代码库）。

LM Studio（完全离线）

LM Studio 0.3.17+ 支持 MCP。打开聊天设置，找到 MCP servers 部分，然后添加：

{
  "mcpServers": {
    "ucp-local": {
      "command": "/full/path/to/ucp-local",
      "args": ["serve"]
    }
  }
}

将 UCP 与你在 LM Studio 中下载的任一本地模型（Llama、Qwen、Mistral 等）配合使用。这样一来，索引、嵌入、检索和聊天模型都在同一台机器上运行——无需云服务或网络——而大模型仍可调用 search_local_context，根据你的文件生成回答。

其他 MCP 客户端

任何遵循 MCP 规范的客户端（Zed、Continue.dev、Goose、自定义 Agent SDK 应用等）都采用相同的 command + args 格式。如果你的客户端需要 JSON-RPC stdio 服务，只需将其指向 ucp-local serve 即可。

配置

~/.config/ucp/config.toml（或平台对应路径——ucp-local status 会打印解析后的路径）。所有字段均为可选；默认值如下：

[ollama]
host = "http://localhost:11434"
embedding_model = "nomic-embed-text"

[chunking]
max_tokens = 512
overlap_sentences = 1

索引内容

按扩展名索引：md、markdown、txt、rs、py、ts、tsx、js、jsx、mjs、go、pdf。

**PDF：**文本通过 pdf-extract 提取，并按散文分块。适用于数字生成的 PDF（论文、文档、导出的笔记）。对于扫描件等仅包含图像的 PDF，效果不佳——这类文件需要 OCR（v0.2+）。引用中的行号对应提取出的纯文本，而非 PDF 页码；支持基于页码的引用已列入 v0.2 计划。

跳过的目录：.git、.idea、.vscode、target、node_modules、__pycache__、.venv、venv、dist、build、.next、.nuxt、coverage、.pytest_cache、.mypy_cache。点文件会被跳过。

架构

模块	作用
ingestion	遮蔽处理 + 按格式分块（散文 / Markdown / 使用 tree-sitter 的代码）+ 分发器
storage	rusqlite + sqlite-vec + FTS5；通过 RRF 进行混合搜索
embeddings	OllamaClient + 通过 EmbeddingCache::hash 实现的内容哈希缓存
indexer	遍历 + 读取 + 分块 + 嵌入 + 插入；支持单文件和批量分块路径
watcher	基于 notify 的防抖重新索引
mcp	JSON-RPC 2.0 stdio 服务，提供一个工具：search_local_context

请参阅 CLAUDE.md 中面向开发者的架构摘要，以及 Universal Context Pipeline Specification.md 中的原始设计文档（现已缩小适用范围）。

开发

cargo test                    # full test suite
cargo test --lib ingestion    # one module
cargo run -- index <path>     # iterate against the dev build
RUST_LOG=ucp_local=info cargo run -- watch <path>   # verbose

更新日志

发布历史和说明见 CHANGELOG.md。当前已发布版本为 0.1.0（crates.io）。

许可证

采用 Apache-2.0 许可证。