SAP SuccessFactors マルチエージェント MCP プロトタイプ

合成の SuccessFactors 形式データを使用したデモンストレーション。 これは読み取り専用の教育用プロトタイプであり、SAP SuccessFactors システムでも本番稼働可能なものではありません。

このアプリケーションは、限定された MCP ツール境界を通じて、承認された HR の質問に回答します。モックモードでは SAP または OpenAI の認証情報は不要です。デモモードではオプションの OpenAI Agents SDK オーケストレーションを追加します。実モードは、明示的に設定された非本番 SuccessFactors テナント専用に予約されています。

機能

• 11 個の型付き読み取り専用 MCP ツール。任意の HTTP、OData、書き込みサーフェスはありません。

• サーバー側のロールと人口スコープを持つ 4 つの合成 ID。

• 明示的なエンティティおよびフィールドの許可リストと、デフォルト拒否のレスポンスサニタイズ。

• 10 人の架空の従業員、12 のポジション、基盤オブジェクト、有効日付履歴、欠員、意図的なデータ品質問題。

• 完全な HR ペイロードやシークレットを含まない構造化 SQLite 監査証跡。

• FastAPI チャット/監査 API と Streamlit のエビデンス重視インターフェース。

• API キーなしで動作する決定論的モックチャット。

Related MCP server: HRIS MCP Connector

Windows セットアップ（主要パス）

cd .\successfactors-mcp-prototype
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup_windows.ps1

すべてのサービスを実行:

.\scripts\run_all_windows.ps1

または 3 つのターミナルを使用:

.\scripts\run_mcp_windows.ps1
.\scripts\run_backend_windows.ps1
.\scripts\run_ui_windows.ps1

run_ui_windows.ps1 は、バックエンドがまだ実行されていない場合に FastAPI をバックグラウンドで自動的に起動するため、最もシンプルなワンコマンドのモック UI ランチャーとしても使用できます。

• UI: http://127.0.0.1:8501

• API: http://127.0.0.1:8000

• OpenAPI: http://127.0.0.1:8000/docs

• MCP: http://127.0.0.1:8001/mcp

Unix および VS Code

bash scripts/setup_unix.sh を実行し、次に bash scripts/run_all_unix.sh を実行します。VS Code では .venv を Python インタープリターとして選択し、必要に応じて 3 つのターミナルを開きます。

設定とモード

.env.example を .env にコピーします。プレースホルダーにはシークレットは含まれていません。

• APP_MODE=mock: 合成プロバイダーと決定論的チャット。外部認証情報は不要。

• APP_MODE=demo: ライブ Agents SDK オーケストレーションを備えた合成プロバイダー。OPENAI_API_KEY と MCP_INTERNAL_TOKEN が必要。

• APP_MODE=real: 設定済みのテストテナントのみ。設定が欠落していると起動に失敗します。モックへのフォールバックはありません。

OPENAI_MODEL はモデル選択を一元管理します。依存関係の範囲は Python 3.11 と現在の互換性のあるメジャーバージョンを対象とし、未レビューのメジャーアップグレードは回避します。

ライブ Agents SDK デモ

.env.example を .env にコピーし、次の値を設定します:

APP_MODE=demo
OPENAI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=your-key-from-a-secret-store
MCP_INTERNAL_TOKEN=a-long-random-local-secret

.env をコミットしないでください。run_ui_windows.ps1 は、必要に応じて MCP サーバーと FastAPI を起動するようになりました。 このアプリケーションは、保護された HTTP ヘッダーを通じてユーザー、セッション、および相関 ID を MCP に渡します。これらのフィールドは、モデルが呼び出し可能なツールスキーマには含まれません。スペシャリストにはハードコードされたツール許可リストが付与されます。UI トレースはエージェント/ツールのライフサイクル名のみを記録し、プロンプト、引数、結果、またはプライベートな推論は記録しません。

コスト管理は DEMO_MAX_TURNS、DEMO_MAX_OUTPUT_TOKENS、および DEMO_DAILY_TOKEN_BUDGET で設定されます。選択したモデルの現在のレートに OPENAI_INPUT_COST_PER_1M と OPENAI_OUTPUT_COST_PER_1M を設定すると、ローカル見積もりが表示されます。OpenAI トレースはデフォルトでオフになっており、有効にしても機密性の高いトレースコンテンツは無効のままです。

通常のスイートは OpenAI を呼び出しません。3 つのサービスすべてがデモモードで実行されている状態で、単一のオプトインのライブ委任スモークテストを実行するには:

$env:RUN_LIVE_AGENT_TESTS="true"
.\.venv\Scripts\python.exe -m pytest -m live -q

このテストは 1 回の実際の API リクエストを行うため、モデルの使用量が発生します。

検証

python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest

実テストテナントの認証設定

1. SuccessFactors API Center で OAuth クライアントを登録します。

2. 専用の API ユーザーを作成します。

3. 最小限の必要な RBP クエリ権限を割り当てます。

4. 対象人口を制限します。

5. 承認されたエンティティとフィールドにのみクエリアクセスを許可します。

6. OAuth 素材をソース管理外に保存します。

7. 非本番テナントに対してテナント固有の署名付き OAuth フローを検証します。

8. 許可された従業員シナリオと拒否された従業員シナリオの両方を検証します。

Basic 認証はサポートされていません。含まれている実トークンプロバイダーインターフェースは、テナント固有の SAP 文書化フローが実装および検証されるまで意図的に失敗します。

Docker

.env.example を .env にコピーした後、docker compose up --build を実行します。Docker はオプションであり、compose ファイルは開発専用で、本番向けに強化されていません。

トラブルシューティングと制限事項

• UI がバックエンドを利用できないと報告する場合は、最初に FastAPI を起動してください。

• ポートバインドに失敗する場合は、8000、8001、または 8501 を使用しているプロセスを停止してください。

• プロトタイプのユーザーセレクターは本番認証ではありません。

• SQLite は、水平スケーリングされた本番監査ストレージを意図していません。

• 実際の OAuth、テナントメタデータの癖、および RBP の動作にはテナント検証が必要です。

• モックルーティングは、提供されたデモンストレーション質問パターンを意図的にサポートしています。一般的な自然言語エンジンではありません。

• 将来の書き込みには、別の承認済みアーキテクチャが必要であり、プレースホルダーとしても存在しません。

詳細なフローと信頼境界については ARCHITECTURE.md を、管理とリスクについては SECURITY.md を参照してください。 正確な合成レコードとシナリオガイドは TEST_DATA.md に記載され、test_data/ の下にエクスポートされています。