Universal Context Pipeline

UCP — Universal Context Pipeline

Um servidor MCP local-first que fundamenta LLMs em seus próprios arquivos.

O UCP indexa pastas na sua máquina — notas, código, exportações de conversas — e as expõe a qualquer cliente compatível com MCP (Claude Desktop, Cursor, LM Studio e outros runtimes de agentes locais) como uma única ferramenta: search_local_context. Recuperação híbrida (BM25 + vetorial), chunking de código com ciência de tree-sitter, citações completas, cache de embeddings por hash de conteúdo. Binário único. Sem telemetria. Sem nuvem.

Combinado com um modelo local no LM Studio (ou Ollama via ucp-local ask), toda a pilha — indexação, embeddings, recuperação e o modelo de chat — roda totalmente offline. Funciona em um avião, em uma instalação com isolamento de ar ou em qualquer lugar onde um LLM em nuvem não seja uma opção.

Demonstrações

Memória de conversas — torne cada chat passado do Claude pesquisável em todas as sessões futuras.

RAG com isolamento de ar — Ollama local + índice local, zero tráfego de rede.

Início rápido — instale, indexe, pergunte, em menos de um minuto.

Para quem é isso?

Se você é…	O UCP oferece…
Um usuário avançado de Claude / Cursor / LM Studio	Um arquivo pesquisável de toda conversa de IA passada, chamável de qualquer sessão futura como a ferramenta search_local_context.
Um engenheiro de software	Código + documentos privados + repositórios irmãos + chats passados do Claude unificados sob uma ferramenta MCP — exibidos dentro do Cursor ou Claude Code junto com seus indexadores nativos.
Um pesquisador, escritor ou acadêmico	Um corpus de PDFs + notas sobre o qual você pode fazer perguntas fundamentadas, com citações em nível de linha, sem que nada saia da máquina.
Em um fluxo de trabalho regulado por privacidade (jurídico, médico, defesa, IP sujeito a NDA)	Um único binário Rust com zero telemetria e zero nuvem. Combine com LM Studio para uma pilha RAG totalmente offline, de ponta a ponta.
Um fundador solo ou consultor	Isolamento de cliente por pasta via folder_filter — sem risco de vazar o contexto do cliente A para a sessão do cliente B.

Análise completa de público, comparação competitiva e as duas vantagens que o UCP foi explicitamente construído para vencer: veja POSITIONING.md.

Status

v0.1, sem interface gráfica. Acompanhe o escopo em ROADMAP.md.

O que está incluído:

• Busca híbrida: SQLite FTS5 (BM25) ⨉ sqlite-vec (ANN) mesclados via fusão de rank recíproco.
• Chunking com tree-sitter para Rust, Python, TypeScript/JavaScript. Markdown ciente de cabeçalhos. Fallback de prosa com limites de frase.
• Memória de conversas: ingira sua exportação do Claude conversations.json e pesquise em chats passados.
• Mascaramento de PII ativado por padrão — e-mail, sk- da OpenAI, chaves AWS, PATs do GitHub, JWT.
• Cache de embeddings por hash de conteúdo: reindexar conteúdo inalterado faz zero chamadas ao Ollama.
• Observador de sistema de arquivos: edite um arquivo, o índice atualiza em ~500ms.

O que não está na v0.1:

• Interface gráfica / bandeja (adiado — estava na especificação original, agora no nível 2+ do ROADMAP).
• Injetor de atalho do SO e interceptador de proxy HTTP (cortados da especificação original).
• Provedores de embeddings OpenAI / Anthropic (apenas Ollama por enquanto).
• Formatos de exportação do Cursor e ChatGPT (apenas Claude; outros depois).

Pré-requisitos

O UCP precisa de três coisas na sua máquina: Rust (para compilar), Ollama (para embeddings e opcionalmente chat) e Poppler (para extração robusta de texto de PDFs — recomendado).

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 (estável, edição 2024) é necessário apenas para compilar a partir do código-fonte. Se você instalar um binário UCP pré-compilado, pule a instalação do Rust.

Poppler é opcional, mas recomendado. Sem ele, o UCP usa apenas o pdf-extract incluído para PDFs, que tem dificuldades com PDFs cujas fontes do corpo não possuem um CMap ToUnicode (você verá cabeçalhos extraídos, mas o texto do corpo desaparece). Com pdftotext do Poppler no PATH, o UCP faz fallback automaticamente para ele.

Instalação

Nota sobre o nome. O crate é publicado como ucp-local no crates.io — o nome simples ucp já estava ocupado. O binário no seu PATH também é ucp-local (é isso que você digita na linha de comando), e a biblioteca é importada como use ucp_local::....

Do crates.io

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

Do código-fonte

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

Uso

# 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

Conecte um cliente MCP

O UCP fala MCP via stdio, então qualquer cliente que inicie servidores MCP pode usá-lo. Mesmo comando serve, arquivo de configuração diferente por cliente.

Claude Desktop

Adicione a ~/Library/Application Support/Claude/claude_desktop_config.json no macOS (%APPDATA%\Claude\claude_desktop_config.json no Windows):

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

Reinicie o Claude Desktop. A ferramenta search_local_context estará disponível — faça uma pergunta fundamentada nos seus arquivos indexados e ela citará inline.

Cursor

O Cursor lê servidores MCP de ~/.cursor/mcp.json (ou .cursor/mcp.json por projeto):

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

Recarregue o Cursor. A barra lateral de chat exibirá search_local_context como uma ferramenta — útil para fundamentar o agente em repositórios e documentos que o indexador @codebase do próprio Cursor não alcança (notas privadas, histórico de conversas, repositórios irmãos).

LM Studio (totalmente offline)

O LM Studio 0.3.17+ suporta MCP. Abra as configurações do chat, encontre a seção Servidores MCP e adicione:

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

Combine o UCP com qualquer modelo local que você baixou no LM Studio (Llama, Qwen, Mistral, etc.). Agora sua indexação, embeddings, recuperação e modelo de chat rodam todos na mesma máquina — sem nuvem, sem rede — e o LLM ainda pode chamar search_local_context para fundamentar suas respostas nos seus arquivos.

Outros clientes MCP

Qualquer cliente que siga a especificação MCP (Zed, Continue.dev, Goose, aplicativos personalizados com Agent SDK, etc.) aceita o mesmo formato command + args. Se o seu cliente espera um servidor stdio JSON-RPC, aponte-o para ucp-local serve e pronto.

Configuração

~/.config/ucp/config.toml (ou o equivalente da plataforma — ucp-local status imprime o caminho resolvido). Todos os campos são opcionais; padrões mostrados:

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

[chunking]
max_tokens = 512
overlap_sentences = 1

O que é indexado

Por extensão: md, markdown, txt, rs, py, ts, tsx, js, jsx, mjs, go, pdf.

PDFs: o texto é extraído via pdf-extract e dividido em chunks como prosa. Funciona bem para PDFs gerados digitalmente (artigos, documentos, notas exportadas). Falha em PDFs escaneados apenas com imagem — esses precisam de OCR (v0.2+). Os números de linha das citações referenciam o texto simples extraído, não os números de página do PDF; citações cientes de página estão na lista da v0.2.

Diretórios ignorados: .git, .idea, .vscode, target, node_modules, __pycache__, .venv, venv, dist, build, .next, .nuxt, coverage, .pytest_cache, .mypy_cache. Arquivos ocultos são ignorados.

Arquitetura

Módulo	Função
ingestion	Mascaramento + chunkers por formato (prosa / markdown / código via tree-sitter) + despachante
storage	rusqlite + sqlite-vec + FTS5; busca híbrida via RRF
embeddings	OllamaClient + cache por hash de conteúdo via EmbeddingCache::hash
indexer	Caminhar + ler + chunk + embed + inserir; caminhos de arquivo único e chunk em lote
watcher	Reindexação com debounce baseada em notify
mcp	Servidor stdio JSON-RPC 2.0, uma ferramenta: search_local_context

Veja CLAUDE.md para o resumo da arquitetura voltado a desenvolvedores, e Universal Context Pipeline Specification.md para o documento de design original (agora com escopo mais restrito).

Desenvolvimento

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

O histórico de versões e notas está em CHANGELOG.md. A versão publicada atual é 0.1.0 (crates.io).

Licença

Sob Apache-2.0.