SAP SuccessFactors 多智能体 MCP 原型

使用合成式 SuccessFactors 风格数据的演示。 这是一个只读的教育性原型，不是 SAP SuccessFactors 系统，也不具备生产就绪性。

该应用通过一个狭窄的 MCP 工具边界来回答经授权的 HR 问题。模拟模式不需要 SAP 或 OpenAI 凭据。演示模式增加了可选的 OpenAI Agents SDK 编排；真实模式仅保留给明确配置的非生产 SuccessFactors 租户。

功能特性

• 十一个类型化、只读的 MCP 工具；没有任意的 HTTP、OData 或写入面。

• 四个合成身份，带有服务端角色和人群范围。

• 显式的实体和字段允许列表，加上默认拒绝的响应净化。

• 十个虚构员工、十二个职位、基础对象、生效日期历史、职位空缺，以及有意引入的数据质量问题。

• 结构化的 SQLite 审计跟踪，不包含完整的 HR 载荷或机密。

• 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

或者使用三个终端：

.\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 解释器，如果愿意，也可以打开三个终端。

配置和模式

将 .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 头将用户、会话和关联身份传递给 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。要在三个服务都以演示模式运行后运行单个可选加入的实时委派冒烟测试：

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

此测试会发起一次真实的 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. 验证允许和拒绝的员工场景。

不支持基本认证。所包含的真实令牌提供程序接口会故意失败，直到实现并验证特定于租户的 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/ 下导出。