# Joule HR MCP Server — SAP SuccessFactors

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

```
Joule Studio (BTP)  →  MCP Server (CF)  →  SuccessFactors OData API
       ↑
  Claude / LLM
```

## Ferramentas disponíveis

| Tool | Descrição |
|---|---|
| `listar_funcionarios` | Lista colaboradores com nome, cargo e departamento |
| `dados_funcionario` | Perfil completo: cargo, gestor, centro de custo, avaliação |
| `vagas_internas` | Vagas abertas, com filtro por departamento |
| `avaliacao_desempenho` | Histórico de avaliações de um funcionário |
| `metas_funcionario` | Metas e objetivos com status de progresso |
| `subordinados_diretos` | Equipe de um gestor |
| `organograma_departamento` | Estrutura e colaboradores de um departamento |
| `remuneracao_funcionario` | Componentes salariais |

## Pré-requisitos

- Python 3.12+
- Conta SAP BTP com Cloud Foundry habilitado
- Acesso ao SAP SuccessFactors com OAuth App registrado
- `cf` CLI + `mbt` instalados

## Configuração

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

Variáveis necessárias no `.env`:

```
SFSF_COMPANY=SFSALES010674
SFSF_CLIENT_ID=<oauth-client-id-do-admin-center>
SFSF_LOGIN_URL=https://hcm-us10-sales.hr.cloud.sap
SFSF_API_URL=https://apisalesdemo8.successfactors.com
SFSF_KEY_B64=<chave-privada-rsa-em-base64>
SFSF_CERT_B64=<certificado-x509-em-base64>
```

### Gerando chave e certificado SAML

```bash
# Gerar chave RSA e certificado autoassinado
openssl req -x509 -newkey rsa:2048 -keyout sfsf_poc.key -out sfsf_poc.crt \
  -days 365 -nodes -subj "/CN=joule-mcp/O=MyOrg"

# Exportar em base64 para as env vars
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 o OAuth App no SuccessFactors

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

## Rodando localmente (VS Code / Claude Code)

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

Adicione ao `.mcp.json` do projeto:

```json
{
  "mcpServers": {
    "joule-sfsf": {
      "command": "python3",
      "args": ["mcp_server_sfsf.py"],
      "env": { "MODE": "sfsf" }
    }
  }
}
```

## Deploy no SAP BTP Cloud Foundry

```bash
# 1. Login
cf login --sso

# 2. Push sem iniciar
cf push joule-sfsf-mcp -f manifest-mcp.yml --no-start

# 3. Injetar credenciais
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())')"

# 4. Iniciar
cf start joule-sfsf-mcp
```

**URL após deploy:**
```
https://joule-sfsf-mcp.cfapps.us10.hana.ondemand.com/mcp
```

## Integração com Joule Studio

Crie uma **BTP Destination** com estas propriedades:

| 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 para Cloud Foundry (Streamable HTTP)
├── mcp_server_sfsf.py   # MCP Server local para desenvolvimento (stdio)
├── manifest-mcp.yml     # Manifest CF
├── requirements.txt     # Dependências Python
└── .env.example         # Variáveis de ambiente necessárias
```

## Tecnologias

- **Python 3.12** + **FastMCP 1.28** — servidor MCP
- **signxml** + **lxml** — assinatura SAML para OAuth 2.0
- **SAP SuccessFactors OData V2** — fonte de dados
- **SAP BTP Cloud Foundry** — plataforma de deployment
- **SAP Joule Studio** — interface do agente

## Referência

- [SF_HCM_OData_API_DEV.pdf](SF_HCM_OData_API_DEV.pdf) — Guia de referência OData V2 do SAP SuccessFactors
- [SAP SuccessFactors API Servers](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b/af2b8d5437494b12be88fe374eba75b6.html)
- [MCP Protocol](https://modelcontextprotocol.io)

## Licença

MIT