Context-Pipe

Una capa de orquestación de alto rendimiento e independiente del lenguaje que lleva la Filosofía Unix a la ventana de contexto de la IA.

GitHub

Prueba este MCPPatrocinado

Documentación

⛓️ Context-Pipe

El Estándar Universal para la Ingeniería de Contexto.

context-pipe es una capa de orquestación de alto rendimiento directamente inspirada en el pipe de terminal Unix — la misma filosofía que hizo de cmd1 | cmd2 | cmd3 el primitivo de composición más duradero de la informática. Así como el terminal encadena procesos a través de flujos de bytes stdin/stdout, Context-Pipe encadena llamadas de herramientas de IA a través de flujos de contexto: cada nodo hace una cosa, pasa su salida al siguiente, y el LLM solo ve la señal final y refinada.

Esto no es una metáfora — es una extensión literal. Context-Pipe soporta tanto piping MCP (encadenar llamadas de herramientas MCP a través del orquestador) como piping de terminal (cualquier binario, comando de shell o script que lea stdin y escriba stdout es un nodo válido). Los dos modos se combinan libremente en una única definición de pipe. Y a través del CLI mcp-pipe, extiende el propio terminal: el subcomando mcp-pipe tool hace que cualquier servidor MCP — context-mode, serena, GitHub, Firecrawl, o cualquier servidor registrado en pipes.json — sea directamente pipeable desde el shell, cargándose bajo demanda, sin scripts envoltorio y sin necesidad 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

Hoy, mcp-pipe run <pipe> ya le da al terminal acceso de primera clase a cualquier pipe con nombre definido en pipes.json, componiendo binarios de terminal a través del mismo orquestador que usa el IDE.

🚀 La Visión

El agente de IA tiene un problema de infraestructura fundamental: cada llamada de herramienta devuelve salida cruda y sin filtrar directamente a la ventana de contexto. Los logs llegan con marcas de tiempo. Los resultados de búsqueda llegan con texto de relleno. El análisis de 40KB del Agente A se pasa verbatim al Agente B. La ventana de contexto se llena. La señal se ahoga en el ruido. El LLM se degrada.

context-pipe resuelve esto en la capa de infraestructura — antes de que el LLM vea nada.

En la filosofía del Estudio de Dos, construimos Sistemas, no Parches. Un parche sería un filtro personalizado por herramienta. Un sistema es un protocolo universal: cualquier herramienta que lea stdin y escriba stdout se convierte en un nodo. Cualquier secuencia de nodos se convierte en un pipe. Cualquier pipe es nombrado, versionado, auditado y reutilizable en todos los proyectos y todos los frameworks de agentes.

El resultado es una cadena de suministro de contexto: los datos entran crudos, pasan por una secuencia de refinerías (normalizar → filtrar → comprimir → destilar), y llegan al LLM como contenido denso y de alta señal. Cada byte ahorrado se contabiliza en el Balance de Contexto. Cada ejecución de pipe es trazable. Cada traspaso A2A está protegido.

Esto no es un envoltorio alrededor de semantic-sift. Es la capa de orquestación que hace que cualquier refinería sea componible, observable y de grado de producción. Un nodo puede ser un binario, un comando de shell, un script de Python o una herramienta MCP completa (Figma, GitHub, context-mode, o cualquier servidor registrado en pipes.json). Si lee stdin y escribe stdout, pertenece al pipe.

Ejemplo — rastrea la web, investígala, guárdala y envíala:

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 nodo es un subproceso real. El T-pipe guarda una copia cruda en cualquier punto sin interrumpir la cadena. El LLM recibe solo lo que importa — y cada byte de entrada, byte de salida y milisegundo de latencia se registra automáticamente en el Balance de Contexto.

🛠️ Componentes Principales

1. El Protocolo Context-Pipe (CPP)

Un estándar agnóstico al lenguaje con una regla: un nodo lee stdin, transforma el contenido y escribe en stdout. Cualquier binario, comando de shell, script de Python o herramienta MCP que respete este contrato es un nodo válido. El protocolo está definido en doc/CONTEXT_PIPE_PROTOCOL.md y es deliberadamente simple — sin SDKs, sin registro, sin acoplamiento a frameworks.

2. La Columna de Orquestación (`orchestrator.py`)

El motor de ejecución que encadena nodos en pipes. Ejecuta cada nodo como un subproceso real del SO con shell=False aplicado (sin superficie de inyección). Características: guardia de timeout por nodo (PIPE_NODE_TIMEOUT_MS), división de flujo T-Pipe (guardar la entrada cruda en disco antes de que un nodo la procese), y contabilidad de trazado completa (tamaño de entrada/salida + latencia por nodo).

3. El Conmutador Universal (`pipes.json` + mapeos)

Enrutamiento basado en datos que resuelve el pipe óptimo automáticamente según tres tipos de disparador: nombre de herramienta (tool:regex), tamaño de payload (size:>N) y respaldo por defecto. Las definiciones de pipe viven en pipes.json (a nivel de proyecto) y opcionalmente ~/.mcp-pipe.json (global, fusionado con precedencia local). No se requieren cambios de código para añadir, modificar o reenrutar pipes.

4. La Superficie MCP (`server.py` + CLI `mcp-pipe`)

Ocho herramientas MCP exponen cada capacidad directamente a los asistentes de IA: pipe_run, pipe_run_dynamic, pipe_read_file, pipe_analyze_file, pipe_list_shadow_tools, pipe_agent_handoff, get_pipe_stats y pipe_onboard. El CLI mcp-pipe refleja la misma superficie para flujos de trabajo centrados en terminal — sin necesidad de IDE. El Descubrimiento de Herramientas Sombra (pipe_list_shadow_tools) le da al agente un manifiesto de capacidades en vivo que combina pipes configurados y herramientas PATH seleccionadas (jq, rg, markitdown, pandoc…).

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

Hooks de IDE que aplican pipes de forma transparente después de cada llamada de herramienta — sin que el agente necesite invocar pipe_run explícitamente. Compatible con: Cursor (postToolUse), VS Code/GitHub (hooks), Claude Code/Qwen/Codex (PostToolUse), Windsurf y Cline (puerta de seguridad de pre-lectura), OpenClaw (plugin nativo) y pi.dev (extensión nativa de TypeScript). Para OpenCode, el mandato SOP AGENTS.md es la estrategia activa (ver Limitaciones Conocidas). pipe_onboard inyecta todos los hooks, comandos slash (/pipe-run, /pipe-dynamic, /pipe-handoff, /pipe-stats) y el SOP completo del agente en un solo comando.

6. El Puente A2A (`a2a.py`)

pipe_agent_handoff() destila la salida del Agente A antes de que entre en la ventana de contexto del Agente B. Agnóstico al framework — sin monkey-patching. Funciona en callbacks de tareas de CrewAI, hooks de transferencia de Google ADK, funciones de borde de LangGraph, o cualquier punto de traspaso personalizado. Disponible tanto como función de Python como herramienta MCP. Devuelve la salida original sin cambios ante cualquier error, para que la cadena de agentes nunca se interrumpa.

7. El Núcleo Nativo en Rust (`crates/cpipe`)

cpipe es el corazón Rust de alto rendimiento del ecosistema Context-Pipe. Porta el motor de orquestación completo — fusión de configuración, resolución de placeholders, enrutamiento de flujos y la guardia de bypass autoconsciente — a un binario nativo precompilado con latencia de arranque <2ms (500× más rápido que el runtime de Python). Coexiste con el servidor Python: las herramientas MCP permanecen en Python (FastMCP), mientras que el binario Rust está disponible como sidecar de Tauri, CLI independiente (cpipe run, cpipe list, cpipe serve) o biblioteca Cargo para incrustación directa en aplicaciones Rust. Ver crates/cpipe/README.md para la API completa.

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

@context-pipe/client es el port del motor seguro para navegador y sandboxed del lado del cliente. Simula pipes Unix enteramente en memoria, soporta nodos estándar (grep, replace), permite registro de nodos PWA personalizados (consultas a bases de datos RAG, proxies CORS) y se integra completamente con AbortSignal para cancelación. Ver packages/cpipe-js/README.md para la API completa y ejemplos.

✨ Qué Lo Hace Diferente

Característica	Qué hace	Dónde
Modelo de pipe Unix para IA	Encadena cualquier herramienta `stdin` y `stdout` en un pipe con nombre. Binario, shell, script o herramienta MCP — mismo contrato.	Tipos de Nodo Avanzados
Tipo de Nodo MCP	Llama a cualquier herramienta MCP (Figma, GitHub, context-mode) como nodo de pipe de primera clase — sin scripts envoltorio.	doc/MCP_NODE_SPEC.md
Topología sin compilación	El enrutamiento vive en `pipes.json`, no en el código del nodo. Reenruta, ramifica o intercambia un nodo editando el mapa — sin cambios de código, sin recompilar, sin redesplegar ningún nodo.	doc/ARCHITECTURE.md
Composición MCP primero-protocolo	Intercambia cualquier servidor MCP cambiando una clave de servidor. Sin imports, sin declaraciones de dependencias, sin ciclo de build. Cada servidor MCP habla el mismo protocolo — todo el ecosistema es una capa de capacidades plug-and-play.	doc/ARCHITECTURE.md
Pipes Dinámicos	Los agentes de IA construyen y ejecutan listas de nodos ad hoc en tiempo de ejecución vía `pipe_run_dynamic` — sin necesidad de entrada en `pipes.json`.	Pipes Dinámicos
Registro MCP Sombra	Mantén servidores MCP de utilidad invisibles para la lista de herramientas del agente hasta que se necesiten. `pipe_list_shadow_tools` los consulta bajo demanda.	Registro MCP Sombra
Traspaso de Agente A2A	Destila la salida del Agente A antes de que entre en la ventana de contexto del Agente B — agnóstico al framework, sin monkey-patching.	Traspaso A2A
Conciencia de Versión	Alertas de actualización proactivas respaldadas por GitHub en `pipe_verify` y `pipe_onboard` para garantizar paridad de entorno.	Comprobaciones de Salud
Integridad de Flujo	Motor de orquestación endurecido con robustez no-UTF8 (`errors="replace"`) y lectura segura ante nulos.	doc/ARCHITECTURE.md
División de Flujo T-Pipe	Guarda una copia cruda de la entrada de cualquier nodo en disco antes de que se destile — para auditoría, depuración y medición de calidad.	3. Nodos T-Pipe (División de Flujo)
Presión Adaptativa de Ventana	Señala el margen de contexto restante a cada nodo; `semantic-sift` ajusta automáticamente `--rate` en consecuencia.	Variables de Entorno
Configuración Global	Comparte definiciones de pipe y registros de servidores MCP en todos los proyectos — el `pipes.json` local siempre gana.	doc/ARCHITECTURE.md
Inyección de Alias de Shell	`pipe_install_aliases` escribe `mcp-pipe` / `cpipe` en tu perfil de shell — listo para terminal sin activación de venv.	Uso en Terminal
Protección Git	`pipe_onboard` actualiza automáticamente `.gitignore` para proteger artefactos internos de ser commiteados.	Auto-Onboarding
Balance de Contexto	Cada ejecución de pipe se contabiliza: caracteres de entrada, caracteres de salida, latencia por nodo, atribución de agente, ROI neto.	Telemetría y ROI

🧠 La Arquitectura: Enums Semánticos (Resolviendo la Inflación de Esquemas)

En configuraciones MCP estándar, exponer múltiples capacidades (análisis de PDF, búsqueda de logs, limpieza de HTML) significa exponer múltiples herramientas. Esto causa Inflación de Esquemas: el prompt del sistema del LLM se llena con miles de tokens de instrucciones complejas de herramientas. Para Modelos de Lenguaje Pequeños (SLMs), esto expulsa el historial de chat, abruma la ventana de contexto y conduce a alucinaciones.

context-pipe resuelve esto mediante Enums Semánticos. En lugar de enseñar a la IA cómo usar utilidades complejas de línea de comandos, expones una única herramienta: pipe_run(input, pipe_name). El parámetro pipe_name es simplemente un Enum de tus pipelines predefinidos (p. ej., ["parse-and-clean-pdf", "extract-critical-errors"]).

Esto separa perfectamente la Intención de la Ejecución:

El LLM proporciona la Intención: "Necesito el texto limpio de este PDF, así que llamaré al pipe parse-and-clean-pdf."
pipes.json proporciona la Ejecución: [pandoc -> jq -> semantic-sift] Al usar nombres de pipe breves y concisos, logras una compresión de prompt extrema. La IA obtiene un menú de "botones para pulsar" de alto nivel en lugar de leer un manual de instrucciones para cada utilidad de la máquina host. Mejor aún, si actualizas tus herramientas de backend (por ejemplo, cambiando pandoc por markitdown), nunca tienes que actualizar el prompt del LLM. La IA sigue llamando al mismo pipe; el motor detrás simplemente se vuelve más rápido.

🔧 Tres ejes independientes de cambio

Un pipeline CPP separa las preocupaciones en tres capas que evolucionan en ciclos completamente independientes:

Capa	Qué es	Cómo lo cambias
Nodos	Qué hace cada paso: una herramienta `stdin`/`stdout` simple, sin conocimiento del pipeline que la rodea	Cambia el binario, script o herramienta MCP
`pipes.json`	La topología: cómo se conectan, ramifican y enrutan los pasos	Edita el mapa. Sin cambio de código. Sin recompilación. Sin redeploy.
Servidores MCP	La capacidad detrás de cada llamada de herramienta	Cambia la clave del servidor. Sin imports, sin declaraciones de dependencia, sin ciclo de build.

Mejorar la calidad de un nodo no cambia la topología. Reestructurar el enrutamiento no toca ningún nodo. Actualizar un servidor MCP mejora automáticamente cada pipe que lo usa, sin cambios en el pipeline.

Para los nodos MCP específicamente, esto disuelve por completo el modelo de dependencia tradicional. Cada servidor MCP habla el mismo protocolo: JSON-RPC, tools/call, respuesta de texto. El pipe no depende de lo que implementa el servicio, sino de lo que habla el protocolo. Por lo tanto, todo el ecosistema MCP es la capa de capacidad del pipe. Cada servidor MCP actual y futuro ya es un reemplazo válido para cualquier nodo que sirva el mismo propósito semántico.

En un script, dependes de lo que importas. En un pipe, dependes de lo que habla el protocolo.

Esta separación también significa que el enrutamiento está libre de compilación. En un script tradicional, las salvaguardas y la lógica de recuperación están incrustadas en el código: cambiar cómo se recupera un flujo de trabajo requiere cambiar, probar y redesplegar el script. En CPP, el enrutamiento vive en pipes.json. Una rama, un redireccionamiento o un cambio de nodo es una edición de configuración. El bucle de retroalimentación entre "¿y si redirijo esto?" y "déjame observar qué sucede" se reduce a casi cero.

🚀 Inicio 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

Guía de configuración completa (Patrón Soberano de Doble Repositorio, estructura de venv, configuración de IDE): doc/OPERATOR_GUIDE.md

🏗️ Primeros pasos

1. Instalación

Opción A: Instalación rápida (PyPI)

Debido a que los servidores MCP requieren una ruta explícita del ejecutable de Python en tu configuración de IDE, primero debes crear un entorno virtual:

ℹ️ Lo que obtienes: Esto instala la capa de orquestación de Context-Pipe y el servidor Python principal de Semantic-Sift. El binario Rust sift-core (para el tamizado heurístico casi instantáneo) está incluido en la rueda de PyPI: no se requiere cadena de herramientas Rust. El extra [neural] añade PyTorch (~1.5 GB) para la compresión semántica de cargas grandes.

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

Opción B: Patrón Soberano (Recomendado para Estudio de Dos)

Clona ambos repositorios uno al lado del otro. El venv context-pipe actúa como el entorno maestro que contiene ambos paquetes. Consulta Sección 0 de la Guía del Operador para la secuencia 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: El nombre del paquete en PyPI es mcp-context-pipe pero el módulo instalado es context_pipe. El binario semantic-sift-cli se registra solo en el venv donde semantic-sift se instala con pip (paso 2 anterior). Ambos archivos pipes.json deben hacer referencia a esa ruta absoluta.

2. Conecta el MCP

CRÍTICO: Para rutas de configuración exactas para Cursor, Gemini, Antigravity, OpenCode, VS Code y Claude, consulta la Matriz de Configuración Maestra.

3. Conecta una Refinería

Context-Pipe es el "Conmutador", pero necesita una "Refinería" para destilar datos. Semantic-Sift es el motor de inteligencia insignia de este ecosistema. Utiliza tamices heurísticos y modelos neuronales (BERT/ONNX) para incinerar el ruido (marcas de tiempo, texto repetitivo) mientras preserva el 95% de la señal.

Nota: En el Patrón Soberano, semantic-sift se instala de forma cruzada en context-pipe/venv (paso 2 anterior). Context-Pipe también auto-descubrirá un semantic-sift-cli instalado por separado en todas las ubicaciones conocidas (PATH del sistema, pipx, directorios venv hermanos) a través de pipe_onboard o pipe_verify.

4. Verifica la instalación

Después de instalar ambos paquetes, pide a tu asistente de IA que verifique la pila completa:

"Ejecuta pipe_verify() para confirmar la instalación."

Esto informará sobre el estado de cada componente y vinculará automáticamente semantic-sift-cli en pipes.json si se encontró en un entorno separado.

5. Configura tu primer Pipe

Edita pipes.json (consulta pipes.json.example) para definir tus flujos de contexto de alta fidelidad.

6. Incorporación automática

Una vez conectado, pide a tu Asistente de IA que configure tu espacio de trabajo:

"Ejecuta pipe_onboard(environment='Cursor') para configurar este proyecto."

pipe_onboard detecta automáticamente tu IDE si se omite environment: inspecciona variables de entorno y nombres de procesos padre para identificar más de 12 plataformas (Cursor, Gemini, Antigravity, OpenCode, VS Code, Windsurf, Claude, Cline, etc.). Pasa environment explícitamente solo cuando la detección automática sea ambigua.

📚 Documentación

La documentación detallada está disponible en el directorio doc/.

doc/INDEX.md: El mapa de navegación para el ecosistema de documentación.
doc/USE_CASES.md: Escenarios reales de alto impacto que demuestran cómo encadenar Bash, Nodos de Script y Semantic-Sift.
doc/OPERATOR_GUIDE.md: Guía definitiva para la configuración, el dominio de la terminal y la configuración de pipes.json.
doc/ARCHITECTURE.md: Especificaciones técnicas del espinazo de orquestación y el conmutador.
doc/CONTEXT_PIPE_PROTOCOL.md: El estándar agnóstico de lenguaje para la interoperabilidad de herramientas.
doc/INTEGRATION_ENCYCLOPEDIA.md: Matriz de Compatibilidad Maestra para Cursor, VS Code, Gemini/Antigravity y Claude.

🐍 Uso programático

Python

Context-Pipe expone una única función pipe() para integración directa en scripts de Python, notebooks y marcos de agentes (LangChain, CrewAI, etc.) — no se requiere servidor MCP ni 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)

Firma de la función:

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

La función siempre devuelve el text original sin cambios ante cualquier error (fallo de subproceso, configuración faltante, etc.), por lo que es seguro usarla como filtro de reemplazo directo.

JavaScript/TypeScript

Para entornos de ejecución del lado del cliente (navegadores, PWAs, extensiones), instala el paquete sandboxed:

npm install @context-pipe/client

Inicializa el PipelineEngine y ejecuta tus configuraciones:

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

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

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

Consulta el README del cliente para obtener detalles sobre el registro de nodos personalizados de base de datos o fetch y el manejo de cancelaciones.

Biblioteca Rust (`cpipe`)

Para aplicaciones Rust o Tauri, incrusta el núcleo nativo directamente:

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(())
}

Añade a tu Cargo.toml:

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

Los binarios precompilados para Windows, macOS (Intel y Apple Silicon) y Linux están disponibles en la página de GitHub Releases, o descárgalos mediante:

python scripts/fetch_cpipe.py

🤝 Transferencia A2A (Agente a Agente)

Al encadenar agentes, usa pipe_agent_handoff para destilar la salida del Agente A antes de que entre en la ventana de contexto del Agente B. Funciona con cualquier marco: no se requiere 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",
)

También está disponible como herramienta MCP: pide a tu asistente de IA: "Ejecuta pipe_agent_handoff() para destilar esta salida de agente antes de pasarla."

Firma de la función:

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: ...

Siempre devuelve el output original sin cambios ante cualquier error: la cadena de agentes nunca se interrumpe.

💻 Uso en terminal (CLI `mcp-pipe`)

Context-Pipe incluye un ejecutor de terminal de primera clase — mcp-pipe — para que puedas usar todas las capacidades sin un IDE ni un 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

El punto de entrada mcp-pipe se registra automáticamente cuando pip install mcp-context-pipe. Usa cpipe como abreviatura después de ejecutar mcp-pipe aliases install.

Registro MCP en la sombra

Cada servidor MCP que añades a un IDE registra sus herramientas globalmente: todas aparecen en la lista de herramientas del agente, las necesite o no. A escala, esto causa hinchazón de herramientas MCP: cientos de herramientas en el prompt, tokens desperdiciados en cada llamada de inferencia y una mayor probabilidad de que el agente elija la incorrecta.

context-pipe adopta un enfoque diferente. En lugar de registrar cada herramienta de procesamiento de contexto como una herramienta MCP de primera clase, expone una única herramienta de descubrimiento — pipe_list_shadow_tools — que devuelve un manifiesto de capacidades en vivo bajo demanda. Las herramientas permanecen ocultas ('sombra') hasta que el agente las solicita. Una herramienta MCP hace el trabajo de muchas.

Lo que incluye el manifiesto:

Pipes pipes.json — cada pipe con nombre configurado en tu proyecto.
Herramientas PATH seleccionadas — sondea 7 herramientas CLI conocidas (jq, yq, markitdown, pandoc, rg, fd, bat) y muestra cualquier que se encuentre en PATH.

Limitación conocida: las herramientas en la sombra no se pueden llamar como herramientas MCP independientes: el agente debe enrutarlas a través de pipe_run o pipe_run_dynamic. Esto es por diseño (mantiene la superficie MCP mínima), pero significa que el agente no puede llamar a jq o markitdown directamente sin construir un nodo de pipe dinámico.

Acceso desde terminal mediante mcp-pipe: el mismo manifiesto está disponible sin un IDE ni un servidor MCP: mcp-pipe list imprime cada pipe y herramienta PATH seleccionada en stdout. Canaliza cualquier contenido a través de una herramienta en la sombra directamente desde la 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 de nodo avanzados

Context-Pipe admite más que simples binarios. Puedes encadenar herramientas estándar del sistema operativo y mandatos expertos.

1. Nodos Bash (en sandbox)

Ejecuta comandos de shell arbitrarios como parte de tu pipe. Por diseño, todos los comandos se ejecutan de forma nativa con shell=False para prevenir vulnerabilidades de inyección.

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

2. Nodos de Script

Ejecuta un script específico del proyecto (Python/Shell) o un conjunto de instrucciones local. Se resuelve desde .gemini/scripts/ (por defecto).

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

3. Nodos T-Pipe (División de flujo)

Guarda una copia sin procesar del flujo en disco antes de que un nodo lo destile, sin interrumpir la cadena. Útil para depurar la calidad del pipe y auditar lo que se tamizó.

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

path admite tokens {iso_date} (YYYY-MM-DD) y {tool_name}. Un fallo de tee nunca interrumpe la cadena principal.

4. Nodos MCP

Llama a cualquier herramienta MCP como nodo de pipe. Sin scripts envoltorio: el orquestador inicia el servidor MCP, llama a la herramienta y pasa el resultado aguas abajo mediante stdout.

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

Las definiciones de servidor viven en un bloque servers en pipes.json o ~/.mcp-pipe.json. Consulta doc/MCP_NODE_SPEC.md para la especificación completa.

5. Nodos Validador (Fase 11)

Un validador ejecuta un subproceso y enruta según su código de salida en lugar de fluir linealmente. Úsalo para construir pipelines auto-reparables que intenten corregir problemas automáticamente antes de fallar.

{
  "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"] }
    ]
  }
}

Salida 0 → el linting pasó, salta a done (destila el informe limpio).
Salida 1 → el linting falló, salta a auto-fix (ejecuta --fix, luego destila).
"default" captura cualquier otro código de salida (por ejemplo, 2 para errores de configuración de ESLint).
El stdout del validador se reenvía como entrada a la secuencia objetivo.

6. Claves de condición (Fase 11)

Cualquier nodo puede omitirse condicionalmente sin modificar la definición del pipe:

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

El nodo solo se ejecuta si la entrada actual supera los 8 000 bytes. Predicados admitidos:

Predicado	Ejemplo	Cuándo se ejecuta el nodo
`size:>N`	`size:>10000`	Longitud de entrada > N bytes
`size:<N`	`size:<500`	Longitud de entrada < N bytes
`artifact:exists:<path>`	`artifact:exists:dist/app.js`	El archivo existe en disco
`artifact:missing:<path>`	`artifact:missing:output/report.md`	El archivo NO existe
`contains:<string>`	`contains:ERROR`	Los primeros 300 caracteres contienen la subcadena

Los predicados desconocidos fail-open (advierten y ejecutan el nodo) para evitar bloquear silenciosamente los pipelines.

🔗 El Ecosistema (Studio of Two)

Context-Pipe es un miembro fundacional de la infraestructura Studio of Two. Está diseñado para trabajar en armonía de alta fidelidad con:

Semantic-Sift: La refinería inteligente para el contexto agéntico. Sift es el motor de destilación insignia de Context-Pipe, que proporciona los nodos de tamizado matemático y neuronal utilizados en nuestras plantillas estándar.
std-context-lab: El laboratorio de integración oficial y campo de pruebas. Este repositorio sirve como nuestro campo de pruebas aislado donde se simulan y verifican capacidades entre repositorios, combinaciones de servidores MCP e interacciones de enlaces de terminal.
- Escenarios aislados: Ejecuta casos de prueba aislados que imitan comportamientos reales de IA para reproducir y verificar correcciones sin contaminar los tiempos de ejecución principales.
- Evidencia empírica: Cada error o característica resuelta va acompañada de un registro de ejecución rastreado (EVIDENCE.md), que sirve como prueba empírica de éxito.
- Puerta de paridad de plataforma: Audita la paridad de CLI de Python/Rust y los comportamientos de shell en terminales Windows (PowerShell/CMD) y UNIX antes del lanzamiento.

🧩 Sinergias y Límites de Herramientas

Cuatro herramientas suelen aparecer juntas en una pila de Studio of Two. Son complementarias, no superpuestas — cada una posee una capa distinta.

Herramienta	Capa	Rol principal	Relación
context-pipe	Orquestación	Enruta contenido a través de pipes con nombre; gestiona la ejecución de nodos, tiempos de espera, T-pipe, telemetría y traspaso A2A.	El conmutador. Llama a todas las demás herramientas como nodos cuando están conectadas.
semantic-sift	Destilación	Compresión heurística + neuronal de texto. Elimina ruido (marcas de tiempo, texto repetitivo, tokens repetidos) mientras preserva la señal.	CLI y servidor MCP totalmente independientes. El nodo de refinería insignia dentro de los pipes de context-pipe.
context-mode	Indexación en sesión	Búsqueda de texto completo BM25 sobre contenido indexado durante la sesión actual del agente. Recuperación rápida sin base de datos vectorial.	Servidor MCP totalmente independiente. Opcionalmente conectado como nodo `mcp` para indexar o buscar dentro de un pipe.
Serena	Inteligencia de código	Búsqueda de símbolos respaldada por LSP, refactorización y navegación de código. Entiende el AST, no solo texto.	Servidor MCP totalmente independiente. Opcionalmente conectado como nodo `mcp` para alimentar símbolos de código precisos en un pipe en lugar de lecturas de archivos sin procesar.

Cuándo usar cada una

Usa context-pipe cuando necesites orquestar: encadenar herramientas, aplicar pipes automáticamente en llamadas de herramienta, enrutar por disparador, guardar instantáneas de T-pipe, contabilizar el ROI o puentear traspasos de agentes.

Usa semantic-sift cuando necesites comprimir: un documento grande, un archivo de registro, un resultado de búsqueda o cualquier carga útil donde la relación ruido-señal sea alta. Se ejecuta de forma independiente mediante CLI o MCP, y como nodo dentro de los pipes de context-pipe.

Usa context-mode cuando necesites recuperar: ya has ingerido contenido en esta sesión y quieres una búsqueda BM25 rápida sobre él. Funciona de forma independiente como servidor MCP en cualquier IDE. Combínalo con semantic-sift en ambos lados: aguas arriba para comprimir contenido antes de indexar (índice más pequeño, búsqueda más rápida) y aguas abajo para destilar los fragmentos recuperados antes de que lleguen a la ventana de contexto.

Usa Serena cuando necesites navegar por el código: encontrar un símbolo, rastrear referencias, inspeccionar tipos o realizar una refactorización. Funciona de forma independiente como servidor MCP. Su salida estructurada y precisa es mucho mejor que una lectura de archivo sin procesar como entrada para cualquier herramienta posterior, incluido un pipe de tamizado.

Configuración complementaria — reducción del uso de tokens

Cada herramienta reduce de forma independiente la presión de tokens. Juntas, los ahorros se acumulan:

Serena devuelve solo el símbolo que pediste, no el archivo completo.
semantic-sift comprime el contenido antes de que entre en context-mode (índice más pequeño, búsqueda más rápida) y después de la recuperación (fragmentos sin ruido en la ventana de contexto).
context-mode devuelve solo los fragmentos indexados relevantes, no todo el corpus ingerido.
context-pipe garantiza que esta secuencia se active automáticamente y se contabilice, sin conexión manual por tarea.

El resultado: el agente trabaja con una fracción del volumen bruto de tokens, en cada sesión, sin cambiar cómo piensa ni qué herramientas llama.

Ejemplo 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

Las cuatro herramientas en un solo pipe. Cada una haciendo exactamente un trabajo.

⚙️ Variables de Entorno

Variable	Por defecto	Descripción
`PIPE_CONFIG_PATH`	`pipes.json`	Ruta absoluta al archivo de configuración `pipes.json` del proyecto.
`PIPE_NODE_TIMEOUT_MS`	`30000`	Tiempo de espera de ejecución por nodo en milisegundos.
`allow_shell`	`false`	Habilita nodos de comandos de shell arbitrarios en pipes dinámicos (herramienta MCP `pipe_run_dynamic` / API `run_dynamic_pipe()`). Requiere que el nodo final sea un comando de terminal `semantic-sift` para garantizar la seguridad del contexto.
`PIPE_LOG_LEVEL`	(ninguno)	Nivel de registro predeterminado del pipeline (`compact` o `verbose`). Habilita el registro para todos los pipes si se establece.
`PIPE_LOG_PREFIX`	`[PIPE]`	Texto predeterminado antepuesto a los registros de ejecución del pipeline en `stderr`.

⚠️ Limitaciones Conocidas

OpenCode — Intercepción de Salida de Herramientas MCP

La función de "interceptor subconsciente" (pipe_hook.py) funciona de forma transparente para Cursor, VS Code, Gemini CLI, Antigravity CLI y Claude Desktop al inyectar manejadores de hook que se activan después de cada llamada de herramienta.

OpenCode es la excepción. El hook tool.execute.after se declara en la interfaz Hooks del plugin de OpenCode, pero nunca se activa por el runtime de OpenCode (confirmado mediante auditoría de código fuente de session/processor.ts, session/llm.ts, tool/registry.ts, agent.ts). El código de mutación de salida del plugin es silenciosamente un no-op.

Solución actual: El mandato SOP AGENTS.md (pipe_read_file para todas las lecturas de archivos) es la estrategia de intercepción activa para OpenCode hasta que se admita la inyección transparente de hooks aguas arriba.

Problema aguas arriba: sst/opencode#21149
Problema del plugin: sst/opencode#25918
Rastreado en nuestro backlog: Fase 4.5 — ver doc/backlog.md

⚖️ Licencia

context-pipe está licenciado bajo la Apache License 2.0. Es un proyecto de "Código Abierto, Contribución Cerrada" mantenido por Studio of Two para garantizar la integridad arquitectónica.

Construyendo Infraestructura de Alta Fidelidad para la Era de la Inteligencia.