内容
# 巴西制裁MCP服务器
一个MCP（模型上下文协议）服务器，通过Porta da Transparência API提供对巴西制裁数据库的访问。
## 组件
- **mcp_server.py** - MCP服务器，暴露巴西制裁搜索工具
- **main.py** - 使用LangChain和Ollama的AI聊天机器人，用于自然语言查询
- **BrazillianSanctions.json** - MCP配置文件
## 功能
- 搜索5个巴西制裁登记册
- 从API响应中提取特定字段（名称、制裁机构、日期、地点）
- 根据截止日期检查制裁是否仍然有效
- 获取所有登记册的最大信息综合概览
- 通过AI聊天机器人进行简单的自然语言接口（仅用于测试）
- 按CNPJ、CPF或公司名称搜索
- 详细的制裁信息，包括原因、日期和机构
- 安全的API密钥身份验证
- 异步兼容的工具执行
## 支持的制裁登记册
| 登记册 | 目的 | 搜索方式 |
|----------|---------|-----------|
| CNEP | 国家惩罚登记册 | CNPJ, CPF |
| CEPIM | 受制裁公共雇员登记册 | CNPJ, CPF |
| CEIS | 不合格实体登记册 | CNPJ, CPF |
| CEAF | 公共服务人员不合格登记册 | CPF |
| 宽大协议 | 宽大协议记录 | 名称, CNPJ |
**重要**: 名称搜索仅适用于宽大协议。其他登记册（CNEP、CEIS、CEPIM、CEAF）由于API限制，仅支持CNPJ/CPF搜索。
## API密钥配置
**使用此系统需要API密钥。**
### 获取您的API密钥:
1. 访问：https://www.portaldatransparencia.gov.br/ （需要巴西CPF）
2. 登录或创建帐户
3. 进入“Minha Conta” → “API Keys”或“Desenvolvedor”
4. 生成新的API密钥
5. 复制密钥（格式：`abcd1234efgh5678ijkl9012`）
### 设置:
在项目根目录中创建`.env`文件：
```
PORTAL_TRANSPARENCIA_API_KEY=您的密钥
```
**安全**: 绝不能将您的API密钥提交到版本控制！
## 用法
### 运行MCP服务器
MCP服务器可以独立运行或由MCP客户端使用：
```bash
python mcp_server.py
```
或者
在Claude/Cursor中使用：
```bash
\BrazillianSanctions.json
```
### 运行聊天机器人（聊天机器人仅用于测试，请确保在实际AML Agentic AI环境中设置MCP服务器以正确使用）
聊天机器人提供了一个自然语言接口来查询制裁数据库：
```bash
python main.py
```
**示例查询：**
- "需要检查30.477.220/0001-71是否受到巴西制裁，如果有，为什么？"
- "在宽大协议中搜索Petrobras"
- "检查CNPJ为11222333000181的公司是否有任何制裁"
## MCP服务器工具
MCP服务器暴露了以下工具：
### 搜索工具
- **search_cnep** - 按CNPJ、CPF、机构或日期范围搜索CNEP（国家惩罚登记册）
- **search_cepim** - 按CNPJ、CPF或上级机构搜索CEPIM（受制裁公共雇员登记册）
- **search_ceis** - 按CNPJ、CPF、机构或日期范围搜索CEIS（不合格实体登记册）
- **search_ceaf** - 按CPF、机构或日期范围搜索CEAF（公共服务人员不合格登记册）
- **search_acordos_leniencia** - 按名称、CNPJ、状态或日期范围搜索宽大协议
- **search_all_registers** - 为给定的CNPJ或CPF搜索所有登记册
### 分析工具
- **check_sanction_status** - 根据截止日期检查实体是否仍被制裁，涵盖所有登记册
- **get_sanctioning_authorities** - 获取有关谁制裁了实体（制裁机构）的信息
- **get_location_info** - 获取被制裁实体的地点/州信息（UF，机构地点）
- **get_comprehensive_overview** - 获取涵盖所有登记册的最大信息综合概览，包括名称、机构、日期、地点和状态
### 实用工具
- **get_sanction_details** - 获取有关特定制裁登记册类型的详细信息
- **check_entity_sanctions** - 对实体进行所有登记册的完整制裁检查
- **batch_search** - 一次搜索多个文档（CNPJs或CPFs）
- **generate_sanctions_report** - 从多个搜索结果生成格式化的文本报告
## 聊天机器人演示
我正在使用基于Ollama的本地聊天机器人进行测试，但MCP可以连接到任何Agentic AI：
- **LLM**: Ollama，qwen3:8b模型
- **Agent**: LangChain create_agent，带有工具调用
- **Tools**: 自定义LangChain工具，封装制裁API
## 架构
```
用户查询（自然语言）
↓
LangChain代理（Ollama）
↓
工具选择和执行
↓
MCP工具/直接API调用
↓
巴西制裁API
↓
详细的制裁信息
↓
自然语言响应
```
## 文档格式化
系统自动清理文档编号（巴西CPNJ或CPF）。格式化和非格式化文档均可使用：
```python
# 以下为等效：
"12.345.678/0001-00"
"123456780001000"
"123.456.789-66"
"12345678966"
```
## 错误处理
系统包含全面的错误处理：
- API连接错误
- 无效文档格式
- 缺失API密钥
- 速率限制
- 响应格式错误
## 故障排除
| 问题 | 解决方案 |
|-------|----------|
| 未找到API密钥 | 在.env文件中设置PORTAL_TRANSPARENCIA_API_KEY |
| Ollama未运行 | 启动Ollama服务：`ollama serve` |
| 模型未找到 | 拉取模型：`ollama pull qwen3:8b` |
| 连接超时 | 检查互联网连接和API状态 |
| 未找到记录 | 验证CNPJ/CPF格式并检查实体是否存在 |
## 参考
- **API文档**: https://api.portaldatransparencia.gov.br/swagger-ui/index.html
- **Porta da Transparência**: https://www.portaldatransparencia.gov.br/
- **MCP协议**: https://modelcontextprotocol.io/
- **LangChain**: https://python.langchain.com/
- **Ollama**: https://ollama.ai/
**最后更新**: 2026年6月
**API基准URL**: https://api.portaldatransparencia.gov.br/api-de-dados
