内容
# Transparencia MCP 服务器
一个遵循MCP最佳实践的巴西公共透明度数据MCP服务器，使用Fiorilli Portal API构建。
## 概述
该MCP服务器提供了处理透明度数据的工具，包括从公共API获取数据和根据模式验证数据。它遵循[MCP规范](https://modelcontextprotocol.io/)，并实施了适当的日志记录实践（仅记录到stderr）。
## 功能
### Fiorilli 透明度门户 API 集成
该服务器与Fiorilli透明度门户集成，这是一个全面的巴西公共透明度系统。它提供了对各种公共数据端点的访问，包括：
#### 支出（Despesas）
- `define_exercicio_despesas` - 定义支出年份
- `despesas_por_orgao` - 按部门/机构划分的支出
- `despesas_por_unidade` - 按单位划分的支出
- `despesas_por_fornecedor` - 按供应商划分的支出
- `despesas_gerais` - 一般支出
- `detalhes_empenho_por_numero_empenho` - 按编号划分的承诺详情
- `diarias` - 每日津贴
- `despesas_restos_pagar` - 未支付余额支出
- 以及更多与支出相关的端点...
#### 收入（Receitas）
- `define_exercicio_receitas` - 定义收入年份
- `receita_orcamentaria` - 预算收入
- `receita_uniao` - 联盟收入
- `receita_estado` - 州收入
- `receita_extra_orcamentaria` - 预算外收入
- `detalhes_receita_orcamentaria` - 预算收入详情
#### 招标和合同（Licitações e Contratos）
- `licitacoes` - 招标过程
- `contratos` - 合同
#### 转移（Transferências）
- `transferencias_entre_entidades` - 实体之间的转移
#### 人员（Pessoal）
- `servidores` - 员工/服务器数据
### API 基地址配置
服务器需要配置Fiorilli透明度门户URL。您有几个选项：
#### 选项 1：环境变量（推荐）
```bash
# São Paulo
export FIORILLI_BASE_URL="http://transparencia.prefeitura.sp.gov.br"
# Rio de Janeiro
export FIORILLI_BASE_URL="http://riotransparente.rio.rj.gov.br"
# Minas Gerais
export FIORILLI_BASE_URL="http://www.transparencia.mg.gov.br"
# 然后运行：
bun run index.ts
```
#### 选项 2：配置文件
编辑 `transparencia-config.json` 并更新 `baseUrl` 字段：
```json
{
"baseUrl": "http://your-portal-domain.gov.br/Transparencia"
}
```
#### 选项 3：使用 npm 脚本
```bash
# 预配置示例
bun run dev # São Paulo
bun run dev:rio # Rio de Janeiro
bun run dev:mg # Minas Gerais
# 模拟模式（无需真实 API）
bun run mock # 运行服务器并使用假数据
bun run mock:inspector # 运行检查器并使用假数据
```
#### 选项 4：开发模拟模式
在没有真实Fiorilli门户的情况下进行测试，使用模拟模式：
```bash
export FIORILLI_MOCK_MODE=true
bun run index.ts
```
这为所有端点提供现实的假数据，非常适合开发和测试。
### 查找 Fiorilli 门户网址
要查找特定州/城市的透明度门户：
1. **在线搜索**："[州名] 透明度" 或 "[城市名] 透明度门户"
2. **验证网址**：必须以 `/Transparencia` 结尾，并从 `VersaoJson` 端点提供 JSON
3. **测试门户**：访问 `http://portal-url/Transparencia/VersaoJson/Despesas/?Listagem=DefineExercicio&ConectarExercicio=2023`
**查找可用的 Fiorilli 门户：**
一些门户可能受到反机器人系统保护。要查找可用的门户：
1. **搜索活跃的 Fiorilli 安装**：查找 "portal transparência Fiorilli" + 州名
2. **测试门户**：访问网址并检查 `/Transparencia/VersaoJson/` 端点是否返回 JSON
3. **检查反机器人保护**：一些门户返回 HTML 而不是 JSON
**已知的可用示例：**
- 一些州/城市门户无需保护即可工作
- 可能需要查找不使用 Cloudflare 或类似系统的门户
- 检查可能限制较少的本地市政门户
**测试门户：**
```bash
# 测试门户是否可用
curl "http://portal-url/Transparencia/VersaoJson/Despesas/?Listagem=DefineExercicio&ConectarExercicio=2023"
# 应返回 JSON 而不是 HTML
```
## 安装
```bash
bun install
```
## 使用
### 运行服务器
```bash
bun run index.ts
```
服务器使用 STDIO 传输协议，与像 Claude Desktop 这样的 MCP 客户端通信。
### 连接到 Claude Desktop
1. 将 `claude_desktop_config.json` 复制或符号链接到您的 Claude Desktop 配置目录：
```bash
# 在 Linux/macOS 上
mkdir -p ~/Library/Application\ Support/Claude
cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. 重启 Claude Desktop
3. 服务器应在 Claude 的工具菜单中显示
## 开发
### 项目结构
- `index.ts` - 主要服务器实现
- `http-schemas/` - HTTP 响应模式定义
- `claude_desktop_config.json` - Claude Desktop 配置
### 已实施的最佳实践
- **适当的日志记录**：所有日志记录都输出到 stderr，绝不输出到 stdout（对于基于 STDIO 的 MCP 服务器至关重要）
- **错误处理**：全面的错误处理，附有适当的 MCP 错误代码
- **类型安全性**：完整的 TypeScript 类型，附有适当的接口
- **模块化设计**：清晰的关注点分离，附有专用的处理方法
### 添加新工具
要添加新工具：
1. 在 `ListToolsRequestSchema` 处理程序中定义工具
2. 在 `CallToolRequestSchema` 处理程序中添加一个案例
3. 实现具有适当错误处理的处理器方法
## 测试
### 基本服务器测试
测试服务器启动：
```bash
timeout 5 bun run index.ts
```
您应该看到：
```
[INFO] 启动 Transparencia MCP 服务器
[INFO] 服务器已连接并准备好处理请求
```
### 使用 MCP 检查器进行交互式测试
MCP 检查器提供了一个基于 Web 的界面，用于在不需要 Claude Desktop 的情况下测试您的 MCP 服务器。
#### 快速入门
```bash
# 使用 npm 脚本（推荐）
bun run inspector
# 或使用 shell 脚本
./test-inspector.sh
# 或直接使用 npx
npx @modelcontextprotocol/inspector bun run index.ts
```
#### 预期结果
1. 检查器将启动一个 Web 服务器并打开您的浏览器
2. 您将看到一个 URL，如：`http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>`
3. Web 界面提供：
- **工具选项卡**：测试所有 Fiorilli API 工具（支出、收入、招标、合同等）
- **服务器连接面板**：监视服务器状态
- **通知面板**：查看服务器日志和消息
#### 使用检查器
1. **测试工具**：单击“工具”选项卡
2. **选择工具**：选择任何 Fiorilli API 工具（例如 `despesas_por_orgao`）
3. **输入参数**：根据工具模式填写必填参数
4. **执行**：单击执行按钮测试工具
5. **查看结果**：在结果面板中查看响应
### 示例 Fiorilli API 工具测试
#### 按部门划分的支出
```json
{
"diaInicio": "01",
"mesInicio": "01",
"diaFinal": "31",
"mesFinal": "12",
"exercicio": "2023",
"empresa": "1",
"mostraDadosConsolidado": false
}
```
#### 收入数据
```json
{
"diaInicio": "01",
"mesInicio": "01",
"diaFinal": "31",
"mesFinal": "12",
"exercicio": "2023",
"empresa": "1",
"mostraDadosConsolidado": false
}
```
#### 承诺详情
```json
{
"numeroEmpenho": "12345",
"tipoEmpenho": "OR",
"empresa": "1",
"bolMostrarFornecedor": true
}
```
#### 员工数据
```json
{
"empresa": "1",
"exercicio": "2023",
"mesFinalPeriodo": "12"
}
```
### 真实 API 使用
要与真实的 Fiorilli 门户一起使用，请更新 `src/pedrogomes/functions.ts` 中的 BASE_URL：
```typescript
const BASE_URL = "http://seusite.seuestado.gov.br/Transparencia";
```
将 `seusite.seuestado.gov.br` 替换为您的州/实体实际的透明度门户域名。
## 使用的技术
- [Model Context Protocol SDK](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- [Bun](https://bun.com) - 快速 JavaScript 运行时
- TypeScript，用于类型安全
