secureflows-mcp

secureFlows MCP サーバー

ai-safe および ai-optional タグが付いた secureFlows の OpenAPI サーフェスをラップする、クラウドにデプロイ可能な MCP サーバーです。

このリポジトリは、開発が実際に行われている非公開の secureFlows モノレポから定期的に公開されるパブリックミラーです。 Issue や PR は歓迎します。大規模な変更は、まず上流でリリースサイクルを経て取り込まれる場合があります。

MCP サーバーとは？

MCP サーバーは、AI クライアントが標準的な方法で呼び出せる一連の「ツール」を公開する、小規模な HTTP サービスです。

このリポジトリでは：

• secureFlows MCP サーバーは、OpenAPI YAML 仕様から自動生成されたツールを公開します。
• クライアントがツールを呼び出すと、MCP サーバーはその呼び出しを実際の secureFlows バックエンド（connection.host）に転送し、正規化されたツールの結果を返します。

これにより、AI クライアントは次のことができます：

• listTools で利用可能な secureFlows の操作を検出する
• callTool で操作を呼び出す
• API サーフェスをハードコーディングしたり、認証やヘッダーを手動で設定したりする必要はありません

このサーバーの機能

src/server.ts で2種類のツールをまとめて登録します。

生成ツール（src/tools/build-tools.ts） — OpenAPI の操作ごとに1つ：

• 次のファイルを読み込みます：
  • docs/openapi/session/secure-flows-session-api.yaml
  • docs/openapi/user/secure-flows-user-api.yaml
  • docs/openapi/docs/secure-flows-docs-api.yaml
• ai-safe または ai-optional タグが付いた操作のみを MCP ツールとして公開します
• 呼び出し元が指定した secureFlows ホストにリクエストを転送します。これは、secureFlows 固有の判断を含まない、薄い汎用 HTTP ラッパーです。これらはすべて有効な auth.* トークンを必要とするため、セッションがすでに存在する場合にのみ役立ちます（下記の実行時モデルを参照）。
• MCP ツールの入力から secureFlows の認証ヘッダーをマッピングします：
  • auth.firebaseToken
  • auth.sessionToken
  • auth.userToken

静的ツール（src/tools/static-tools.ts） — 仕様から生成するのではなく、手作業で作成します：

• secureflows_build_login_url / secureflows_build_logout_url — ホスト型ログイン URL とリダイレクトログアウト URL を、常に正しい形式で構築します（常に /app/sessions/login を使用し、旧式の /app/login は使用しません。ログアウト後の redirect_uri が /callback を指す場合や session_token が漏えいする場合は拒否します）。secureFlows トークンは不要です。
• secureflows_lint_integration — 生成されたアプリのソースコードが統合ルールに従っているかを確認し、エージェント自身に prose を監視させるのではなく、構造化された検出結果を報告します。secureFlows トークンは不要です。検出結果は次の2種類です：
  • scope: "file" — 禁止された構文が正確な file:line に存在します：環境変数の設定定数、localStorage 内のトークン、旧式の /app/login、ログアウト時の fetch／XHR、クライアント側の JWT デコード、サインアウト時のトークン失効、空の catch {}、認証以外のエラーでの setSession(null) による復元、session === null によって制御される Continue CTA、…
  • scope: "project" — 渡されたすべてのファイルで必須の処理が欠落しています：401／410 を検出してもトークンをクリアしない、403 を処理しない、または BILLING_GRACE_LOCK の例外処理なしで 403 を処理する場合です。 パターンルールでは、実際に生成されたアプリで最も多い種類の欠陥を構造上検出できないため、不在チェックが用意されています。実測では、実際の試行で、評価ハーネスのLLM判定者が4/10と評価したアプリについて、判定理由は「サインアウト時に古いトークンがクリアされない」「403の各種パターンが未処理」「エラー処理がない」でした。パターンルールだけでは、これらのバグはすべて存在しないものであり、正規表現では存在するものしか検出できないため、検出結果はゼロでした。不在チェックを加えると、error重大度のトークン消去チェックを含む3件が検出されます。どちらのチェックも、基準となるtemplates/web-app-secureflowsスターターに対して検証されており、検出結果が常にゼロでなければなりません。

それでもこれはヒューリスティックなテキスト解析であり、パーサーや型チェッカーではありません。ルールがないものは検出できず、プロジェクトチェックは適切なキーワードが誤った場所にあっても通過する場合があり、実行中のアプリが必要なチェック（認証ガードのマウント競合や、再読み込み後のチェックなど）には対応できません。これは最初の素早い確認であり、SKILL.mdにあるエージェント実装チェックリストの代わりではありません。

これらの静的ツールがあるのは、セッションが存在する前に行われる統合作業、つまりリダイレクト／コールバック／トークンのライフサイクルコードの足場作りには、生成されたツールでは対応できないためです。セキュアなFlowsの統合ミスの多くは、まさにこの段階で発生します。

プロンプト（src/prompts/security-review.ts） — security-reviewというMCPプロンプトが1つあります。現在のプロジェクトにおけるユーザーアカウントの管理方法をエージェントに確認させ、セキュリティ上の問題点を列挙し、それぞれをsecureFlowsに照らして評価したうえで、移行計画を作成します。読み取り専用で、secureFlowsトークンは不要です。同じテキストは、Claude Codeプラグインのスキルskills/security-review（/secureflows:security-reviewで実行）および、https://www.secure-flows.com/docs/getting-started/security-review/ にあるコピー＆ペースト用プロンプトとしても提供されています。TypeScriptの定数が原本であり、test/security-review-prompt.test.tsは、どちらかのコピーが原本と異なると失敗します。

ステートレスなHTTP MCPトランスポートを使用するため、サーバーはテナント設定やシークレットを保持しません。

ランタイムモデル

各ツール呼び出しでは、次の情報を受け取ります。

• connection.host：secureFlowsのベースURL
• connection.workspaceName：省略可能なデフォルトワークスペース
• connection.appId：省略可能なデフォルトアプリケーションID
• auth.*：選択したエンドポイントで必要なトークン

workspaceNameとappIdは、安定したアプリ設定として扱われます。呼び出し元から指定されなかった場合、サーバーはこれらを既知のsecureFlowsリクエスト形式に挿入します。

エージェント向け（サポートされる唯一のクライアント接続方法）

MCPクライアントには、ホスト型URLを指定します。製品と同じホストで、パスはサブドメインではなく/mcpです。

環境	MCP URL
本番環境	https://www.secure-flows.com/mcp
ステージング	https://secure-flows-staging.onrender.com/mcp
ヘルスチェック	…/mcp/health → {"ok":true}

{
  "mcpServers": {
    "secureflows": {
      "url": "https://www.secure-flows.com/mcp"
    }
  }
}

エージェントにnpxの実行やlocalhostの使用を指示しないでください。説明が分断され、ローカルプロセスを一度も起動しない利用者が使えなくなります。Web Dockerイメージに組み込まれています（Nodeは127.0.0.1:8787、nginxはlocation = /mcp。docs/ROUTING.mdを参照）。NodeプロセスはuncaughtException／unhandledRejectionガードを設定しているため、単一の不正なリクエストでプロセスが終了することはありません。それでもプロセスが終了した場合は、docker/entrypoint.shがMCPを再起動します。

Claude Codeプラグイン

このリポジトリはClaude Codeプラグインでもあります。上記のホスト型MCPサーバー（.mcp.json）に接続し、secureflows-integrationとsecurity-reviewの2つのスキルを追加します。Claude Codeでは、次のようにします。

/plugin marketplace add michal-lefler/secureflows-mcp
/plugin install secureflows@secureflows-marketplace

次に、任意のプロジェクトで/secureflows:security-reviewを実行すると、そのプロジェクトのユーザー管理を読み取り専用で確認できます。

ローカル開発（このパッケージのメンテナー向け）

cd mcp-server
npm install
npm run build
npm test
npm run dev

サーバーはデフォルトでhttp://0.0.0.0:8787（POST /mcp、GET /health）で起動します。これはMCPサーバー自体を変更するための設定であり、製品のエージェントが設定すべき接続方法ではありません。

環境変数

• PORT：HTTP ポート。デフォルトは 8787 です（Web コンテナでは、nginx が Render の公開 $PORT を維持できるよう、エントリーポイントが MCP の子プロセスにのみ PORT=8787 を設定します）。
• HOST：バインドするホスト。デフォルトは 0.0.0.0 です（Web コンテナでは 127.0.0.1 を使用します）。
• ALLOWED_HOSTS：MCP のホストヘッダー検証に使用する、任意のカンマ区切りホスト許可リストです。
• MCP_ALLOWED_HOSTS：イメージ内プロセスの起動時に ALLOWED_HOSTS を上書きするエントリーポイント用の変数です。

エンドポイント

• POST /mcp：MCP Streamable HTTP エンドポイント
• GET /health：ヘルスチェック（nginx 経由で GET /mcp/health として公開されます）

アプリケーションへの secureFlows の組み込み

製品アプリは、secureFlows HTTP API とホスト型ログインを直接使用します。以下から始めてください。

• docs/integration/quickstart.md — プロビジョニング（ワークスペースとアプリケーション）および実行時のホスト型ログイン
• docs/integration/CONCEPT.md — 基本的な順序：高度な機能を使う前に、ログイン → ワークスペースを作成
• docs/openapi/integration-auth.yaml — セッションアプリ向けの**/app/sessions/login** と、レガシー／コンソール向けの /app/login

製品アプリは引き続き、上記の HTTP API と直接連携し、このサーバー経由では連携しません。ここにある生成されたツールは、すでにトークンを持つエージェントや自動化（テスト、スクリプトによる検証）向けです。静的なツール（secureflows_build_login_url、secureflows_build_logout_url、secureflows_lint_integration）はトークン不要で、連携の足場を構築している段階のコーディングエージェントが呼び出すことを想定しています。前述の機能を参照してください。

この MCP サーバーのテスト

1. mcp-server/ で npm test を実行します。ユニットテストに加えて HTTP スモークテスト（test/http-smoke.test.ts）も実行します。 Express アプリを一時ポートで起動し、GET /health、GET /mcp → 405、および実際の Streamable-HTTP クライアントによる listTools と callTool(secureflows_build_login_url) を確認します。
2. デプロイ後：Playwright の tests/smoke/mcp-health.spec.ts が、対象ホストの公開エンドポイント GET /mcp/health と GET /mcp にアクセスします（本番スモークジョブ）。
3. ローカルでのメンテナー作業：npm run dev を実行し、その後 curl -sS http://127.0.0.1:8787/health を実行します。
4. 任意：生成されたツールを使う場合は、connection.host と auth.* を指定して、MCP クライアントから POST /mcp に接続します。

プラグインの配布も npm test でテストされます（オフライン。モノレポ専用のチェックはパブリックミラーでは自動的にスキップされます）。

• test/plugin-distribution.test.ts — マニフェスト、ホスト型 .mcp.json の配置先、ドキュメントページと README のインストールコマンド、および sync-public-mirrors CI ジョブ（タグのみで実行され、npm の公開完了を待機し、secrets: inherit を使用し、トークンはステップの環境変数内でのみ使用します）。
• test/mirror-sync.test.ts — 実際の scripts/sync-public-mirrors.mjs --commit --push をローカルのベア Git リポジトリに対して実行し、第三者が受け取る内容を確認します。対象はプラグイン、マーケットプレイス、スキル、ホスト型 .mcp.json、レジストリの server.json、再実行時の冪等性、削除の反映です。
• npm run test:live（任意で実行。SECUREFLOWS_LIVE_MCP=1 が必要）— .mcp.json 内の URL に接続してツール一覧を取得します。security-review プロンプトも必須にするには、SECUREFLOWS_LIVE_MCP_PROMPTS=1 を追加します。デプロイ後に実行してください（またはステージングで SECUREFLOWS_LIVE_MCP_URL を使用してください）。npm test には含まれないため、CI はオフラインのままです。

これらのテストでは確認できないこと：MIRRORS_PUSH_TOKEN を使った実際のプッシュ（GitHub でのワークフロー初回実行時）と、クリーンな Claude Code のインストール環境から実行する実際の /plugin marketplace add です。

デプロイ

Web Docker イメージに同梱され、www.secure-flows.com／ステージング環境の /mcp でプロキシされます（前述のエージェント向けを参照）。専用のサブドメインはありません。

npm パッケージ secureflows は、CI がバージョン付きアーティファクトを公開する方法（および mcp-server/Dockerfile からスタンドアロンコンテナをビルドする方法）です。エージェント向けのセットアップ手順ではありません。.github/workflows/publish-secureflows-mcp-server.yml を使い、v*.*.* タグで公開します。

docker build -f mcp-server/Dockerfile -t secureflows-mcp-server .
docker run --rm -p 8787:8787 secureflows-mcp-server

注意事項

• ホスト型のログイン／リダイレクトエンドポイントは、OpenAPI 仕様で ai-safe または ai-optional のタグが付けられている場合にのみ公開されます。
• ドキュメント検索（get_docs_search）は ai-safe で、auth.* は不要です。必要なのは connection.host とクエリ q のみです。
• 人間専用の管理コンソール API は意図的に除外されています。
• 各ツールのレスポンスペイロードには、次の内容が含まれます。
  • status
  • ok
  • url
  • headers
  • data