Transparencia MCP

透明MCP服务器

一个模型上下文协议（MCP）服务器，用于巴西公共透明度数据，使用Fiorilli门户API，按照MCP最佳实践构建。

概述

此MCP服务器提供用于处理透明度数据的工具，包括从公共API获取数据和根据模式验证数据。它遵循 MCP规范 并实现了正确的日志记录实践（仅记录到stderr）。

特性

Fiorilli透明门户API集成

该服务器与巴西全面的公共透明度系统Fiorilli Transparency Portal集成。它提供对各种公共数据端点的访问，包括：

费用（Expenses）

• define_exercicio_despesas -确定费用的行使年份
• despesas_por_orgao -按部门/机构分列的费用
• despesas_por_unidade -单位费用
• despesas_por_fornecedor -供应商费用
• despesas_gerais -一般费用
• detalhes_empenho_por_numero_empenho -按数量列出的承诺详情
• diarias -每日津贴
• despesas_restos_pagar -未清余额费用
• 还有更多与费用相关的端点。..

收入（Revenue）

• define_exercicio_receitas -确定收入的行使年
• receita_orcamentaria -预算收入
• receita_uniao -工会收入
• receita_estado -国家收入
• receita_extra_orcamentaria -预算外收入
• detalhes_receita_orcamentaria -预算收入明细

招标与合同（Bids and Contracts）

• licitacoes -投标流程
• contratos -合同

转移（Transfers）

• transferencias_entre_entidades -实体之间的转账

工作人员（Personnel）

• servidores -员工/服务器数据

API基本URL配置

服务器需要配置Fiorilli透明门户URL。您有几个选项：

选项1：环境变量（推荐）

# 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"

# Then run:
bun run index.ts

选项2：配置文件

编辑 transparencia-config.json 并更新 baseUrl 字段：

{
  "baseUrl": "http://your-portal-domain.gov.br/Transparencia"
}

选项3：使用npm脚本

# Pre-configured examples
bun run dev        # São Paulo
bun run dev:rio    # Rio de Janeiro
bun run dev:mg     # Minas Gerais

# Mock mode for testing (no real API needed)
bun run mock       # Run server with fake data
bun run mock:inspector  # Run inspector with fake data

选项4：模拟开发模式

对于没有真正Fiorilli门户的测试，请使用模拟模式：

export FIORILLI_MOCK_MODE=true
bun run index.ts

这为所有端点提供了真实的假数据，非常适合开发和测试。

查找Fiorilli门户网址

要查找特定州/城市的透明度门户：

1. 在线搜索“\[State Name\]透明度”或“\[City Name\]门户透明度”
2. 验证URL：必须以结尾 /Transparencia 并从以下位置提供JSON VersaoJson 端点
3. 测试门户：参观 http://portal-url/Transparencia/VersaoJson/Despesas/?Listagem=DefineExercicio&ConectarExercicio=2023

寻找工作Fiorilli门户：

一些门户网站可能受到反机器人系统的保护。要查找工作门户：

1. 搜索活跃的Fiorilli装置：查找“佛罗伦萨交通门户”+州名
2. 测试门户：访问URL并检查 /Transparencia/VersaoJson/ 端点返回JSON
3. 检查反机器人保护：一些门户返回HTML而不是JSON

已知工作示例：

• 一些州/市门户网站在没有保护的情况下工作
• 可能需要找到不使用Cloudflare或类似系统的门户
• 检查可能限制较少的当地市政门户网站

测试门户：

# Test if a portal works
curl "http://portal-url/Transparencia/VersaoJson/Despesas/?Listagem=DefineExercicio&ConectarExercicio=2023"
# Should return JSON, not HTML

安装

bun install

用法

运行服务器

bun run index.ts

服务器使用STDIO传输，并与Claude Desktop等MCP客户端通信。

连接到克劳德桌面

1. 复制或符号链接 claude_desktop_config.json 到您的Claude Desktop配置目录：

   # On Linux/macOS
   mkdir -p ~/Library/Application\ Support/Claude
   cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

1. 重新启动克劳德桌面

1. 服务器应出现在Claude的工具菜单中

发展

项目结构

• index.ts -主服务器实现
• http-schemas/ -HTTP响应的模式定义
• claude_desktop_config.json -Claude桌面配置

已实施的最佳实践

• 正确记录：所有日志记录都会进入stderr，从不进入stdout（对于基于STDIO的MCP服务器至关重要）
• 错误处理：使用适当的MCP错误代码进行全面的错误处理
• 类型安全：具有正确接口的完整TypeScript类型
• 模块化设计：通过专用处理程序方法实现关注点的清晰分离

添加新工具

要添加新工具，请执行以下操作：

1. 在中定义工具 ListToolsRequestSchema 处理器
2. 在中添加一个案例 CallToolRequestSchema 处理器
3. 使用适当的错误处理来实现处理程序方法

测试

基本服务器测试

测试服务器启动：

timeout 5 bun run index.ts

您应该看到：

[INFO] Starting Transparencia MCP Server
[INFO] Server connected and ready to handle requests

使用MCP检查器进行交互式测试

MCP检查器提供了一个基于web的界面，用于测试您的MCP服务器，而不需要Claude Desktop。

快速开始

# Using npm script (recommended)
bun run inspector

# Or using the shell script
./test-inspector.sh

# Or directly with npx
npx @modelcontextprotocol/inspector bun run index.ts

期待什么

1. 检查员将启动一个web服务器并打开您的浏览器
2. 你会看到一个类似的URL： http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=
3. web界面提供：

- 工具选项卡：测试所有Fiorilli API工具（费用、收入、投标、合同等） - 服务器连接窗格：监视服务器状态 - 通知窗格：查看服务器日志和消息

使用检查器

1. 测试工具：点击“工具”选项卡
2. 选择工具：选择任何Fiorilli API工具（例如。， despesas_por_orgao)
3. 输入参数：根据工具架构填写所需的参数
4. 执行：单击执行按钮测试工具
5. 查看结果：请参阅结果面板中的回复

Fiorilli API工具测试示例

各部门费用

{
  "diaInicio": "01",
  "mesInicio": "01",
  "diaFinal": "31",
  "mesFinal": "12",
  "exercicio": "2023",
  "empresa": "1",
  "mostraDadosConsolidado": false
}

收入数据

{
  "diaInicio": "01",
  "mesInicio": "01",
  "diaFinal": "31",
  "mesFinal": "12",
  "exercicio": "2023",
  "empresa": "1",
  "mostraDadosConsolidado": false
}

承诺详情

{
  "numeroEmpenho": "12345",
  "tipoEmpenho": "OR",
  "empresa": "1",
  "bolMostrarFornecedor": true
}

员工数据

{
  "empresa": "1",
  "exercicio": "2023",
  "mesFinalPeriodo": "12"
}

API实际使用情况

要与真正的Fiorilli门户网站一起使用，请在中更新BASE_URL src/pedrogomes/functions.ts:

const BASE_URL = "http://seusite.seuestado.gov.br/Transparencia";

替换 seusite.seuestado.gov.br 使用您所在州/实体的实际透明度门户域。

内置

• 模型上下文协议SDK
• 包子 -快速JavaScript运行时
• TypeScript用于类型安全