Context-Pipe

Uma camada de orquestração de alto desempenho e independente de linguagem que traz a Filosofia Unix para a janela de contexto da IA.

GitHub

Experimente este MCPPatrocinado

Documentação

⛓️ Context-Pipe

O Padrão Universal para Engenharia de Contexto.

context-pipe é uma camada de orquestração de alto desempenho diretamente inspirada no piping de terminais Unix — a mesma filosofia que tornou o cmd1 | cmd2 | cmd3 o primitivo de composição mais durável da computação. Assim como o terminal encadeia processos por meio de fluxos de bytes stdin/stdout, o Context-Pipe encadeia chamadas de ferramentas de IA por meio de fluxos de contexto: cada nó faz uma coisa, passa sua saída para o próximo, e o LLM vê apenas o sinal final e refinado.

Isto não é uma metáfora — é uma extensão literal. O Context-Pipe suporta tanto piping MCP (encadeando chamadas de ferramentas MCP por meio do orquestrador) quanto piping de terminal (qualquer binário, comando de shell ou script que leia stdin e escreva stdout é um nó válido). Os dois modos se compõem livremente em uma única definição de pipe. E por meio do CLI mcp-pipe, ele estende o próprio terminal: o subcomando mcp-pipe tool torna qualquer servidor MCP — context-mode, serena, GitHub, Firecrawl, ou qualquer servidor registrado em pipes.json — diretamente pipeable a partir do shell, carregando sob demanda, sem scripts de wrapper e sem necessidade de IDE:

cat error.log | mcp-pipe tool semantic-sift sift_logs | rg "CRITICAL"
curl -s https://example.com | mcp-pipe tool firecrawl scrape | mcp-pipe run semantic-refinery

Hoje, o mcp-pipe run <pipe> já dá ao terminal acesso de primeira classe a qualquer pipe nomeado definido em pipes.json, compondo binários de terminal por meio do mesmo orquestrador usado pela IDE.

🚀 A Visão

O agente de IA tem um problema fundamental de infraestrutura: toda chamada de ferramenta retorna saída bruta e não filtrada diretamente para a janela de contexto. Logs chegam com timestamps. Resultados de busca chegam com texto padronizado. A análise de 40KB do Agente A é passada verbatim para o Agente B. A janela de contexto enche. O sinal se afoga no ruído. O LLM degrada.

O context-pipe resolve isso na camada de infraestrutura — antes que o LLM veja qualquer coisa.

Na filosofia do Studio of Two, construímos Sistemas, não Remendos. Um remendo seria um filtro personalizado por ferramenta. Um sistema é um protocolo universal: qualquer ferramenta que leia stdin e escreva stdout torna-se um nó. Qualquer sequência de nós torna-se um pipe. Qualquer pipe é nomeado, versionado, auditado e reutilizável em todos os projetos e frameworks de agentes.

O resultado é uma cadeia de suprimentos de contexto: os dados entram crus, passam por uma sequência de refinarias (normalizar → filtrar → comprimir → destilar), e chegam ao LLM como conteúdo denso e de alto sinal. Cada byte economizado é contabilizado no Balanço de Contexto. Cada execução de pipe é rastreável. Cada handoff A2A é protegido.

Isto não é um wrapper em torno do semantic-sift. É a camada de orquestração que torna qualquer refinaria componível, observável e pronta para produção. Um nó pode ser um binário, um comando de shell, um script Python ou uma ferramenta MCP completa (Figma, GitHub, context-mode, ou qualquer servidor registrado em pipes.json). Se lê stdin e escreve stdout, pertence ao pipe.

Exemplo — rastreie a web, pesquise, salve e envie:

trigger: tool:web_search | tool:web_fetch

[URL]
    → firecrawl/scrape             # MCP node: fetch live page as clean text     ~18,400 tokens
    → markitdown                   # binary node: convert to structured Markdown     ~16,200 tokens
    → rg 'security|vulnerability'  # shell node: surface only relevant sections      ~3,100 tokens
    → prettier --parser markdown   # shell node: normalize formatting                ~3,050 tokens
    → semantic-sift-cli doc        # binary node: distil to high-signal summary        ~420 tokens
          ↳ tee → research.md      # T-pipe: save raw distilled copy to disk
    → security-auditor             # script node: project-specific logic               ~380 tokens
    → github/create_issue          # MCP node: open a tracked issue with findings

Context Balance Sheet (illustrative)
  in:  18,400 tokens  →  out: 380 tokens  —  97.9% saved  ·  1.2s total

Cada nó é um subprocesso real. O T-pipe salva uma cópia bruta em qualquer ponto sem interromper a cadeia. O LLM recebe apenas o que importa — e cada byte de entrada, byte de saída e milissegundo de latência é registrado automaticamente no Balanço de Contexto.

🛠️ Componentes Principais

1. O Protocolo Context-Pipe (CPP)

Um padrão agnóstico de linguagem com uma regra: um nó lê stdin, transforma o conteúdo e escreve em stdout. Qualquer binário, comando de shell, script Python ou ferramenta MCP que honre este contrato é um nó válido. O protocolo é definido em doc/CONTEXT_PIPE_PROTOCOL.md e é deliberadamente simples — sem SDKs, sem registro, sem acoplamento de framework.

2. A Espinha de Orquestração (`orchestrator.py`)

O motor de execução que encadeia nós em pipes. Executa cada nó como um subprocesso real do SO com shell=False aplicado (sem superfície de injeção). Recursos: guarda de timeout por nó (PIPE_NODE_TIMEOUT_MS), divisão de fluxo T-Pipe (salva entrada bruta em disco antes de um nó processá-la) e contabilidade completa de rastreamento (tamanho de entrada/saída + latência por nó).

3. O Quadro de Distribuição Universal (`pipes.json` + mapeamentos)

Roteamento orientado a dados que resolve o pipe ideal automaticamente com base em três tipos de gatilho: nome da ferramenta (tool:regex), tamanho do payload (size:>N) e fallback padrão. As definições de pipe vivem em pipes.json (nível de projeto) e opcionalmente ~/.mcp-pipe.json (global, mesclado com precedência local). Nenhuma alteração de código é necessária para adicionar, modificar ou re-rotear pipes.

4. A Superfície MCP (`server.py` + CLI `mcp-pipe`)

Oito ferramentas MCP expõem cada capacidade diretamente aos assistentes de IA: pipe_run, pipe_run_dynamic, pipe_read_file, pipe_analyze_file, pipe_list_shadow_tools, pipe_agent_handoff, get_pipe_stats e pipe_onboard. O CLI mcp-pipe espelha a mesma superfície para fluxos de trabalho primeiro-no-terminal — sem necessidade de IDE. Descoberta de Ferramentas Sombra (pipe_list_shadow_tools) dá ao agente um manifesto de capacidades ao vivo combinando pipes configurados e ferramentas PATH selecionadas (jq, rg, markitdown, pandoc…).

5. Interceptadores Subconscientes (`pipe_hook.py` + `onboarding.py`)

Hooks de IDE que aplicam pipes de forma transparente após cada chamada de ferramenta — sem que o agente precise invocar pipe_run explicitamente. Suportados: Cursor (postToolUse), VS Code/GitHub (hooks), Claude Code/Qwen/Codex (PostToolUse), Windsurf e Cline (gateway de segurança pré-leitura), OpenClaw (plugin nativo) e pi.dev (extensão TypeScript nativa). Para OpenCode, o mandato SOP AGENTS.md é a estratégia ativa (veja Limitações Conhecidas). pipe_onboard injeta todos os hooks, comandos de barra (/pipe-run, /pipe-dynamic, /pipe-handoff, /pipe-stats) e o SOP completo do agente em um único comando.

6. A Ponte A2A (`a2a.py`)

pipe_agent_handoff() destila a saída do Agente A antes que ela entre na janela de contexto do Agente B. Agnóstico de framework — sem monkey-patching. Funciona em callbacks de tarefas CrewAI, hooks de transferência Google ADK, funções de borda LangGraph ou qualquer ponto de handoff personalizado. Disponível tanto como função Python quanto como ferramenta MCP. Retorna a saída original inalterada em qualquer erro, para que a cadeia de agentes nunca seja interrompida.

7. O Núcleo Nativo em Rust (`crates/cpipe`)

cpipe é o coração Rust de alto desempenho do ecossistema Context-Pipe. Ele porta o motor completo de orquestração — mesclagem de configuração, resolução de placeholders, roteamento de fluxo e a guarda de bypass autoconsciente — para um binário nativo pré-compilado com latência de inicialização <2ms (500× mais rápido que o runtime Python). Ele coexiste com o servidor Python: as ferramentas MCP permanecem em Python (FastMCP), enquanto o binário Rust está disponível como sidecar Tauri, CLI autônomo (cpipe run, cpipe list, cpipe serve) ou biblioteca Cargo para incorporação direta em aplicações Rust. Veja crates/cpipe/README.md para a API completa.

8. O Cliente TypeScript/JavaScript (`packages/cpipe-js`)

@context-pipe/client é a porta client-side segura para navegador e sandboxed do motor. Simula pipes Unix inteiramente em memória, suporta nós padrão (grep, replace), permite registro de nós PWA personalizados (consultas a banco de dados RAG, proxies CORS) e integra-se totalmente com AbortSignal para cancelamento. Veja packages/cpipe-js/README.md para a API completa e exemplos.

✨ O Que Torna Isso Diferente

Recurso	O que faz	Onde
Modelo de pipe Unix para IA	Encadeie qualquer ferramenta `stdin` e `stdout` em um pipe nomeado. Binário, shell, script ou ferramenta MCP — mesmo contrato.	Tipos Avançados de Nó
Tipo de Nó MCP	Chame qualquer ferramenta MCP (Figma, GitHub, context-mode) como um nó de pipe de primeira classe — sem scripts de wrapper.	doc/MCP_NODE_SPEC.md
Topologia sem compilação	O roteamento vive em `pipes.json`, não no código do nó. Re-roteie, ramifique ou troque um nó editando o mapa — sem alterações de código, sem recompilação, sem reimplantação de qualquer nó.	doc/ARCHITECTURE.md
Composição MCP primeiro-no-protocolo	Troque qualquer servidor MCP alterando uma chave de servidor. Sem imports, sem declarações de dependência, sem ciclo de build. Todo servidor MCP fala o mesmo protocolo — o ecossistema inteiro é uma camada de capacidade plug-and-play.	doc/ARCHITECTURE.md
Pipes Dinâmicos	Agentes de IA constroem e executam listas de nós ad hoc em tempo de execução via `pipe_run_dynamic` — sem entrada `pipes.json` necessária.	Pipes Dinâmicos
Registro MCP Sombra	Mantenha servidores MCP utilitários invisíveis para a lista de ferramentas do agente até serem necessários. `pipe_list_shadow_tools` os consulta sob demanda.	Registro MCP Sombra
Handoff de Agente A2A	Destile a saída do Agente A antes que ela entre na janela de contexto do Agente B — agnóstico de framework, sem monkey-patching.	Handoff A2A
Consciência de Versão	Alertas proativos de atualização com suporte do GitHub em `pipe_verify` e `pipe_onboard` para garantir paridade de ambiente.	Verificações de Saúde
Integridade de Fluxo	Motor de orquestração endurecido com robustez não-UTF8 (`errors="replace"`) e leitura segura contra nulos.	doc/ARCHITECTURE.md
Divisão de Fluxo T-Pipe	Salve uma cópia bruta da entrada de qualquer nó em disco antes de ser destilada — para auditoria, depuração e medição de qualidade.	3. Nós T-Pipe (Divisão de Fluxo)
Pressão Adaptativa de Janela	Sinaliza a margem de contexto restante para cada nó; `semantic-sift` ajusta automaticamente `--rate` de acordo.	Variáveis de Ambiente
Configuração Global	Compartilhe definições de pipe e registros de servidor MCP em todos os projetos — `pipes.json` local sempre vence.	doc/ARCHITECTURE.md
Injeção de Alias de Shell	`pipe_install_aliases` escreve `mcp-pipe` / `cpipe` no seu perfil de shell — pronto para terminal sem ativação de venv.	Uso no Terminal
Proteção Git	`pipe_onboard` atualiza automaticamente `.gitignore` para proteger artefatos internos de serem commitados.	Auto-Onboard
Balanço de Contexto	Cada execução de pipe é contabilizada: caracteres de entrada, caracteres de saída, latência por nó, atribuição de agente, ROI líquido.	Telemetria e ROI

🧠 A Arquitetura: Enums Semânticos (Resolvendo o Inchaço de Schema)

Em configurações MCP padrão, expor múltiplas capacidades (análise de PDF, busca em logs, limpeza de HTML) significa expor múltiplas ferramentas. Isso causa Inchaço de Schema: o prompt de sistema do LLM se enche com milhares de tokens de instruções complexas de ferramentas. Para Modelos de Linguagem Pequenos (SLMs), isso empurra o histórico de chat para fora, sobrecarrega a janela de contexto e leva a alucinações.

O context-pipe resolve isso por meio de Enums Semânticos. Em vez de ensinar a IA como usar utilitários complexos de linha de comando, você expõe uma única ferramenta: pipe_run(input, pipe_name). O parâmetro pipe_name é simplesmente um Enum dos seus pipelines predefinidos (por exemplo, ["parse-and-clean-pdf", "extract-critical-errors"]).

Isso separa perfeitamente Intenção de Execução:

O LLM fornece a Intenção: "Preciso do texto limpo deste PDF, então vou chamar o pipe parse-and-clean-pdf."
pipes.json fornece a Execução: [pandoc -> jq -> semantic-sift]

Usando nomes de pipes curtos e concisos, você alcança compressão extrema de prompt. A IA recebe um menu de "botões para apertar" de alto nível em vez de ler um manual de instruções para cada utilitário na máquina host. Melhor ainda, se você atualizar suas ferramentas de backend (por exemplo, trocando pandoc por markitdown), você nunca precisa atualizar o prompt do LLM. A IA ainda chama o mesmo pipe; o motor por trás dele apenas fica mais rápido.

🔧 Três Eixos Independentes de Mudança

Um pipeline CPP separa preocupações em três camadas que evoluem em ciclos completamente independentes:

Camada	O que é	Como você muda
Nós	O que cada etapa faz — uma ferramenta `stdin`/`stdout` simples, sem conhecimento do pipeline ao redor	Troque o binário, script ou ferramenta MCP
`pipes.json`	A topologia — como as etapas se conectam, ramificam e roteiam	Edite o mapa. Sem mudança de código. Sem recompilação. Sem reimplantação.
Servidores MCP	A capacidade por trás de cada chamada de ferramenta	Mude a chave do servidor. Sem imports, sem declarações de dependência, sem ciclo de build.

Melhorar a qualidade de um nó não muda a topologia. Reestruturar o roteamento não toca em nenhum nó. Atualizar um servidor MCP melhora automaticamente todos os pipes que o usam — sem mudanças no pipeline.

Especificamente para nós MCP, isso dissolve completamente o modelo tradicional de dependência. Cada servidor MCP fala o mesmo protocolo: JSON-RPC, tools/call, resposta de texto. O pipe não depende do que implementa o serviço — depende do que fala o protocolo. Todo o ecossistema MCP é, portanto, a camada de capacidade do pipe. Cada servidor MCP atual e futuro já é uma substituição válida para qualquer nó que sirva ao mesmo propósito semântico.

Em um script, você depende do que importa. Em um pipe, você depende do que fala o protocolo.

Essa separação também significa que o roteamento é livre de compilação. Em um script tradicional, salvaguardas e lógica de recuperação estão embutidas no código — mudar como um fluxo de trabalho se recupera exige mudar, testar e reimplantar o script. No CPP, o roteamento vive em pipes.json. Uma ramificação, um reroteamento ou uma troca de nó é uma edição de configuração. O ciclo de feedback entre "e se eu rerotear isso" e "deixe-me observar o que acontece" colapsa para quase zero.

🚀 Início Rápido (60 segundos)

# 1. Install
pip install mcp-context-pipe "semantic-sift[neural]"

# 2. Onboard (auto-creates pipes.json + hooks for your IDE)
context-pipe-onboard   # or: ask your AI "Run pipe_onboard()"

# 3. Verify the full stack
echo "noisy log [14:22:05.123] DEBUG: heartbeat ok" | context-pipe run standard-distill
# → distilled, noise-free output with audit header

Guia de configuração completo (Padrão Dual-Repo Soberano, layout de venv, configuração de IDE): doc/OPERATOR_GUIDE.md

🏗️ Começando

1. Instalação

Opção A: Instalação Rápida (PyPI)

Como os servidores MCP exigem um caminho explícito do executável Python na configuração do seu IDE, você deve criar um ambiente virtual primeiro:

ℹ️ O que você obtém: Isso instala a camada de orquestração do Context-Pipe e o servidor Python principal do Semantic-Sift. O binário Rust sift-core (para peneiramento heurístico quase instantâneo) está incluído no wheel PyPI — sem necessidade de toolchain Rust. O extra [neural] adiciona PyTorch (~1,5 GB) para compressão semântica de grandes cargas úteis.

uv venv
# Windows: .\.venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
uv pip install mcp-context-pipe "semantic-sift[neural,multi-modal]"

Opção B: Padrão Soberano (Recomendado para Estúdio de Dois) Clone ambos os repositórios lado a lado. O venv context-pipe atua como o ambiente mestre contendo ambos os pacotes. Veja Seção 0 do Guia do Operador para a sequência completa.

# 1. Clone both repos
git clone https://github.com/luismichio/context-pipe.git
git clone https://github.com/luismichio/semantic-sift.git

# 2. Master venv in context-pipe - holds both packages
cd context-pipe
python3.12 -m venv venv
# Windows:
.\venv\Scripts\activate
# macOS/Linux:
# source venv/bin/activate
uv pip install -e .
uv pip install -e ../semantic-sift  # semantic-sift-cli lands in context-pipe/venv/Scripts/ (Win) or venv/bin/ (Mac/Linux)

# 3. ML runtime venv in semantic-sift (Python 3.12 for torch/CUDA compatibility)
cd ../semantic-sift
python3.12 -m venv venv312
# Windows:
.\venv312\Scripts\activate
# macOS/Linux:
# source venv312/bin/activate
uv pip install -e .[neural]         # torch, transformers, llmlingua

Nota: O nome do pacote no PyPI é mcp-context-pipe mas o módulo instalado é context_pipe. O binário semantic-sift-cli é registrado apenas no venv onde semantic-sift é instalado via pip (passo 2 acima). Ambos os arquivos pipes.json devem referenciar esse caminho absoluto.

2. Conecte o MCP

CRÍTICO: Para caminhos de configuração exatos para Cursor, Gemini, Antigravity, OpenCode, VS Code e Claude, consulte a Matriz de Configuração Mestre.

3. Conecte uma Refinaria

Context-Pipe é o "Quadro de Comutação", mas precisa de uma "Refinaria" para destilar dados. Semantic-Sift é o motor de inteligência principal deste ecossistema. Ele usa peneiras heurísticas e modelos neurais (BERT/ONNX) para incinerar ruído (timestamps, texto padrão) enquanto preserva 95% do sinal.

Nota: No Padrão Soberano, semantic-sift é instalado de forma cruzada em context-pipe/venv (passo 2 acima). O Context-Pipe também descobrirá automaticamente um semantic-sift-cli instalado separadamente em todos os locais conhecidos (PATH do sistema, pipx, diretórios de venv irmãos) via pipe_onboard ou pipe_verify.

4. Verifique a Instalação

Após instalar ambos os pacotes, peça ao seu assistente de IA para verificar a pilha completa:

"Execute pipe_verify() para confirmar a instalação."

Isso reportará a saúde de cada componente e vinculará automaticamente semantic-sift-cli em pipes.json se for encontrado em um ambiente separado.

5. Configure seu primeiro Pipe

Edite pipes.json (veja pipes.json.example) para definir seus fluxos de contexto de alta fidelidade.

6. Onboarding Automático

Uma vez conectado, peça ao seu Assistente de IA para configurar seu espaço de trabalho:

"Execute pipe_onboard(environment='Cursor') para configurar este projeto."

pipe_onboard detecta automaticamente seu IDE se environment for omitido — ele inspeciona variáveis de ambiente e nomes de processos pai para identificar 12+ plataformas (Cursor, Gemini, Antigravity, OpenCode, VS Code, Windsurf, Claude, Cline, etc.). Passe environment explicitamente apenas quando a detecção automática for ambígua.

📚 Documentação

Documentação detalhada está disponível no diretório doc/.

doc/INDEX.md: O roteiro de navegação para o ecossistema de documentação.
doc/USE_CASES.md: Cenários reais de alto impacto demonstrando como encadear Bash, Nós de Script e Semantic-Sift.
doc/OPERATOR_GUIDE.md: Guia definitivo para configuração, domínio do terminal e configuração de pipes.json.
doc/ARCHITECTURE.md: Especificações técnicas da espinha dorsal de orquestração e do quadro de comutação.
doc/CONTEXT_PIPE_PROTOCOL.md: O padrão agnóstico de linguagem para interoperabilidade de ferramentas.
doc/INTEGRATION_ENCYCLOPEDIA.md: Matriz de Compatibilidade Mestre para Cursor, VS Code, Gemini/Antigravity e Claude.

🐍 Uso Programático

Python

O Context-Pipe expõe uma única função pipe() para integração direta em scripts Python, notebooks e frameworks de agentes (LangChain, CrewAI, etc.) — sem necessidade de servidor MCP ou CLI.

from context_pipe import pipe

# Auto-route based on pipes.json mappings
clean = pipe(raw_logs, tool_name="bash")

# Specify a pipe explicitly
distilled = pipe(document_text, pipe_name="semantic-refinery")

# Minimal usage — returns input unchanged if no pipe resolves
result = pipe(text)

Assinatura da função:

def pipe(
    text: str,
    pipe_name: str | None = None,
    tool_name: str = "",
    config_path: str = "pipes.json",
    vars: dict | None = None,
) -> str: ...

A função sempre retorna o text original inalterado em qualquer erro (falha de subprocesso, configuração ausente, etc.), então é seguro usá-la como um filtro drop-in.

JavaScript/TypeScript

Para runtimes do lado do cliente (navegadores, PWAs, extensões), instale o pacote sandboxed:

npm install @context-pipe/client

Inicialize o PipelineEngine e execute suas configurações:

import { PipelineEngine } from '@context-pipe/client';

const engine = new PipelineEngine({ failFast: true });

// Run a named pipe configuration
const output = await engine.runPipe(pipeConfig, rawLogs);

Veja o README do cliente para detalhes sobre registrar nós de banco de dados ou fetch personalizados e lidar com cancelamentos.

Biblioteca Rust (`cpipe`)

Para aplicações Rust ou Tauri, incorpore o núcleo nativo diretamente:

use cpipe::config::load_pipes_config;
use cpipe::orchestrator::run_pipe;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let config = load_pipes_config();
    let pipe = config.pipes.iter().find(|p| p.name == "standard-distill")
        .ok_or("Pipe not found")?;

    let (output, _telemetry) = run_pipe(
        pipe,
        "raw context text here",
        Some("my-tool"), None, &config.servers,
    ).await;

    println!("{output}");
    Ok(())
}

Adicione ao seu Cargo.toml:

[dependencies]
cpipe = { git = "https://github.com/luismichio/context-pipe", path = "crates/cpipe" }

Binários pré-compilados para Windows, macOS (Intel & Apple Silicon) e Linux estão disponíveis na página de GitHub Releases, ou baixe via:

python scripts/fetch_cpipe.py

🤝 Handoff A2A (Agente para Agente)

Ao encadear agentes, use pipe_agent_handoff para destilar a saída do Agente A antes que ela entre na janela de contexto do Agente B. Funciona com qualquer framework — sem necessidade de monkey-patching.

from context_pipe.a2a import pipe_agent_handoff

# In a CrewAI task callback, ADK transfer hook, or any custom handoff point:
agent_b_input = pipe_agent_handoff(
    agent_a_output,
    pipe_name="semantic-refinery",   # optional; auto-routes if omitted
    from_agent="researcher",
    to_agent="writer",
)

Também disponível como ferramenta MCP — pergunte ao seu assistente de IA: "Execute pipe_agent_handoff() para destilar esta saída de agente antes de passá-la adiante."

Assinatura da função:

def pipe_agent_handoff(
    output: str,
    pipe_name: str | None = None,   # explicit pipe; auto-routes if omitted
    from_agent: str | None = None,  # producing agent label (telemetry + routing)
    to_agent: str | None = None,    # consuming agent label (telemetry only)
    config_path: str = "pipes.json",
) -> str: ...

Sempre retorna o output original inalterado em qualquer erro — a cadeia de agentes nunca é interrompida.

💻 Uso no Terminal (CLI `mcp-pipe`)

O Context-Pipe inclui um runner de terminal de primeira classe — mcp-pipe — para que você possa usar todas as capacidades sem IDE ou servidor MCP.

# Run a named pipe on stdin
cat app.log | mcp-pipe run standard-distill

# Run a named pipe on a file directly
mcp-pipe run semantic-refinery --file spec.md

# Run an ad-hoc node array (shell synergy requires --allow-shell)
echo "noisy output" | mcp-pipe run-dynamic '[{"cmd":"semantic-sift-cli","args":["logs"]}]'

# List all configured pipes + curated PATH tools (Shadow MCP discovery)
mcp-pipe list

# Print the Context Balance Sheet (ROI across all sessions)
mcp-pipe stats

# Start the MCP server manually (stdio transport)
mcp-pipe serve

# Install/remove the cpipe shell alias
mcp-pipe aliases install
mcp-pipe aliases remove

O ponto de entrada mcp-pipe é registrado automaticamente quando você pip install mcp-context-pipe. Use cpipe como atalho após executar mcp-pipe aliases install.

Registro MCP Sombra

Cada servidor MCP que você adiciona a um IDE registra suas ferramentas globalmente — todas aparecem na lista de ferramentas do agente, quer o agente precise delas ou não. Em escala, isso causa inchaço de ferramentas MCP: centenas de ferramentas no prompt, tokens desperdiçados em cada chamada de inferência e maior chance de o agente escolher a errada.

context-pipe adota uma abordagem diferente. Em vez de registrar cada ferramenta de processamento de contexto como uma ferramenta MCP de primeira classe, ele expõe uma única ferramenta de descoberta — pipe_list_shadow_tools — que retorna um manifesto de capacidades ao vivo sob demanda. As ferramentas permanecem ocultas ("sombra") até que o agente as solicite. Uma ferramenta MCP faz o trabalho de muitas.

O que o manifesto inclui:

Pipes pipes.json — cada pipe nomeado configurado no seu projeto.
Ferramentas PATH selecionadas — testa 7 ferramentas CLI conhecidas (jq, yq, markitdown, pandoc, rg, fd, bat) e exibe qualquer uma encontrada no PATH.

Limitação conhecida: ferramentas sombra não são chamáveis como ferramentas MCP independentes — o agente deve roteá-las através de pipe_run ou pipe_run_dynamic. Isso é por design (mantém a superfície MCP mínima), mas significa que o agente não pode chamar jq ou markitdown diretamente sem construir um nó de pipe dinâmico.

Acesso via terminal com mcp-pipe: o mesmo manifesto está disponível sem IDE ou servidor MCP — mcp-pipe list imprime cada pipe e ferramenta PATH selecionada para stdout. Envie qualquer conteúdo através de uma ferramenta sombra diretamente do terminal:

# Discover what's available
mcp-pipe list

# Run a shadow tool via a dynamic pipe — no pipes.json entry needed
echo "# My Doc" | mcp-pipe run-dynamic '[{"cmd":"markitdown"},{"cmd":"semantic-sift-cli","args":["doc"]}]'

🔗 Tipos Avançados de Nó

O Context-Pipe suporta mais do que apenas binários simples. Você pode encadear ferramentas padrão do SO e mandatos especializados.

1. Nós Bash (Sandboxed)

Execute comandos shell arbitrários como parte do seu pipe. Por design, todos os comandos são executados nativamente com shell=False para prevenir vulnerabilidades de injeção.

{ "cmd": "grep", "args": ["ERROR"] }

2. Nós de Script

Executa um script específico do projeto (Python/Shell) ou um conjunto de instruções local. Resolvido de .gemini/scripts/ (padrão).

{ "type": "script", "cmd": "security-auditor" }

3. Nós T-Pipe (Divisão de Fluxo)

Salve uma cópia bruta do fluxo em disco antes que um nó o destile — sem interromper a cadeia. Útil para depurar a qualidade do pipe e auditar o que foi peneirado.

{
  "cmd": "semantic-sift-cli",
  "args": ["logs"],
  "tee": {
    "sink": "file",
    "path": "logs/{tool_name}_{iso_date}.log",
    "mode": "append"
  }
}

path suporta tokens {iso_date} (AAAA-MM-DD) e {tool_name}. Uma falha de tee nunca interrompe a cadeia principal.

4. Nós MCP

Chame qualquer ferramenta MCP como um nó de pipe. Sem scripts wrapper — o orquestrador inicia o servidor MCP, chama a ferramenta e passa o resultado adiante via stdout.

{
  "type": "mcp",
  "server": "figma",
  "tool": "get_file",
  "input_key": "file_id"
}

As definições de servidor vivem em um bloco servers em pipes.json ou ~/.mcp-pipe.json. Veja doc/MCP_NODE_SPEC.md para a especificação completa.

5. Nós Validador (Fase 11)

Um validador executa um subprocesso e roteia com base no seu código de saída em vez de fluir linearmente. Use isso para construir pipelines auto-reparáveis que tentam corrigir problemas automaticamente antes de falhar.

{
  "name": "self-healing-lint",
  "nodes": [
    {
      "cmd": "eslint",
      "args": ["--format", "compact", "src/"],
      "type": "validator",
      "id": "lint-check",
      "branches": {
        "0": "done",
        "1": "auto-fix",
        "default": "auto-fix"
      }
    }
  ],
  "branch_sequences": {
    "auto-fix": [
      { "cmd": "eslint", "args": ["--fix", "src/"] },
      { "cmd": "semantic-sift-cli", "args": ["logs"] }
    ],
    "done": [
      { "cmd": "semantic-sift-cli", "args": ["logs"] }
    ]
  }
}

Saída 0 → linting passou, salta para done (destila o relatório limpo).
Saída 1 → linting falhou, salta para auto-fix (executa --fix, depois destila).
"default" captura qualquer outro código de saída (ex.: 2 para erros de configuração do ESLint).
O stdout do validador é encaminhado como entrada para a sequência alvo.

6. Chaves de Condição (Fase 11)

Qualquer nó pode ser pulado condicionalmente sem modificar a definição do pipe:

{
  "cmd": "neural-summariser",
  "condition": "size:>8000"
}

O nó só executa se a entrada atual exceder 8.000 bytes. Predicados suportados:

Predicado	Exemplo	Quando o nó é executado
`size:>N`	`size:>10000`	Comprimento da entrada > N bytes
`size:<N`	`size:<500`	Comprimento da entrada < N bytes
`artifact:exists:<path>`	`artifact:exists:dist/app.js`	Arquivo existe no disco
`artifact:missing:<path>`	`artifact:missing:output/report.md`	Arquivo NÃO existe
`contains:<string>`	`contains:ERROR`	Os 300 caracteres iniciais contêm a substring

Predicados desconhecidos falham abertamente (avisam e executam o nó) para evitar bloquear pipelines silenciosamente.

🔗 O Ecossistema (Studio of Two)

Context-Pipe é um membro fundamental da infraestrutura Studio of Two. Ele foi projetado para funcionar em harmonia de alta fidelidade com:

Semantic-Sift: A refinaria inteligente para contexto agêntico. Sift é o motor de destilação principal do Context-Pipe, fornecendo os nós de peneiramento matemático e neural usados em nossos modelos padrão.
std-context-lab: O laboratório oficial de integração e campo de testes. Este repositório serve como nosso campo de testes isolado de batalha, onde capacidades entre repositórios, combinações de servidores MCP e interações de hooks de terminal são simuladas e verificadas.
- Cenários Isolados: Executa casos de teste isolados imitando comportamentos reais de IA para reproduzir e verificar correções sem poluir runtimes principais.
- Evidência Empírica: Cada bug resolvido ou recurso é acompanhado por um log de execução rastreado (EVIDENCE.md), servindo como prova empírica de sucesso.
- Portão de Paridade de Plataforma: Audita a paridade CLI Python/Rust e comportamentos de shell em terminais Windows (PowerShell/CMD) e UNIX antes do lançamento.

🧩 Sinergias e Limites de Ferramentas

Quatro ferramentas frequentemente aparecem juntas em uma stack Studio of Two. Elas são complementares, não sobrepostas — cada uma possui uma camada distinta.

Ferramenta	Camada	Papel Principal	Relacionamento
context-pipe	Orquestração	Roteia conteúdo através de pipes nomeados; gerencia execução de nós, timeouts, T-pipe, telemetria e handoff A2A.	O painel de controle. Chama todas as outras ferramentas como nós quando conectadas.
semantic-sift	Destilação	Compressão heurística + neural de texto. Remove ruído (timestamps, boilerplate, tokens repetidos) preservando o sinal.	CLI e servidor MCP totalmente independentes. O nó de refinaria principal dentro dos pipes do context-pipe.
context-mode	Indexação em sessão	Busca de texto completo BM25 sobre conteúdo indexado durante a sessão atual do agente. Recuperação rápida sem banco de dados vetorial.	Servidor MCP totalmente independente. Opcionalmente conectado como um nó `mcp` para indexar ou buscar dentro de um pipe.
Serena	Inteligência de código	Busca de símbolos com suporte LSP, refatoração e navegação de código. Entende a AST — não apenas texto.	Servidor MCP totalmente independente. Opcionalmente conectado como um nó `mcp` para alimentar símbolos de código precisos em um pipe em vez de leituras brutas de arquivos.

Quando usar cada um

Use context-pipe quando você precisar orquestrar: encadear ferramentas, aplicar pipes automaticamente em chamadas de ferramentas, rotear por gatilho, salvar snapshots T-pipe, contabilizar ROI ou fazer ponte de handoffs de agentes.

Use semantic-sift quando você precisar comprimir: um documento grande, um arquivo de log, um resultado de busca ou qualquer payload onde a relação ruído-sinal seja alta. Executa de forma independente via CLI ou MCP — e como um nó dentro dos pipes do context-pipe.

Use context-mode quando você precisar recuperar: você já ingeriu conteúdo nesta sessão e quer busca BM25 rápida sobre ele. Funciona de forma independente como um servidor MCP em qualquer IDE. Combine-o com semantic-sift em ambos os lados — a montante para comprimir conteúdo antes da indexação (índice menor, busca mais rápida) e a jusante para destilar blocos recuperados antes de chegarem à janela de contexto.

Use Serena quando você precisar navegar em código: encontrar um símbolo, rastrear referências, inspecionar tipos ou realizar uma refatoração. Funciona de forma independente como um servidor MCP. Sua saída estruturada e precisa é muito melhor do que uma leitura bruta de arquivo como entrada para qualquer ferramenta a jusante — incluindo um pipe de peneiramento.

Configuração complementar — reduzindo o uso de tokens

Cada ferramenta reduz independentemente a pressão de tokens. Juntas, as economias se acumulam:

Serena retorna apenas o símbolo que você pediu — não o arquivo inteiro.
semantic-sift comprime o conteúdo antes de entrar no context-mode (índice menor, busca mais rápida) e após a recuperação (blocos sem ruído na janela de contexto).
context-mode retorna apenas os blocos indexados relevantes — não o corpus inteiro ingerido.
context-pipe garante que essa sequência seja disparada automaticamente e contabilizada — sem conexão manual por tarefa.

O resultado: o agente trabalha com uma fração do volume bruto de tokens, em todas as sessões, sem mudar como pensa ou quais ferramentas chama.

Exemplo de sinergia

[user query]
    → serena/find_symbol           # MCP node: precise code symbol — not a raw file dump
    → context-mode/search          # MCP node: retrieve related session context
    → semantic-sift-cli semantic   # binary node: compress both into a dense summary
    → security-auditor             # script node: project-specific logic

Todas as quatro ferramentas em um único pipe. Cada uma fazendo exatamente um trabalho.

⚙️ Variáveis de Ambiente

Variável	Padrão	Descrição
`PIPE_CONFIG_PATH`	`pipes.json`	Caminho absoluto para o arquivo de configuração `pipes.json` do projeto.
`PIPE_NODE_TIMEOUT_MS`	`30000`	Timeout de execução por nó em milissegundos.
`allow_shell`	`false`	Habilita nós de comandos shell arbitrários em pipes dinâmicos (ferramenta MCP `pipe_run_dynamic` / API `run_dynamic_pipe()`). Requer que o nó final seja um comando de terminal `semantic-sift` para garantir a segurança do contexto.
`PIPE_LOG_LEVEL`	(nenhum)	Nível de log padrão do pipeline (`compact` ou `verbose`). Habilita logging para todos os pipes se definido.
`PIPE_LOG_PREFIX`	`[PIPE]`	Texto padrão prefixado aos logs de execução do pipeline em `stderr`.

⚠️ Limitações Conhecidas

OpenCode — Interceptação de Saída de Ferramentas MCP

O recurso "interceptor subconsciente" (pipe_hook.py) funciona de forma transparente para Cursor, VS Code, Gemini CLI, Antigravity CLI e Claude Desktop ao injetar manipuladores de hooks que disparam após cada chamada de ferramenta.

OpenCode é a exceção. O hook tool.execute.after é declarado na interface do plugin Hooks do OpenCode, mas nunca é acionado pelo runtime do OpenCode (confirmado via auditoria de fonte de session/processor.ts, session/llm.ts, tool/registry.ts, agent.ts). O código de mutação de saída do plugin é silenciosamente um no-op.

Solução atual: O mandato SOP AGENTS.md (pipe_read_file para todas as leituras de arquivos) é a estratégia de interceptação ativa para OpenCode até que a injeção transparente de hooks seja suportada a montante.

Issue upstream: sst/opencode#21149
Issue do plugin: sst/opencode#25918
Rastreado em nosso backlog: Fase 4.5 — veja doc/backlog.md

⚖️ Licenciamento

context-pipe é licenciado sob a Apache License 2.0. É um projeto "Open Source, Closed Contribution" mantido pelo Studio of Two para garantir integridade arquitetural.

Construindo Infraestrutura de Alta Fidelidade para a Era da Inteligência.