Phlow MCP Server

Phlow

ローカル環境で、範囲を限定したプランナー → コーダー → レビュアーのワークフローを実行します。実際のファイルツールと、ホストが強制する検証ゲートを備えています。デフォルトのバックエンドは Ollama です。CLI、ターミナル UI、MCP サーバーは単一の安全なランタイムを共有しており、従来の制限のないシェルや自動読み込みされるプラグイン経路は使用しません。

Flow は単独でも、Rose と双方向に連携しても動作します。Rose は MCP stdio 経由で Flow を呼び出し、Flow はプライベートな Neovim ソケット経由で Rose のネイティブエディターツールを呼び出します。

はじめに

必要なもの：Python 3.11 以降、uv、およびツール対応モデルをインストール済みの Ollama。Flow の安全なローカルファイル I/O には POSIX が必要です。主な対象は Linux と macOS です。

このチェックアウトから：

uv venv .venv
uv pip install --python .venv/bin/python -e '.[editor,dev]'

# In a separate terminal, if not already running:
ollama serve
ollama pull qwen2.5-coder:7b

# No model request or command execution; this also works without Ollama running:
.venv/bin/flow status --workspace /absolute/path/to/project

editor エクストラは、オプションの pynvim をインストールします。dev は pytest、Ruff、ホイールビルダーをインストールします。基本的な CLI／TUI ランタイムでは、エクストラを省略してください。依存関係はグローバルな Python インストールではなく、プロジェクト環境に追加してください。

チェックを承認してから実行する

たとえば flow-operator.toml のような、オペレーターが確認した TOML ファイルを作成します。ワークスペースの値は TOML テーブルヘッダーより前のルートに記述してください。

workspace_dir = "/absolute/path/to/project"

[ollama]
base_url = "http://127.0.0.1:11434"
model = "qwen2.5-coder:7b"
timeout = 120 # seconds

[models]
planner = "qwen2.5-coder:7b"
coder = "qwen2.5-coder:7b"
reviewer = "qwen2.5-coder:7b"

[agent]
max_iterations = 6      # model turns per role invocation
max_cycles = 2          # coder → verification → reviewer cycles
max_tool_calls = 64     # total across the entire run
max_context_chars = 100000

[checks.tests]
cmd = [".venv/bin/python", "-m", "pytest", "-q"]
timeout = 60000         # milliseconds, as in Rose
required = true
kind = "test"
filetypes = ["python"]

[checks.lint]
cmd = [".venv/bin/ruff", "check", "."]
timeout = 30000
required = true
kind = "lint"
filetypes = ["python"]

これらの実行ファイルは対象プロジェクトの環境内に存在している必要があります。Flow はプロジェクトの依存関係をインストールしたり、実行コマンドを選択したりしません。この Flow のチェックアウトでは、付属の config.toml に独自のテストと lint チェックが設定されています。

.venv/bin/flow check --config /absolute/path/to/flow-operator.toml --trusted
.venv/bin/flow run --config /absolute/path/to/flow-operator.toml --trusted \
  "Fix the failing parser tests and explain the changes"
.venv/bin/flow status --workspace /absolute/path/to/project
.venv/bin/flow tui --config /absolute/path/to/flow-operator.toml --trusted

run、check、status は、それぞれ 1 つの JSON オブジェクトを出力します。終了コード：ok の結果では 0、失敗または未検証の結果では 1、設定／使用法エラーでは 2、セッションの中断時は 130 です。共通フラグはコマンドの前後どちらにも指定できます。--workspace はランタイム／ツールの構築前に設定を上書きし、--model はすべてのロールの設定を上書きします。サブコマンドを指定せずに flow を実行すると、TUI が起動します。

TUI コマンド：/help、/status、/check [name]、/tools、/models、/model <installed-model>、/build <request>、/clear、/quit。Ctrl-D で終了します。自然言語によるタスクと /build は、同じ検証済みランタイムを使用します。タスクごとに、ロール別の新しいコンテキストが個別に用意されます。従来の /plugins、/evolve、/memory、/feedback は、安全でないヘルパーに暗黙的に接続されるのではなく、明示的に利用不可となっています。

「検証済み」の意味

実行が verified: true となるのは、次の条件をすべて満たす場合に限られます。

1. プランナー／コーダーが、それぞれの予算内に完了する。
2. 必須として指定された名前付きチェックが少なくとも1つ実行され、すべての必須チェックに合格する。
3. Flow を通じて変更されたすべてのソースファイルで、関連する静的解析に成功する。
4. 読み取り専用の別のレビュアーが、構造化された承認を返す。
5. 検証／レビュー中に編集済みファイルが変更されておらず、アタッチされたエディターバッファーに未保存の変更がない。

静的エビデンスとは、kind = "lint"、"typecheck"、または "diagnostics" と、対応する filetypes が設定された必須チェック、あるいは status="ok", verified=true を返す、完了済みのネイティブな Rose リンターです。kind="test"、"build"、"check" だけでは、静的な言語カバレッジを確立できません。編集するすべての言語を実際にカバーするチェックの場合に限り、言語名（"python"）、拡張子（".py"）、または明示的な "*" を使用してください。不明なソース拡張子は、その拡張子またはサフィックスをカバレッジキーとして使用できます。.md、.json、.toml などのドキュメント／データ拡張子には、名前付きゲートが引き続き必要ですが、ソース言語リンターは必要ありません。

すべての必須チェックが実行されます。filetypes はカバレッジを示すものであり、必須コマンドを暗黙にスキップすることはありません。任意のチェックも報告されますが、必須ゲートの代わりにはなりません。チェックは言語に依存しない厳密な argv であり、Rust、Go、TypeScript、C、Nix など、どの言語でも同じ仕組みを使用できます。npx によるダウンロードやパッケージマネージャーの自動インストールは推測して実行されません。

実行ファイル／チェックの不足、タイムアウト、無効なレビュアー出力、静的カバレッジの欠如、予算の超過は、成功とは見なされません。チェックの失敗やレビューでの問題は、次の上限付き修復サイクルに引き継がれます。レポートには、checks、verification.coverage、verification_history、変更されたファイル、役割／モデル／ターン数、ツール呼び出し ID／エラーが保持されます。キャッシュされた LSP 診断が空でも、それは単なるスナップショットであり、検証ではありません。実際のリンターが設定された範囲を個別に検証した場合でも、LSP がない場合は明示的に unavailable のままです。実際の診断エラーや古い結果がある場合、ネイティブカバレッジは無効になります。

これは、設定されたチェックの範囲内でのエビデンスであり、すべての動作、すべての言語、またはアプリケーション全体が正しいことの証明ではありません。

信頼とセキュリティ

• デフォルトのモードは読み取り専用です。--trusted を指定すると、プロジェクトの編集と、明示的に設定された名前付きチェックが許可されます。新たにモデルが選択したコマンドは許可されません。
• --config FILE を指定すると、そのオペレーター設定ファイルの読み込みが明示的に許可されます。ワークスペースの config.toml／.flow.toml は、--trusted を指定しても自動では読み込まれません。自動的にユーザー設定として読み込まれるのは、$XDG_CONFIG_HOME/flow/config.toml（デフォルトは ~/.config/flow/config.toml）のみです。
• モデルが制御するシェル、Python／Bash コードの実行、実行可能ファイルの引数、作業ディレクトリ、環境変数の上書き、削除ツール、プラグイン、Lua、Ex コマンドはありません。名前付きチェックでインタープリターを呼び出すことはできますが、その引数全体はオペレーター設定で固定され、実行前にスナップショットが作成されます。
• ファイルツールで指定できるのは相対パスのみです。親ディレクトリへの移動、絶対パス／Windows 形式のパス、.git、シンボリックリンク、ハードリンクが複数あるファイル、ルート外のパスは拒否されます。書き込みはアトミックに行われ、サイズ制限があり、ファイルディスクリプター相対で、シンボリックリンクをたどりません。ルートの置き換えは古い状態として検出されます。オペレーター設定はモデルのファイルツールから編集できません。
• ファイルの読み取り／書き込みは 256 KiB に制限されます。ディレクトリ一覧には上限があり、生成されたディレクトリは除外されます。ツールの出力とモデルの応答サイズにも上限があります。
• デフォルトの Ollama URL はループバックです。HTTP リダイレクトと環境変数で設定されたプロキシは無効です。ループバック以外のエンドポイントを使用するには、ollama.allow_remote=true を明示的に設定する必要があります。クラウドへのフォールバック、API キーの検索、自動的な外部検索はありません。
• 信頼されたプロジェクトのテスト／ビルド／リンターはコードを実行し、ユーザーとして OS、ネットワーク、ファイルにアクセスできます。名前付きコマンドは、プロジェクトの設定、プラグイン、フックを実行する場合があります。これはOS サンドボックスではありません。プロジェクトとチェックコマンドの内容を正確に確認し、信頼できないプロジェクトにはコンテナー／VM を使用してください。また、Flow を昇格した権限で実行しないでください。同じユーザーとして同時に動作する悪意のあるプロセスは、セキュリティ保証の対象外です。

従来の実行可能ファクトリーは、デフォルトで失敗するようになりました。以前のアプリケーションジェネレーター名とオーケストレーター名を使用するには、明示的に Runtime が必要です。従来の直接書き込み／テキストからシェルへの変換経路は廃止されました。バンドルされたプロンプト／プロファイルは flow/skills 内にインストールされ、パッケージリソースとして読み込まれます。プロジェクトの skills/ ディレクトリから暗黙的に読み込まれることはありません。

Rose 連携

同じ絶対ワークスペースと信頼設定を使用して、Rose のネイティブエントリーポイントを設定します。

require('rose').setup({
  workspace = '/absolute/path/to/project',
  trusted = true,
  ollama = { base_url = 'http://127.0.0.1:11434', model = 'qwen2.5-coder:7b' },
  flow = {
    cmd = { '/absolute/path/to/flow/.venv/bin/flow', 'serve',
            '--config', '/absolute/path/to/flow-operator.toml' },
    bridge = true,
    timeout = 300000, -- milliseconds; budget for the complete bounded run
  },
})

Rose はワークスペース／信頼設定のフラグを追加し、リバースブリッジ用のプライベートソケットを起動して渡します。手動実行でも同じインターフェースを使用します。

flow serve --workspace /absolute/root --trusted \
  --config /absolute/operator.toml --nvim /private/directory/nvim.sock \
  --editor-timeout 120

ソケットは明示的に指定し、同一ユーザー専用のプライベートなものにする必要があります。POSIX では、親ディレクトリを 0700 にするか、グループやその他のユーザーからアクセスできないソケットを使用してください。TCP は拒否されます。Neovim ソケットを使用すると、同一ユーザーの他のクライアントから任意のコードを実行できるため、プライベートに保ってください。Flow が送信するのは、固定の式である return require('rose.tools').schemas() と return require('rose.tools').call(...) のみで、名前と引数はパラメーターとして渡します。

エディターのスキーマは動的に検出され、editor_context、 editor_diagnostics、editor_symbols、editor_references、editor_lint、 editor_check、editor_scip、editor_debug に絞り込まれます。 デバッグの起動／プローブは引き続き手動で行います。エージェントに表示されるのは editor_debug の状態のみです。プランナー／レビュアーには読み取り専用のツールが渡され、チェック／リントや書き込みのツールは渡されません。

バッファーの安全性を確保するため、リバースブリッジでは固定の file_read および file_write 呼び出しも許可リストに登録されています。Flow はまずパス、信頼設定、ロール、サイズ、保護対象の設定を検証し、Rose の解決済みワークスペースと一致することを確認してから、Rose のバッファー対応 I/O を使用します。未保存または読み取り専用のバッファーは上書きされません。読み込み済みのバッファーは、ディスクへの書き込みと同期されます。ブリッジを利用できない場合や一致しない場合に、安全でないディスク書き込みへフォールバックすることはありません。名前付きチェックは、未保存のバッファーがある場合は実行を拒否します。Rose のエディターコンテキスト鮮度 API v1 が必須です。Flow はグローバルなダーティバッファーリストを確認し、チェックとレビューを通じて、現在のバッファー以外も含む読み込み済み／観測済みのワークスペーススナップショットを比較します。鮮度フィールドが欠落している場合は、安全側に倒して処理を拒否します。

pynvim はアタッチ前にメインスレッドでインポートされます（pynvim はインポート時にシグナル所有スレッドを記録するためです）。接続の作成、リクエスト、終了処理は、1 つの所有ワーカー上で行われます。エディターリクエストのタイムアウトはデフォルトで 120 秒で、0.1～660 秒の範囲で設定できます。モデルとチェックのタイムアウトでは、単位がそれぞれ異なります。SCIP のサポートでは、Rose が提供するデコード済み JSON を使用し、生の protobuf デコードは行いません。リバースの flow_run 呼び出しは公開されません。

MCP ワイヤーコントラクト

改行ごとに UTF-8 の JSON-RPC 2.0 オブジェクトを 1 つ送信します。Content-Length によるフレーミングは使用しません。 プロトコルは 2025-11-25 です。互換性のある日付 2025-06-18 と 2025-03-26 も受け付けます。 tools/list または tools/call の前に、initialize、続いて notifications/initialized を送信してください。ping は常時利用できます。

ツール	引数
flow_status	{}
flow_run	{"task":"..."}
flow_check	{} または {"name":"configured-name"}

ツールの応答には、content=[{type:"text",text:"<JSON report>"}]、 structuredContent=report、および結果が ok でない場合の isError が含まれます。MCP ツールリストには、意図的にこの 3 つのツールのみが含まれます。標準出力はプロトコル専用です。診断情報には標準エラー出力を使用します。解析／メソッド／パラメーターのエラーでは、有効な場合は JSON-RPC ID が保持されます。フレームが大きすぎる場合は、エラーの後にセッションを終了します。

このサーバーは、デバイス上で動作するよう意図的に逐次処理を行います。実行中のリクエストでは、notifications/cancelled を協調的に処理しません。キャンセルするには、Flow セッションを終了してください（RoseStop）。SIGTERM／KeyboardInterrupt により、実行中のチェックのプロセスグループのクリーンアップが行われ、エディタークライアントが閉じられます。その後、再接続してください。すでに保存された編集はロールバックされません。アイドル状態のセッションは EOF で終了します。ビジー状態のリクエストは、スーパーバイザーによって終了されない限り、設定された上限時間内に完了します。この標準入出力トランスポートにはクライアントスーパーバイザーが必要です。標準出力を systemd ジャーナルにリダイレクトして、ネットワークデーモンのように見せかけることはできません。

開発と検証

uv pip install --python .venv/bin/python -e '.[editor,dev]'
.venv/bin/pytest -q
.venv/bin/ruff check flow tests
.venv/bin/python -m compileall -q flow
.venv/bin/python -m build --wheel --no-isolation

# Include real headless editor tests when Neovim is not on PATH:
NVIM=/absolute/path/to/nvim .venv/bin/pytest -q

テストでは、決定論的な偽バックエンド、ローカルの偽 HTTP Ollama エンドポイント、実際の CLI/MCP サブプロセス、オプションの実際のヘッドレス Neovim を使用します。役割の分離、修復の上限、検証、ツール ID／エラー、信頼性／設定／パスのリグレッション、タイムアウト／プロセスのクリーンアップ、バッファーブリッジ、チェックアウト外から読み込まれる wheel リソースを対象としています。Neovim 固有のテストでは、実行可能ファイルがない場合にスキップしたことが報告されます。 実際の Ollama 推論／GPU 品質テストは保証していません。実際のモデルは不適切な編集を選んだり、割り当てられた予算を使い切ったりする可能性があります。生成されたレポートと差分を確認してください。

Nix 式は残されていますが、この環境ではビルドされていません。

ライセンス

このプロジェクトは Apache License, Version 2.0 の下でライセンスされています。