secureFlows MCP サーバー

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

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

MCPサーバーとは？

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

このリポジトリでは:

• secureFlows MCPサーバーは、OpenAPI YAML仕様から自動生成されたツールを公開します。

• クライアントがツールを呼び出すと、MCPサーバーはその呼び出しを実際のsecureFlowsバックエンド（connection.host）に転送し、応答を正規化されたツール結果として返します。

これにより、AIクライアントは以下のことが可能になります:

• listTools による利用可能なsecureFlowsオペレーションの検出

• callTool によるそれらの呼び出し

• APIサーフェスや認証・ヘッダー配線をハードコードする必要なし

機能

2種類のツールが src/server.ts にまとめて登録されています:

生成ツール (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 — 生成されたアプリのソースコードを統合ルールに照らしてチェックし、エージェントが自己検証するための散文として残すのではなく、構造化された検出結果を報告します。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 のエージェント実装チェックリストの代わりになるものではありません。

これらの静的ツールが存在するのは、生成ツールではセッションが存在する前に発生する統合部分（リダイレクト/コールバック/トークンライフサイクルコードの足場作り）を支援できないためです。これは、secureFlows統合のミスのほとんどが発生する場所です。

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

ランタイムモデル

各ツール呼び出しは以下を受け取ります:

• connection.host: secureFlowsベースURL

• connection.workspaceName: オプションのデフォルトワークスペース

• connection.appId: オプションのデフォルトアプリケーションID

• auth.*: 選択したエンドポイントが必要とするトークン

workspaceName と appId は安定したアプリ設定として扱われます。呼び出し元が省略した場合、サーバーはこれらを既知のsecureFlowsリクエストシェイプに注入します。

エージェント向け（サポートされている唯一のクライアントパス）

MCPクライアントをホスト型URL（製品と同じホスト、パスは /mcp。サブドメインではありません）にポイントします:

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

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

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

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コンテナでは、エントリポイントがMCP子プロセスにのみ PORT=8787 を設定し、nginxがRenderのパブリックな $PORT を保持できるようにします）

• 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の埋め込み

製品アプリは、このサーバーを介さず、上記の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.* を指定して POST /mcp に対してMCPクライアントを実行します。

デプロイ

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

npmパッケージ secureflows-mcp-server は、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