Context Pipe

⛓️ Context-Pipe

コンテキストエンジニアリングのユニバーサルスタンダード。

context-pipeは、Unixターミナルのパイピングから直接着想を得た高性能なオーケストレーションレイヤーです。コンピューティングにおいて最も長く使われ続ける構成プリミティブとなった、cmd1 | cmd2 | cmd3と同じ哲学に基づいています。ターミナルがstdin／stdoutのバイトストリームを介してプロセスを連結するのと同じように、Context-Pipeはコンテキストストリームを介してAIツール呼び出しを連結します。各ノードは1つの処理を行い、その出力を次に渡し、LLMには最終的に精製されたシグナルだけが渡されます。

これは比喩ではなく、文字どおりの拡張です。Context-PipeはMCPパイピング（オーケストレーターを介したMCPツール呼び出しの連結）とターミナルパイピング（stdinを読み込み、stdoutに書き込むバイナリ、シェルコマンド、スクリプトはすべて有効なノード）の両方をサポートします。2つのモードは、1つのパイプ定義内で自由に組み合わせられます。また、mcp-pipe CLIを通じて、ターミナル自体も拡張します。mcp-pipe toolサブコマンドを使えば、context-mode、serena、GitHub、Firecrawl、またはpipes.jsonに登録された任意のサーバーなど、あらゆるMCPサーバーをシェルから直接パイプとして実行できます。必要に応じて読み込まれ、ラッパースクリプトも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

現在、mcp-pipe run <pipe>を使うと、pipes.jsonで定義された名前付きパイプにターミナルから一級のアクセスができます。IDEが使うものと同じオーケストレーターを通じて、ターミナルのバイナリを組み合わせられます。

---

🚀 ビジョン

AI エージェントには、根本的なインフラの問題があります。すべてのツール呼び出しが、生の未加工出力をコンテキストウィンドウに直接返します。ログにはタイムスタンプが付いています。検索結果には定型文が含まれています。エージェントAの40KBの分析結果が、そのままエージェントBに渡されます。コンテキストウィンドウは埋まり、シグナルはノイズに埋もれ、LLMの性能は低下します。

context-pipeは、LLMが何かを見る前のインフラレイヤーでこの問題を解決します。

Studio of Twoの哲学では、パッチではなくシステムを構築します。パッチとは、ツールごとに用意するカスタムフィルターです。システムとは、あらゆるツールがstdinを読み込み、stdoutに書き込むことでノードになる、ユニバーサルプロトコルです。任意のノードの並びがパイプになります。すべてのパイプには名前が付き、バージョン管理され、監査可能で、あらゆるプロジェクトやエージェントフレームワークで再利用できます。

その結果、コンテキストのサプライチェーンが実現します。データは生の状態で取り込まれ、一連の精製工程（正規化 → フィルタリング → 圧縮 → 蒸留）を経て、高密度でシグナルの多いコンテンツとしてLLMに届きます。削減されたすべてのバイトは、Context Balance Sheetに記録されます。すべてのパイプ実行を追跡できます。すべてのA2Aハンドオフが保護されます。

これはsemantic-siftのラッパーではありません。あらゆる精製処理を組み合わせ可能、可観測、かつ本番環境に対応したものにするオーケストレーションレイヤーです。ノードには、バイナリ、シェルコマンド、Pythonスクリプト、または完全なMCPツール（Figma、GitHub、context-mode、あるいはpipes.jsonに登録された任意のサーバー）を指定できます。stdinを読み込み、stdoutに書き込むものなら、すべてパイプに組み込めます。

例 — ウェブをクロールして調査し、保存して公開する：

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

各ノードは実際のサブプロセスです。Tパイプはチェーンを中断することなく、任意の時点で生データのコピーを保存します。LLMには必要な情報だけが渡されます。また、入出力のすべてのバイト数と遅延時間が自動的にContext Balance Sheetに記録されます。

---

🛠️ コアコンポーネント

1. Context-Pipe プロトコル（CPP）

言語に依存しない標準で、ルールは 1 つです。ノードは stdin を読み取り、コンテンツを変換して stdout に書き込みます。この契約に従うバイナリ、シェルコマンド、Python スクリプト、MCP ツールは、すべて有効なノードです。プロトコルは doc/CONTEXT_PIPE_PROTOCOL.md で定義されており、意図的にシンプルに設計されています。SDK、登録、フレームワークとの結合は必要ありません。

2. オーケストレーション基盤（orchestrator.py）

ノードをパイプに連結する実行エンジンです。各ノードを実際の OS サブプロセスとして実行し、shell=False を強制しているため、インジェクションの攻撃対象領域はありません。機能には、ノードごとのタイムアウト制御（PIPE_NODE_TIMEOUT_MS）、T-Pipe のストリーム分割（ノードが処理する前に生の入力をディスクに保存）、完全なトレース記録（ノードごとの入出力サイズとレイテンシー）があります。

3. ユニバーサル・スイッチボード（pipes.json + マッピング）

データ駆動型のルーティングにより、3 種類のトリガー（ツール名（tool:regex）、ペイロードサイズ（size:>N）、デフォルトのフォールバック）に基づいて、最適なパイプを自動的に選択します。パイプ定義は pipes.json（プロジェクトレベル）と、必要に応じて ~/.mcp-pipe.json（グローバル。ローカルの設定を優先して統合）に保存されます。パイプの追加、変更、再ルーティングにコード変更は不要です。

4. MCP インターフェース（server.py + mcp-pipe CLI）

8 つの MCP ツールを通じて、すべての機能を AI アシスタントから直接利用できます。pipe_run、pipe_run_dynamic、pipe_read_file、pipe_analyze_file、pipe_list_shadow_tools、pipe_agent_handoff、get_pipe_stats、pipe_onboard です。mcp-pipe CLI も同じ機能を提供するため、ターミナル中心のワークフローでは IDE は不要です。Shadow Tool Discovery（pipe_list_shadow_tools）は、設定済みのパイプと、厳選された PATH 上のツール（jq、rg、markitdown、pandoc…）を組み合わせた、最新の機能マニフェストをエージェントに提供します。

5. サブコンシャス・インターセプター（pipe_hook.py + onboarding.py）

すべてのツール呼び出し後に、エージェントが明示的に pipe_run を呼び出さなくても、パイプを透過的に適用する IDE フックです。対応環境：Cursor（postToolUse）、VS Code/GitHub（フック）、Claude Code/Qwen/Codex（PostToolUse）、Windsurf、Cline（読み取り前のセキュリティゲートウェイ）、OpenClaw（ネイティブプラグイン）、pi.dev（ネイティブ TypeScript 拡張機能）。OpenCode では、AGENTS.md の SOP に従う方式が現在の戦略です（既知の制限事項を参照）。pipe_onboard を実行すると、すべてのフック、スラッシュコマンド（/pipe-run、/pipe-dynamic、/pipe-handoff、/pipe-stats）、エージェント向けの完全な SOP を一度に組み込みます。

6. A2A ブリッジ（a2a.py）

pipe_agent_handoff() は、エージェント A の出力を要約してから、エージェント B のコンテキストウィンドウに渡します。フレームワークに依存せず、モンキーパッチも不要です。CrewAI のタスクコールバック、Google ADK の転送フック、LangGraph のエッジ関数、その他のカスタム転送ポイントで動作します。Python 関数と MCP ツールの両方で利用できます。エラーが発生した場合は、元の出力を変更せずに返すため、エージェントの連携が中断されることはありません。

7. ネイティブ Rust コア（crates/cpipe）

cpipe は Context-Pipe エコシステムを支える高性能な Rust コアです。オーケストレーションエンジン全体（設定の統合、プレースホルダーの解決、ストリームのルーティング、自己認識型のバイパスガード）を、起動レイテンシー 2 ms 未満（Python ランタイムの 500 倍高速）のプリコンパイル済みネイティブバイナリに移植しています。Python サーバーと共存し、MCP ツールは Python（FastMCP）のまま利用できます。一方、Rust バイナリは Tauri サイドカー、スタンドアロン CLI（cpipe run、cpipe list、cpipe serve）、または Rust アプリケーションに直接組み込むための Cargo ライブラリとして利用できます。API の詳細は crates/cpipe/README.md を参照してください。

8. TypeScript/JavaScript クライアント（packages/cpipe-js）

@context-pipe/client は、エンジンをブラウザーで安全に使えるようサンドボックス化したクライアント側ポートです。Unix パイプをすべてメモリ内でシミュレートし、標準ノード（grep、replace）をサポートします。また、カスタム PWA ノードの登録（RAG データベースの検索、CORS プロキシ）に対応し、キャンセル用の AbortSignal と完全に統合されています。API と使用例の詳細については、packages/cpipe-js/README.md を参照してください。

---

✨ このツールの特長

機能	内容	参照先
AI 向け Unix パイプモデル	任意の stdin と stdout を持つツールを名前付きパイプに連結できます。バイナリ、シェル、スクリプト、MCP ツールのいずれも同じ契約で利用できます。	高度なノードタイプ
MCP ノードタイプ	任意の MCP ツール（Figma、GitHub、context-mode）を、ラッパースクリプトなしで第一級のパイプノードとして呼び出せます。	doc/MCP_NODE_SPEC.md
コンパイル不要のトポロジー	ルーティングはノードコードではなく pipes.json に記述されています。マップを編集するだけで、ルート変更、分岐、ノードの入れ替えができます。コード変更、再コンパイル、ノードの再デプロイは不要です。	doc/ARCHITECTURE.md
プロトコル優先の MCP 構成	サーバーキーを変更するだけで、任意の MCP サーバーを入れ替えられます。インポート、依存関係の宣言、ビルドサイクルは不要です。すべての MCP サーバーが同じプロトコルを使用するため、エコシステム全体をそのまま利用できる機能レイヤーとして扱えます。	doc/ARCHITECTURE.md
動的パイプ	AI エージェントは、pipe_run_dynamic を使って実行時にその場でノードリストを構築し、実行できます。pipes.json への登録は不要です。	動的パイプ
シャドウ MCP レジストリ	必要になるまで、ユーティリティ MCP サーバーをエージェントのツール一覧に表示しないようにできます。pipe_list_shadow_tools で必要なときに問い合わせます。	シャドウ MCP レジストリ
A2A エージェント引き継ぎ	Agent A の出力を要約してから Agent B のコンテキストウィンドウに渡せます。フレームワークに依存せず、モンキーパッチも不要です。	A2A 引き継ぎ
バージョン認識	pipe_verify と pipe_onboard で GitHub に基づく更新通知を事前に行い、環境の整合性を確保します。	ヘルスチェック
ストリームの整合性	UTF-8 以外のデータ（errors="replace"）への堅牢性と、null セーフな読み取りを備えた強化版オーケストレーションエンジンです。	doc/ARCHITECTURE.md
T-Pipe ストリーム分割	ノードの入力を要約する前に、その生データのコピーをディスクに保存できます。監査、デバッグ、品質測定に役立ちます。	3. T-Pipe ノード（ストリーム分割）
適応型ウィンドウ圧力	すべてのノードに残りのコンテキスト容量を通知します。semantic-sift はそれに応じて --rate を自動調整します。	環境変数
グローバル設定	すべてのプロジェクトでパイプ定義と MCP サーバーレジストリを共有できます。ローカルの pipes.json が常に優先されます。	doc/ARCHITECTURE.md
シェルエイリアスの追加	pipe_install_aliases により、シェルのプロファイルに mcp-pipe / cpipe が書き込まれます。venv を有効化せず、ターミナルからすぐに使えます。	ターミナルでの使用方法（MCP Pipe CLI）
Git 保護	pipe_onboard が .gitignore を自動更新し、内部アーティファクトがコミットされないよう保護します。	自動オンボーディング
コンテキスト収支表	すべてのパイプ実行について、入力文字数、出力文字数、ノードごとのレイテンシー、エージェントの帰属、純 ROI を記録します。	テレメトリーと ROI

---

🧠 アーキテクチャ：セマンティック列挙型（スキーマの肥大化を解決）

標準的な MCP のセットアップでは、複数の機能（PDF の解析、ログの検索、HTML のクリーニング）を公開するには、複数のツールを公開する必要があります。その結果、スキーマの肥大化が発生します。LLM のシステムプロンプトが、複雑なツールの指示で何千ものトークンに埋め尽くされるのです。小規模言語モデル（SLM）では、チャット履歴を押し出し、コンテキストウィンドウを圧迫し、ハルシネーションにつながります。

context-pipe は、セマンティック列挙型によってこの問題を解決します。 複雑なコマンドラインユーティリティの使い方を AI に教える代わりに、pipe_run(input, pipe_name) という単一のツールを公開します。pipe_name パラメーターは、事前定義したパイプラインの列挙型にすぎません（例：["parse-and-clean-pdf", "extract-critical-errors"]）。

これにより、意図と実行を完全に分離できます。

• LLM が意図を示します： 「この PDF のクリーンなテキストが必要なので、parse-and-clean-pdf パイプを呼び出します。」
• pipes.json が実行を指定します： [pandoc -> jq -> semantic-sift]

短く簡潔なパイプ名を使うことで、プロンプトを極限まで圧縮できます。AI は、ホストマシン上のすべてのユーティリティの取扱説明書を読む代わりに、操作するための高レベルな「ボタン」のメニューを受け取ります。さらに、バックエンドのツールをアップグレードしても（例：pandoc を markitdown に置き換えても）、LLM のプロンプトを更新する必要はありません。AI は同じパイプを呼び出し、背後のエンジンがより高速になるだけです。

---

🔧 独立して変化する3つの軸

CPP パイプラインでは、互いに完全に独立したサイクルで進化する3つのレイヤーに関心を分離します。

レイヤー	内容	変更方法
ノード	各ステップが行う処理。パイプライン全体を認識しない、単純な stdin／stdout ツールです	バイナリ、スクリプト、または MCP ツールを交換します
pipes.json	トポロジー。ステップの接続、分岐、ルーティングの方法です	マップを編集します。コード変更も再コンパイルも再デプロイも不要です
MCP サーバー	各ツール呼び出しを支える機能です	サーバーキーを変更します。インポート、依存関係の宣言、ビルドサイクルは不要です

ノードの品質を高めても、トポロジーは変わりません。ルーティングを再構成しても、ノードには影響しません。MCP サーバーをアップグレードすれば、そのサーバーを使うすべてのパイプがパイプラインの変更なしで自動的に改善されます。

**特に MCP ノードでは、**従来の依存関係モデルが完全に解消されます。すべての MCP サーバーは同じプロトコルを使います：JSON-RPC、tools/call、テキスト応答です。パイプが依存するのは、サービスを実装するものではなく、プロトコルを話すものです。したがって、MCP エコシステム全体がパイプの機能レイヤーとなります。同じセマンティックな役割を担うノードであれば、現在および将来のすべての MCP サーバーが、そのまま置き換え可能です。

スクリプトでは、インポートするものに依存します。パイプでは、プロトコルを話すものに依存します。

この分離により、ルーティングはコンパイル不要になります。従来のスクリプトでは、保護策や復旧ロジックがコードに組み込まれているため、ワークフローの復旧方法を変更するには、スクリプトの変更、テスト、再デプロイが必要です。CPP では、ルーティングは pipes.json にあります。分岐、ルート変更、ノードの交換は、設定の編集だけで済みます。*「これを別のルートにしたらどうなるか」から「実際に何が起きるか確認しよう」*までのフィードバックループは、ほぼゼロになります。

---

🚀 クイックスタート（60秒）

# 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

セットアップの完全なガイド（Sovereign Dual-Repo Pattern、venv の構成、IDE の設定）：doc/OPERATOR_GUIDE.md

---

🏗️ はじめに

1. インストール

オプション A：クイックインストール（PyPI）

MCP サーバーでは IDE の設定に明示的な Python 実行ファイルのパスが必要なため、まず仮想環境を作成する必要があります。

ℹ️ インストールされる内容： Context-Pipe のオーケストレーションレイヤーと、Semantic-Sift のコア Python サーバーがインストールされます。ほぼ瞬時にヒューリスティックな選別を行う sift-core Rust バイナリは PyPI ホイールに含まれているため、Rust ツールチェーンは不要です。[neural] エクストラを追加すると、大容量ペイロードのセマンティック圧縮用に PyTorch（約 1.5 GB）がインストールされます。

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

オプション B：Sovereign Pattern（Studio of Two におすすめ） 2 つのリポジトリを並べてクローンします。context-pipe の仮想環境が、両方のパッケージを格納するマスター環境として機能します。手順の全容は Operator's Guide のセクション 0 をご覧ください。

# 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

注： PyPI でのパッケージ名は mcp-context-pipe ですが、インストールされるモジュール名は context_pipe です。semantic-sift-cli バイナリは、semantic-sift を pip でインストールした仮想環境（上記のステップ 2）のみに登録されます。両方の pipes.json ファイルで、その絶対パスを参照する必要があります。

2. MCP を接続する

重要：Cursor、Gemini、Antigravity、OpenCode、VS Code、Claude の正確な設定パスについては、マスター設定マトリックス をご覧ください。

3. Refinery を接続する

Context-Pipe は「スイッチボード」ですが、データを精製する「Refinery」が必要です。Semantic-Sift は、このエコシステムを代表するインテリジェンスエンジンです。ヒューリスティックなふるいとニューラルモデル（BERT/ONNX）を使用して、シグナルの 95％を維持しながらノイズ（タイムスタンプ、定型文）を焼却します。

注： Sovereign Pattern では、semantic-sift は context-pipe/venv にクロスインストールされます（上記のステップ 2）。また、Context-Pipe は pipe_onboard または pipe_verify を通じて、既知のすべての場所（システム PATH、pipx、隣接する仮想環境ディレクトリ）に個別にインストールされた semantic-sift-cli を自動検出します。

4. インストールを確認する

両方のパッケージをインストールした後、AI アシスタントにスタック全体の確認を依頼します。

「pipe_verify() を実行して、インストールを確認してください。」

これにより、すべてのコンポーネントの状態が報告され、別の環境で見つかった場合は semantic-sift-cli が pipes.json に自動的にリンクされます。

5. 最初の Pipe を設定する

pipes.json（pipes.json.example を参照）を編集して、高忠実度のコンテキストストリームを定義します。

6. 自動オンボーディング

接続したら、AI アシスタントにワークスペースの設定を依頼します。

「pipe_onboard(environment='Cursor') を実行して、このプロジェクトを設定してください。」

environment を省略すると、pipe_onboard は IDE を自動検出します。環境変数と親プロセス名を調べて、12 以上のプラットフォーム（Cursor、Gemini、Antigravity、OpenCode、VS Code、Windsurf、Claude、Cline など）を識別します。自動検出で判断できない場合に限り、environment を明示的に指定してください。

---

📚 ドキュメント

詳しいドキュメントは doc/ ディレクトリにあります。

• doc/INDEX.md：ドキュメントエコシステムのナビゲーションロードマップです。
• doc/USE_CASES.md：Bash、Script Nodes、Semantic-Sift を連携させる方法を紹介する、実際の影響力の大きいシナリオです。
• doc/OPERATOR_GUIDE.md：セットアップ、ターミナルの習熟、pipes.json の設定に関する決定版ガイドです。
• doc/ARCHITECTURE.md：オーケストレーションの基盤とスイッチボードの技術仕様です。
• doc/CONTEXT_PIPE_PROTOCOL.md：ツールの相互運用性を実現する、言語に依存しない標準です。
• doc/INTEGRATION_ENCYCLOPEDIA.md：Cursor、VS Code、Gemini/Antigravity、Claude のマスター互換性マトリックスです。

---

🐍 プログラムからの使用方法

Python

Context-Pipe は、Python スクリプト、ノートブック、エージェントフレームワーク（LangChain、CrewAI など）に直接組み込める単一の pipe() 関数を提供します。MCP サーバーや 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)

関数シグネチャ：

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

この関数は、エラー（サブプロセスの失敗、設定の欠落など）が発生した場合、常に元の text を変更せずに返すため、置き換え可能なフィルターとして安全に使用できます。

JavaScript/TypeScript

クライアント側のランタイム（ブラウザー、PWA、拡張機能）では、サンドボックス化されたパッケージをインストールします：

npm install @context-pipe/client

PipelineEngine を初期化し、設定を実行します：

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

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

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

カスタムのデータベースノードやフェッチノードの登録、およびキャンセルの処理については、クライアント README を参照してください。

Rust ライブラリ（cpipe）

Rust または Tauri アプリケーションでは、ネイティブコアを直接組み込みます：

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

Cargo.toml に追加します：

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

Windows、macOS（Intel および Apple Silicon）、Linux 用のビルド済みバイナリは、GitHub Releases ページから入手するか、次のコマンドでダウンロードできます：

python scripts/fetch_cpipe.py

---

🤝 A2A（エージェント間）ハンドオフ

エージェントを連鎖させる場合は、pipe_agent_handoff を使用して、Agent A の出力が Agent B のコンテキストウィンドウに入る前に要約します。あらゆるフレームワークで動作し、モンキーパッチは不要です。

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",
)

MCP ツールとしても利用できます。AI アシスタントに「このエージェントの出力を次に渡す前に要約するため、pipe_agent_handoff() を実行してください」と指示してください。

関数シグネチャ：

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

エラーが発生した場合は常に元の output を変更せずに返すため、エージェントの連鎖が中断されることはありません。

---

💻 ターミナルでの使用（mcp-pipe CLI）

Context-Pipe には、IDE や MCP サーバーなしであらゆる機能を使える、専用のターミナルランナー mcp-pipe が含まれています。

# 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

mcp-pipe のエントリーポイントは、pip install mcp-context-pipe を実行すると自動的に登録されます。mcp-pipe aliases install を実行した後は、短縮形として cpipe を使用できます。

シャドウ MCP レジストリ

IDE に追加した MCP サーバーは、それぞれのツールをグローバルに登録します。そのため、エージェントが必要としているかどうかにかかわらず、すべてのツールがエージェントのツール一覧に表示されます。規模が大きくなると、これによりMCP ツールの肥大化が起こります。プロンプトに数百ものツールが並び、推論のたびにトークンが無駄になり、エージェントが間違ったツールを選ぶ可能性も高まります。

context-pipe は異なるアプローチを採用しています。コンテキスト処理ツールをすべて独立した MCP ツールとして登録するのではなく、オンデマンドで現在の機能マニフェストを返す単一のディスカバリーツール pipe_list_shadow_tools を公開します。エージェントが要求するまでは、ツールは非表示（「シャドウ」）のままです。1 つの MCP ツールで多数のツールの役割を果たします。

マニフェストに含まれるもの：

1. pipes.json のパイプ — プロジェクトで設定されている、名前付きのすべてのパイプ。
2. 厳選された PATH ツール — よく知られた 7 つの CLI ツール（jq、yq、markitdown、pandoc、rg、fd、bat）を調べ、PATH 上で見つかったものを表示します。

既知の制限事項： シャドウツールは独立した MCP ツールとして呼び出せません。エージェントは pipe_run または pipe_run_dynamic を介して実行する必要があります。これは意図的な設計です（MCP の公開範囲を最小限に抑えられます）が、動的パイプノードを構成しない限り、エージェントは jq や markitdown を直接呼び出せません。

mcp-pipe によるターミナルアクセス： 同じマニフェストを IDE や MCP サーバーなしで利用できます。mcp-pipe list を実行すると、すべてのパイプと厳選された PATH ツールが標準出力に表示されます。ターミナルから、シャドウツールにコンテンツを直接パイプできます：

# 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"]}]'

---

🔗 高度なノードタイプ

Context-Pipe は、単純なバイナリだけでなく、標準的な OS ツールや専門家向けの指示も連鎖できます。

1. Bash ノード（サンドボックス化）

パイプの一部として任意のシェルコマンドを実行します。インジェクションの脆弱性を防ぐため、すべてのコマンドは設計上、shell=False を指定してネイティブに実行されます。

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

2. スクリプトノード

プロジェクト固有のスクリプト（Python／Shell）またはローカルの指示セットを実行します。デフォルトでは .gemini/scripts/ から解決されます。

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

3. T-Pipe ノード（ストリーム分割）

ノードがストリームを要約する前に、ストリームの生データのコピーをディスクに保存します。チェーンを中断することはありません。パイプの品質をデバッグしたり、ふるい落とされた内容を監査したりする場合に便利です。

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

path は {iso_date}（YYYY-MM-DD）および {tool_name} トークンに対応しています。T 字分岐でのエラーによってメインチェーンが中断されることはありません。

4. MCP ノード

任意の MCP ツールをパイプノードとして呼び出します。ラッパースクリプトは不要です。オーケストレーターが MCP サーバーを起動してツールを呼び出し、結果を stdout 経由で後続に渡します。

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

サーバー定義は、pipes.json または ~/.mcp-pipe.json の servers ブロックに記述します。仕様の全文はdoc/MCP_NODE_SPEC.mdをご覧ください。

5. バリデータノード（フェーズ 11）

バリデーターはサブプロセスを実行し、直線的に処理を進める代わりに、終了コードに応じて処理を振り分けます。これを使うと、失敗する前に問題を自動修正しようとする自己修復型パイプラインを構築できます。

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

• 終了コード 0 → リントに合格した場合は done にジャンプします（クリーンなレポートを要約します）。
• 終了コード 1 → リントに失敗した場合は auto-fix にジャンプします（--fix を実行してから要約します）。
• "default" は、それ以外の終了コード（ESLint の設定エラーを示す 2 など）をすべて受け取ります。
• バリデーターの stdout は、ターゲットシーケンスへの入力として転送されます。

6. 条件キー（フェーズ 11）

パイプ定義を変更せずに、任意のノードを条件に応じてスキップできます。

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

現在の入力が 8 000 バイトを超える場合にのみ、ノードが実行されます。対応する述語は次のとおりです。

述語	例	ノードが実行される条件
size:>N	size:>10000	入力の長さが N バイトを超える
size:<N	size:<500	入力の長さが N バイト未満
artifact:exists:<path>	artifact:exists:dist/app.js	ファイルがディスク上に存在する
artifact:missing:<path>	artifact:missing:output/report.md	ファイルが存在しない
contains:<string>	contains:ERROR	先頭 300 文字に部分文字列が含まれる

パイプラインを意図せずブロックしないよう、未知の述語はフェイルオープンで処理されます（警告を表示してノードを実行します）。

🔗 エコシステム（Studio of Two）

Context-Pipe は、Studio of Two インフラストラクチャの基盤を成すメンバーです。次のプロジェクトと高度な調和を保って動作するよう設計されています。

• Semantic-Sift：エージェントコンテキストのためのインテリジェントな精製所です。Sift は Context-Pipe の主要な要約エンジンであり、標準テンプレートで使用される数学的・ニューラルなふるい分けノードを提供します。
• std-context-lab：公式の統合ラボ兼テスト用ゲートです。このリポジトリは、リポジトリ間の機能、MCP サーバーの組み合わせ、ターミナルフックの連携をシミュレーションおよび検証する、隔離された実戦テスト環境として機能します。
  • 隔離されたシナリオ：現実世界の AI の動作を模した隔離テストケースを実行し、コアランタイムを汚染せずに修正を再現・検証します。
  • 実証的な証拠：解決されたすべてのバグや機能には、成功の実証的な証拠となる、追跡可能な実行ログ（EVIDENCE.md）が付属します。
  • プラットフォーム同等性ゲート：リリース前に、Windows（PowerShell/CMD）と UNIX ターミナルにおける Python/Rust CLI の同等性とシェルの動作を監査します。

---

🧩 ツールの連携と役割の境界

Studio of Two スタックでは、4 つのツールが一緒に使われることがよくあります。これらは互いに補完し合うもので、役割は重複しません。それぞれが異なるレイヤーを担当します。

ツール	レイヤー	主な役割	関係
context-pipe	オーケストレーション	名前付きパイプ経由でコンテンツをルーティングします。ノードの実行、タイムアウト、T-pipe、テレメトリー、A2A ハンドオフを管理します。	配電盤です。接続すると、他のすべてのツールをノードとして呼び出します。
semantic-sift	蒸留	ヒューリスティックとニューラルによるテキスト圧縮を行います。シグナルを保ちながら、ノイズ（タイムスタンプ、定型文、繰り返しのトークン）を取り除きます。	単独で使える CLI および MCP サーバーです。context-pipe のパイプ内では、主要な精製ノードとして機能します。
context-mode	セッション内インデックス作成	現在のエージェントセッション中にインデックス化されたコンテンツを対象に、BM25 全文検索を行います。ベクトルデータベースを使わずに高速に検索できます。	単独で使える MCP サーバーです。必要に応じて mcp ノードとして接続し、パイプ内でインデックス作成や検索を行えます。
Serena	コードインテリジェンス	LSP を基盤としたシンボル検索、リファクタリング、コードナビゲーションを行います。テキストだけでなく AST を理解します。	単独で使える MCP サーバーです。必要に応じて mcp ノードとして接続し、ファイルをそのまま読み込む代わりに、正確なコードシンボルをパイプに渡せます。

どれを使うべきか

オーケストレーションが必要な場合は、context-pipe を使います。 ツールの連携、自動的なツール呼び出し時のパイプ適用、トリガーによるルーティング、T-pipe スナップショットの保存、ROI の計算、エージェント間のハンドオフを行えます。

圧縮が必要な場合は、semantic-sift を使います。 大きなドキュメント、ログファイル、検索結果など、ノイズとシグナルの比率が高いペイロードに適しています。CLI または MCP で単独実行でき、context-pipe のパイプ内ではノードとして動作します。

検索が必要な場合は、context-mode を使います。 このセッションですでにコンテンツを取り込んでおり、その内容を対象に高速な BM25 検索を行いたい場合に適しています。任意の IDE で MCP サーバーとして単独で動作します。検索の前後で semantic-sift と組み合わせることもできます。上流ではインデックス作成前にコンテンツを圧縮し（インデックスが小さくなり、検索が速くなります）、下流では取得したチャンクをコンテキストウィンドウに入れる前に蒸留します。

コードのナビゲーションが必要な場合は、Serena を使います。 シンボルの検索、参照の追跡、型の確認、リファクタリングに適しています。MCP サーバーとして単独で動作します。構造化された正確な出力は、そのままファイルを読み込むよりも、後続のあらゆるツールへの入力として優れています。シフティングパイプへの入力にも適しています。

相補的なセットアップ — トークン使用量の削減

各ツールは個別にトークンの負荷を軽減します。組み合わせることで、削減効果がさらに高まります。

• Serena は要求されたシンボルだけを返し、ファイル全体は返しません。
• semantic-sift は、コンテンツが context-mode に入る前（インデックスが小さくなり、検索が速くなります）と、取得後（ノイズを取り除いたチャンクをコンテキストウィンドウに渡します）にコンテンツを圧縮します。
• context-mode は、関連するインデックス済みチャンクだけを返し、取り込んだコーパス全体は返しません。
• context-pipe は、この一連の処理が自動的に実行され、記録されるようにします。タスクごとに手動で接続する必要はありません。

その結果、エージェントは考え方や呼び出すツールを変えることなく、毎回のセッションで生のトークン量を大幅に抑えて作業できます。

連携の例

[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

1 つのパイプに 4 つのツールをすべて組み込みます。それぞれが正確に 1 つの役割を担います。

---

⚙️ 環境変数

変数	デフォルト	説明
PIPE_CONFIG_PATH	pipes.json	プロジェクトの pipes.json 設定ファイルへの絶対パスです。
PIPE_NODE_TIMEOUT_MS	30000	ノードごとの実行タイムアウトをミリ秒で指定します。
allow_shell	false	動的パイプで任意のシェルコマンドノードを有効にします（pipe_run_dynamic MCP ツール／run_dynamic_pipe() API）。コンテキストの安全性を確保するため、最後のノードは semantic-sift の終端コマンドである必要があります。
PIPE_LOG_LEVEL	(none)	デフォルトのパイプラインログレベル（compact または verbose）です。設定すると、すべてのパイプのログが有効になります。
PIPE_LOG_PREFIX	[PIPE]	stderr に出力されるパイプライン実行ログの先頭に付加するデフォルトのテキストです。

---

⚠️ 既知の制限

OpenCode — MCP ツール出力のインターセプト

「サブコンシャスインターセプター」機能（pipe_hook.py）は、すべてのツール呼び出しの後に実行されるフックハンドラーを注入することで、Cursor、VS Code、Gemini CLI、Antigravity CLI、Claude Desktop で透過的に動作します。

OpenCode は例外です。 tool.execute.after フックは OpenCode プラグインの Hooks インターフェイスで宣言されていますが、OpenCode のランタイムでは一度も実行されません（session/processor.ts、session/llm.ts、tool/registry.ts、agent.ts のソース監査で確認済みです）。プラグインの出力変更コードは、何も通知せずに実質的な処理を行いません。

現在の回避策：透過的なフック注入が上流でサポートされるまで、AGENTS.md の SOP にある指示（すべてのファイル読み取りに pipe_read_file を使用する）が、OpenCode で有効なインターセプト戦略です。

• 上流の課題：sst/opencode#21149
• プラグインの課題：sst/opencode#25918
• 当社のバックログで追跡中：フェーズ 4.5 — doc/backlog.md を参照

---

⚖️ ライセンス

context-pipe は Apache License 2.0 のもとでライセンスされています。これは、アーキテクチャの整合性を確保するため、Studio of Two が保守する「オープンソース、クローズドコントリビューション」のプロジェクトです。

---

インテリジェンス時代に向けた高忠実度インフラストラクチャの構築。