SAP SuccessFactors Multi-Agent MCP 프로토타입

합성 SuccessFactors 스타일 데이터를 사용한 데모입니다. 이 애플리케이션은 읽기 전용 교육용 프로토타입으로, SAP SuccessFactors 시스템이 아니며 프로덕션 환경에 적합하지 않습니다.

이 애플리케이션은 제한된 MCP 도구 경계를 통해 승인된 HR 질문에 응답합니다. Mock 모드는 SAP 또는 OpenAI 자격 증명이 필요 없습니다. Demo 모드는 선택적 OpenAI Agents SDK 오케스트레이션을 추가하며, Real 모드는 명시적으로 구성된 비프로덕션 SuccessFactors 테넌트에 대해서만 예약되어 있습니다.

기능

• 유형이 지정된 11개의 읽기 전용 MCP 도구; 임의의 HTTP, OData 또는 쓰기 표면이 없습니다.

• 서버 측 역할과 인구 범위를 가진 4개의 합성 ID.

• 명시적 엔터티 및 필드 허용 목록과 기본 거부 방식의 응답 삭제.

• 10명의 가상 직원, 12개의 포지션, 기반 객체, 유효 일자 이력, 공석, 의도적인 데이터 품질 문제.

• 전체 HR 페이로드나 비밀번호 없이 구조화된 SQLite 감사 추적.

• FastAPI 채팅/감사 API 및 Streamlit 증거 중심 인터페이스.

• API 키 없이 작동하는 결정적 mock 채팅.

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를 백그라운드에서 자동으로 시작하므로, 가장 간단한 원커맨드 mock 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: 구성된 테스트 테넌트 전용. 누락된 설정은 시작 시 실패하며 mock 대체가 없습니다.

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를 호출하지 않습니다. 세 가지 서비스가 모두 demo 모드로 실행된 후 단일 옵트인 라이브 위임 스모크 테스트를 실행하려면:

$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 동작은 테넌트 검증이 필요합니다.

• Mock 라우팅은 의도적으로 제공된 데모 질문 패턴을 지원합니다. 일반 자연어 엔진이 아닙니다.

• 향후 쓰기 작업은 별도의 승인된 아키텍처가 필요하며 자리 표시자로도 존재하지 않습니다.

자세한 흐름 및 신뢰 경계는 ARCHITECTURE.md를 참조하고, 제어 및 위험은 SECURITY.md를 참조하십시오. 정확한 합성 레코드 및 시나리오 가이드는 TEST_DATA.md에 설명되어 있으며 test_data/ 아래에 내보내집니다.