SF MCP

SuccessFactors-MCP

SAP SuccessFactors Model Context Protocol Server

Installation · Quick Start · 43 Tools · Deployment · API Reference

______________________________________________________________________

A生产级 模型上下文协议 将Claude（或任何MCP客户端）连接到的服务器 SAP SuccessFactors 通过OData API。查询员工数据、管理权限、运行合规报告和管理人力资源操作——所有这些都是通过自然语言完成的。

You: "Who on the Engineering team has a work anniversary this month?"

Claude: [calls get_anniversary_employees] Found 3 upcoming anniversaries...
         - Jane Smith (5 years - milestone!) - March 12
         - Bob Johnson (2 years) - March 18
         - Alice Chen (10 years - milestone!) - March 25

为什么选择SF-MCP？

工具

43种工具，分为13个类别：

Configuration & Discovery (3 tools)

RBP Security (7 tools)

RBP Audit (2 tools)

Data Query (2 tools)

Employee Lookup (4 tools)

Time Off (3 tools)

Hiring & Onboarding (3 tools)

Compliance & Reporting (3 tools)

Performance & Compensation (2 tools)

Position Management (3 tools)

MDF Objects (3 tools)

Workflow (2 tools)

Monitoring & Admin (6 tools)

安装

先决条件

• Python 3.10+
• 紫外线 包管理器
• 具有API访问权限的SAP SuccessFactors帐户

设置

git clone https://github.com/aiadiguru2025/sf-mcp.git
cd sf-mcp
uv sync

快速开始

开发模式 （MCP检查员）：

uv run mcp dev main.py

标准模式 （克劳德桌面）：

uv run main.py

HTTP模式 （云运行/远程）：

PORT=8080 uv run main.py

Claude桌面集成

第一步——找到通往 uv

# macOS / Linux
which uv

# Windows (PowerShell)
Get-Command uv | Select-Object -ExpandProperty Source

步骤2--编辑您的Claude桌面配置

添加sf-mcp服务器：

{
  "mcpServers": {
    "sf-mcp": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/sf-mcp", "run", "main.py"]
    }
  }
}

步骤3--重新启动克劳德桌面

MCP工具图标（锤子）将出现在输入区域，所有43个工具都可用。

注： 证书(auth_user_id 和 auth_password)在每次工具调用时都会提供这些参数——配置中没有存储任何内容。

部署

谷歌云运行

# Build and deploy
export PROJECT_ID=your-gcp-project-id
gcloud builds submit --tag gcr.io/$PROJECT_ID/sf-mcp
gcloud run deploy sf-mcp \
  --image gcr.io/$PROJECT_ID/sf-mcp \
  --platform managed \
  --region us-central1

然后将Claude Desktop指向远程URL：

{
  "mcpServers": {
    "sf-mcp": {
      "url": "https://sf-mcp-xxxxx-uc.a.run.app/mcp"
    }
  }
}

Docker（本地）

docker build -t sf-mcp .
docker run -p 8080:8080 sf-mcp

API密钥保护（可选）

集 MCP_API_KEY 要要求在HTTP端点上进行身份验证，请执行以下操作：

MCP_API_KEY=your-secret-key PORT=8080 uv run main.py

客户必须包括 X-API-Key: your-secret-key 在请求中。

配置

所有工具参数(data_center, environment, auth_user_id, auth_password)根据请求提供。服务器端环境变量是可选的：

速率限制

响应缓存

终端保护

复制 .env.example 到 .env 自定义：

cp .env.example .env

支持的数据中心

6大洲的21个数据中心，支持别名：

建筑

sf-mcp/
├── main.py                     # Entry point (stdio + HTTP modes)
├── sf_mcp/
│   ├── server.py               # FastMCP instance
│   ├── config.py               # DC mappings, constants, env vars
│   ├── auth.py                 # Credential resolution, API key middleware
│   ├── client.py               # HTTP client (OData, metadata, service doc, pagination)
│   ├── cache.py                # TTL-based response cache with deep-copy safety
│   ├── rate_limiter.py         # Sliding-window rate limiter (per-instance)
│   ├── validation.py           # 10 input validators with registry pattern
│   ├── decorators.py           # sf_tool decorator (cross-cutting concerns)
│   ├── dependencies.py         # FastMCP DI for schema exclusion
│   ├── logging_config.py       # Cloud Logging JSON formatter, audit_log()
│   ├── xml_utils.py            # Safe XML parsing (defusedxml), SAP date parsing
│   └── tools/                  # 43 tools across 13 modules
│       ├── configuration.py    # get_configuration, compare_configurations, list_entities
│       ├── permissions.py      # 7 RBP security tools
│       ├── audit.py            # Role history, role assignment history
│       ├── query.py            # query_odata, get_picklist_values
│       ├── employee.py         # Profile, search, history, team roster
│       ├── time_off.py         # Balances, upcoming absences, requests
│       ├── recruiting.py       # Requisitions, pipeline, new hires
│       ├── compliance.py       # Terminations, missing data, anniversaries, reviews, comp
│       ├── position.py         # Position details, vacancies, org chart
│       ├── workflow.py         # Pending approvals, workflow history
│       ├── mdf.py              # MDF object definitions, queries, foundation objects
│       ├── monitoring.py       # Alerts, scheduled jobs, integration jobs
│       ├── admin.py            # Rate limit quota, cache status, cache clear
│       └── utils.py            # Shared utilities (display_name)
├── tests/                      # 110 tests
├── Dockerfile                  # Cloud Run container
├── .env.example                # Configuration template
└── pyproject.toml              # Project metadata, dependencies, linter config

设计原则

零样板 --The sf_tool 装饰器处理请求ID生成、计时、审计日志、输入验证、凭证检查、错误处理和 $top 夹紧。工具函数仅包含业务逻辑。

缺省安全 -10个输入验证器（regex allowlists）、OData注入防止、XXE-safe XML解析（defosedxml）、定时安全API密钥比较（hmac.compare_dispest）以及日志中的自动凭证屏蔽。

生产就绪 --连接池（requests.Session）、突变安全响应缓存（put/get深度复制）、滑动窗口速率限制和自动429重试，以及与Cloud Logging兼容的JSON审计跟踪。

架构清理 --内部参数(request_id, start_time, api_host)通过FastMCP的依赖注入从MCP工具模式中隐藏，为LLM消费者保持工具接口的清洁。

安全

测试

# Run all 110 tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=sf_mcp

# Lint
uv run ruff check .

# Type check
uv run mypy sf_mcp/

测试覆盖范围包括：

• 配置 --DC映射分辨率、不区分大小写、别名、错误情况
• 验证 --所有10个验证器均具有有效/无效输入，防止注射
• 客户 --模拟HTTP响应（200、401、500，空，连接错误）
• 速率限制器 --限制执行、滑动窗口、每实例隔离、线程安全
• 缓存 --Put/get、TTL到期、类别TTL、无效、驱逐、深度复制安全
• 分页 --单页/多页，max_pages限制，错误处理，$跳过增量
• 装饰器 --值注入、验证错误、max_top箝位、异常处理

API 参考

每个工具都接受这些常见参数：

Configuration Tools

get_configuration

检索SuccessFactors实体的OData元数据。

list_entities

发现实例中所有可用的OData实体。

compare_configurations

比较两个实例之间的实体配置（例如，dev与prod）。

RBP Security Tools

get_rbp_roles

get_role_permissions

get_user_permissions

get_user_roles

get_permission_metadata

check_user_permission

get_dynamic_groups

RBP Audit Tools

get_role_history

get_role_assignment_history

至少一个 role_id 或 user_id 是必需的。

Data Query Tools

query_odata

get_picklist_values

Employee Lookup Tools

get_employee_profile

search_employees

get_employee_history

get_team_roster

Time Off Tools

get_time_off_balances

get_upcoming_time_off

get_time_off_requests

Hiring & Onboarding Tools

get_open_requisitions

get_candidate_pipeline

get_new_hires

Compliance & Reporting Tools

get_terminations

get_employees_missing_data

get_anniversary_employees

Performance & Compensation Tools

get_performance_review_status

get_compensation_details

Position Management Tools

get_position_details

get_vacant_positions

get_org_chart

MDF Object Tools

get_mdf_object_definitions

query_mdf_object

get_foundation_objects

Workflow Tools

get_pending_approvals

get_workflow_history

Monitoring & Admin Tools

get_alert_notifications

get_scheduled_job_status

get_integration_center_jobs

get_api_quota_status

返回指定实例的当前速率限制使用情况。

get_cache_status

返回缓存命中率、按类别划分的条目计数和内存使用情况。

clear_cache

查询示例

用自然语言问克劳德：

常见成功因素实体

使用 list_entities 发现实例中的所有可用实体。

故障排除

Authentication Errors (HTTP 401)

• 验证凭据格式：用户ID 没有 @instance
• 确认密码正确
• 确保API用户在SuccessFactors管理中心中具有适当的权限

Validation Errors

所有输入都经过验证，以防止注射攻击：

Server Disconnected (Claude Desktop)

1. 验证 uv 配置中的路径正确： which uv
2. 检查日志： tail -f ~/Library/Logs/Claude/mcp*.log
3. 手动测试： uv run mcp dev main.py
4. 确保已安装Python 3.10+： python3 --version

Rate Limit Errors

• 服务器自动重试HTTP 429响应（最多3次）
• 使用 get_api_quota_status 检查当前使用情况
• 通过以下方式增加限额 SF_RATE_LIMIT 环境变量
• 缓存响应 SF_CACHE_TTL_DEFAULT 以减少API调用

依赖项

开发依赖关系： pytest、ruff、mypy

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 运行测试： uv run pytest tests/ -v
4. 运行linting： uv run ruff check .
5. 提交您的更改
6. 打开拉取请求

更新日志

看 更改日志.md 发布历史。

许可证

该项目根据 MIT许可证 --看看 许可证 文件以获取详细信息。

______________________________________________________________________

Built with FastMCP · Powered by Model Context Protocol