Joule HR MCP Server — SAP SuccessFactors

Servidor MCP (Model Context Protocol) que expõe dados do SAP SuccessFactors como ferramentas para agentes de IA integrados ao SAP Joule Studio.

Joule Studio (BTP)  →  MCP Server (CF)  →  SuccessFactors OData API
       ↑
   LLM do Joule raciocina com os dados retornados pelas tools

Princípio de design: a tool busca dados, o LLM do orquestrador raciocina. O servidor MCP não precisa de LLM próprio.

---

🔗 Ambiente de Demonstração

	URL
MCP Server	https://joule-sfsf-mcp.cfapps.us10.hana.ondemand.com/mcp
Health	https://joule-sfsf-mcp.cfapps.us10.hana.ondemand.com/health
Instância SFSF	https://hcm-us10-sales.hr.cloud.sap (company: SFSALES010674)
API Server SFSF	https://apisalesdemo8.successfactors.com

---

✅ Tools implementadas (15)

Consulta de dados — Employee Central

Tool	Descrição	Exemplo de pergunta
listar_funcionarios	Lista colaboradores com nome, cargo e departamento	"Quem está no sistema?"
dados_funcionario	Perfil completo: cargo, gestor, CC, avaliação, potencial	"Qual o cargo de Kay Holliston?"
subordinados_diretos	Equipe de um gestor	"Quem são os subordinados de 100083?"
organograma_departamento	Estrutura e colaboradores de um departamento	"Como é o organograma do dept 50150001?"

Recrutamento

Tool	Descrição	Exemplo de pergunta
vagas_internas	Vagas abertas com filtro por departamento	"Quais vagas estão abertas?"

Performance & Desenvolvimento

Tool	Descrição	Exemplo de pergunta
avaliacao_desempenho	Histórico de avaliações de um funcionário	"Como foi a avaliação de Amanda Winters?"
metas_funcionario	Metas e objetivos com status de progresso	"Quais as metas de Rick Smolla?"

Remuneração

Tool	Descrição	Exemplo de pergunta
remuneracao_funcionario	Componentes salariais recorrentes	"Qual o salário de Kay Holliston?"
consultar_remuneracao	Demonstrativo completo: componentes, avulsos, histórico de folha	"Mostre o demonstrativo de Amanda Winters"

Certificações O&G (via extensão CAP)

Tool	Descrição	Exemplo de pergunta
certificacoes_funcionario	Habilitações técnicas com status de validade	"Quais certificações de Amanda estão vencidas?"
alertas_vencimento	Colaboradores com certificações críticas	"Quem tem certificação vencida?"
dashboard_certificacoes	Compliance por departamento	"Como está o compliance de certificações?"

Geração de conteúdo (dados SFSF → Joule gera o texto)

Tool	Descrição	Exemplo de pergunta
redigir_perfil_vaga	Dados da vaga para o Joule redigir um JD completo	"Redija o perfil da vaga 3"
sugerir_metas_gd	Perfil do colaborador para o Joule sugerir metas SMART	"Sugira metas de GD para Amanda Winters"
buscar_cursos	Perfil e histórico para o Joule recomendar cursos	"Quais cursos Kay Holliston deveria fazer?"

---

🗺️ Roadmap

Concluído ✅

• [x] MCP Server base — 8 tools de consulta (Employee Central, Recrutamento, Performance, Remuneração)
• [x] OAuth 2.0 SAML Bearer — autenticação com instância real SFSALES010674
• [x] Deploy BTP Cloud Foundry — servidor HTTP com Streamable HTTP transport
• [x] Integração Joule Studio — BTP Destination + configuração MCP
• [x] Extensão CAP — Certificações O&G — 3 tools (CAP + HANA Cloud): certificacoes_funcionario, alertas_vencimento, dashboard_certificacoes
• [x] Casos custom — Geração de conteúdo — 3 tools: redigir_perfil_vaga, sugerir_metas_gd, buscar_cursos
• [x] Demonstrativo de pagamento — consultar_remuneracao com histórico de folha

Em andamento / Próximo sprint 🟡

• [ ] Caso 3 — Atualização de dado standard (Centro de Custo)

  • Tool atualizar_centro_custo implementada localmente (aguarda permissão RBP no SFSF Admin Center)
  • Requer: Admin Center → Permission Roles → Employment Information → Edit

• [ ] Caso 4 — Atualização de dado custom (% VR/VA, Higiene Ocupacional)

  • Requer campo MDF criado no SFSF via Admin Center / BCUI
  • Tool de leitura + escrita via Joule Studio skill

Backlog — Próximas extensões CAP 🟢

• [ ] Project Staffing — alocação de pessoas em projetos/plataformas offshore

  • Entidades: Projeto, Alocacao (userId + projeto + % FTE), CalendarioRotacao
  • Pergunta-chave: "Quem está disponível para alocar em Búzios com NR-33 válida?"

• [ ] Workforce Risk Dashboard — visão executiva para CHRO/VP RH

  • Entidades: ScoreRiscoFuga, BenchmarkSalarial, ProjecaoEfetivo
  • Pergunta-chave: "Quais áreas têm maior risco de perder talentos nos próximos 12 meses?"

• [ ] Portal de Mobilidade Interna

  • Cruzamento de perfil + vagas abertas + certificações → matching inteligente
  • Pergunta-chave: "Para qual vaga deveria me candidatar?"

• [ ] Painel de Sucessão Estendido

  • Entidades: CriticidadePosicao, SucessorIndicado, PlanoPDI
  • Pergunta-chave: "Quem substitui o Gerente de E&P Rio se ele sair?"

---

Pré-requisitos

• Python 3.12+
• SAP BTP com Cloud Foundry habilitado
• SAP SuccessFactors com OAuth App registrado
• cf CLI + mbt instalados

Configuração

cp .env.example .env
# Edite .env com suas credenciais SFSF

Gerando chave e certificado SAML

openssl req -x509 -newkey rsa:2048 -keyout sfsf_poc.key -out sfsf_poc.crt \
  -days 365 -nodes -subj "/CN=joule-mcp/O=MinhaOrg"

export SFSF_KEY_B64=$(cat sfsf_poc.key | base64 | tr -d '\n')
export SFSF_CERT_B64=$(cat sfsf_poc.crt | base64 | tr -d '\n')

Registrando OAuth App no SuccessFactors

1. Admin Center → Manage OAuth2 Client Applications → Register Client Application
2. Cole o conteúdo de sfsf_poc.crt no campo X.509 Certificate
3. Copie o API Key gerado → use como SFSF_CLIENT_ID

Rodando localmente

pip install -r requirements.txt
MODE=sfsf SFSF_CLIENT_ID=xxx SFSF_KEY_B64=xxx SFSF_CERT_B64=xxx \
  python mcp_server_sfsf.py

Deploy no SAP BTP Cloud Foundry

cf login --sso
cf push joule-sfsf-mcp -f manifest-mcp.yml --no-start
cf set-env joule-sfsf-mcp SFSF_CLIENT_ID "<oauth-client-id>"
cf set-env joule-sfsf-mcp SFSF_KEY_B64   "$(cat sfsf_poc.key | base64 | tr -d '\n')"
cf set-env joule-sfsf-mcp SFSF_CERT_B64  "$(cat sfsf_poc.crt | base64 | tr -d '\n')"
cf set-env joule-sfsf-mcp MCP_AUTH_TOKEN "$(python3 -c 'import uuid; print(uuid.uuid4())')"
cf start joule-sfsf-mcp

Integração com Joule Studio

Crie uma BTP Destination (Connectivity → Destinations):

Propriedade	Valor
Nome	JouleHR-MCP
Tipo	HTTP
URL	https://joule-sfsf-mcp.cfapps.us10.hana.ondemand.com
Authentication	NoAuthentication
sap-joule-studio-mcp-server	true
URL.headers.Authorization	Bearer <MCP_AUTH_TOKEN>

No Joule Studio: Adicionar servidor MCP → selecionar destino JouleHR-MCP → caminho /mcp.

Estrutura do projeto

├── mcp_server_cf.py     # MCP Server — Cloud Foundry (Streamable HTTP, 15 tools)
├── mcp_server_sfsf.py   # MCP Server — desenvolvimento local (stdio)
├── manifest-mcp.yml     # Deploy descriptor BTP CF
├── requirements.txt     # Dependências Python
├── .cfignore            # Exclui pastas desnecessárias do deploy
└── .env.example         # Template de variáveis de ambiente

Tecnologias

• Python 3.12 + FastMCP 1.28 — servidor MCP (Streamable HTTP)
• signxml + lxml — assinatura SAML para OAuth 2.0 SAML Bearer
• SAP SuccessFactors OData V2 — fonte de dados de RH
• SAP BTP Cloud Foundry — plataforma de deployment
• SAP Joule Studio — interface do agente conversacional
• SAP CAP + HANA Cloud — extensão para dados não nativos do SFSF

Referências

• SF_HCM_OData_API_DEV.pdf — Guia OData V2 do SAP SuccessFactors
• SAP API Servers
• MCP Protocol
• Extensão CAP Certificações

Licença

MIT