# Brazilian PEP MCP Server

An MCP (Model Context Protocol) server that provides access to Brazilian PEP (Politically Exposed Persons) and federal public servants data through the Porta da Transparência API.

## Components

- **mcp_server.py** - MCP server exposing Brazilian PEP and servants search tools
- **pyproject.toml** - Project dependencies and configuration
- **requirements.txt** - Python dependencies

## Features

- Search PEPs (Politically Exposed Persons) by CPF, name, function, agency, or date ranges
- Search federal executive branch servers (civil and military)
- Query server remuneration data
- Search servers aggregated by agency
- Query functions and positions of trust
- Get comprehensive PEP status for individuals
- Extract specific fields from API responses
- Secure API key authentication
- Async-compatible tool execution

## Data Sources

| Source | Purpose | Search By |
|--------|---------|-----------|
| PEPs | Politically Exposed Persons | CPF, Name, Function, Agency, Date Ranges |
| Servidores | Federal Executive Branch Servers | CPF, Name, Agency, Type, Situation |
| Remuneração | Server Remuneration | CPF, ID, Month/Year |
| Por Órgão | Servers by Agency | Agency Code, Type, Link Type |
| Funções e Cargos | Functions and Positions | Pagination |

## API Key Configuration

**An API key is REQUIRED to use this system.**

### Get your API key:

1. Visit: https://www.portaldatransparencia.gov.br/ (Brazilian CPF is required)
2. Login or create an account
3. Go to "Minha Conta" → "API Keys" or "Desenvolvedor"
4. Generate a new API key
5. Copy the key (format: `abcd1234efgh5678ijkl9012`)

### Setup:

Create `.env` file in project root:
```
PORTAL_TRANSPARENCIA_API_KEY=your_key_here
```

**SECURITY**: Never commit your API key to version control!

## Usage

### Running the MCP Server

The MCP server can be run standalone or used by MCP clients:

```bash
python mcp_server.py
```

### Example queries:
- "Check if CPF 123.456.789-00 is a PEP"
- "Search for servers named Silva in the Ministry of Economy"
- "Get remuneration data for server with CPF 987.654.321-00 for January 2026"
- "List all PEPs in agency 25000"
- "Search for functions and positions of trust"

## MCP Server Tools

The MCP server exposes the following tools:

### PEP Search Tools
- **search_peps** - Search PEPs by CPF, name, function, agency, or date ranges
- **get_pep_info** - Get comprehensive PEP information for a person by CPF

### Servidor Search Tools
- **search_servidores** - Search federal executive branch servers by CPF, name, agency, type, or situation
- **get_servidor_by_id** - Get specific server by ID
- **search_servidores_remuneracao** - Search server remuneration by CPF or ID and month/year
- **search_servidores_por_orgao** - Search servers aggregated by agency
- **search_funcoes_e_cargos** - Search functions and positions of trust

## Architecture

```
User Query (Natural Language)
    ↓
Tool Selection & Execution
    ↓
MCP Tools / Direct API Calls
    ↓
Brazilian PEP API
    ↓
Detailed PEP/Servant Information
    ↓
Natural Language Response
```

## Document Formatting

The system automatically cleans document numbers (Brazilian CPF). Both formatted and unformatted documents work:

```python
# These are equivalent:
"123.456.789-00"
"12345678900"
```

## Error Handling

The system includes comprehensive error handling:
- API connection errors
- Invalid document formats
- Missing API keys
- Rate limiting
- Malformed responses

## Troubleshooting

| Issue | Solution |
|-------|----------|
| API key not found | Set PORTAL_TRANSPARENCIA_API_KEY in .env file |
| Connection timeout | Check internet connection and API status |
| No records found | Verify CPF format and check if person exists |
| 401 Unauthorized | Verify API key is correct and active |

## References

- **API Documentation**: https://api.portaldatransparencia.gov.br/swagger-ui/index.html
- **Porta da Transparência**: https://www.portaldatransparencia.gov.br/
- **MCP Protocol**: https://modelcontextprotocol.io/

**Last Updated**: June 2026
**API Base URL**: https://api.portaldatransparencia.gov.br/api-de-dados