Spanish Public Info Radar MCP

🚀 西班牙公共數據MCP

西班牙公共數據MCP是一個用於查詢西班牙政府開放數據API的MCP服務器，提供了對西班牙政府數據進行即時查詢的LLM友好工具。

🚀 快速開始

安裝

# 克隆倉庫
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# 使用uv安裝（推薦）
uv sync

# 開發環境安裝
uv sync --extra dev

啟動方式

方式一：直接運行（開發/測試）

# 安裝依賴
uv sync

# 運行MCP服務器（HTTP/SSE模式）
uv run python -m public_radar

# 或者指定端口運行
uv run python -m public_radar --port 9000

# 或者以標準輸入輸出模式運行（適用於Claude Desktop）
uv run python -m public_radar --stdio

方式二：使用Docker

# 構建並運行
docker-compose up -d

# 查看日誌
docker-compose logs -f

# 停止運行
docker-compose down

驗證運行情況

# 健康檢查（HTTP模式）
curl http://localhost:8080/health

# 應返回: {"status":"healthy","service":"spanish-public-data-mcp"}

與Claude Desktop集成

步驟1：定位配置文件

Claude Desktop配置文件位置如下：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

步驟2：添加MCP服務器配置

打開配置文件並添加以下內容：

{
  "mcpServers": {
    "spanish-public-data": {
      "command": "uv",
      "args": ["run", "python", "-m", "public_radar", "--stdio"],
      "cwd": "C:\\Users\\YOUR_USER\\path\\to\\spanish-public-data-mcp"
    }
  }
}

注意：請將YOUR_USER和路徑替換為實際安裝路徑。

步驟3：重啟Claude Desktop

關閉並重新打開Claude Desktop以加載新的MCP服務器。

步驟4：驗證連接

向Claude詢問：“你有哪些西班牙公共數據工具可用？” Claude應返回26個可用工具的相關信息。

✨ 主要特性

• 多數據源支持：支持查詢多個西班牙政府數據源，包括國家資助數據庫（BDNS）、官方公報（BOE）、公司註冊公報（BORME）、國家統計局（INE）和國家開放數據目錄（datos.gob.es）。
• 即時查詢：通過即時查詢官方API獲取數據，無需數據庫。
• 豐富工具集：提供26個MCP工具，涵蓋資助、立法、公司註冊、統計和開放數據等多個領域。

📦 安裝指南

# 克隆倉庫
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# 使用uv安裝（推薦）
uv sync

# 開發環境安裝
uv sync --extra dev

💻 使用示例

示例查詢Claude

資助與補貼（BDNS）

"查找上個月發佈的資助項目"

"搜索與創新或研發相關的資助項目"

"公司NIF為B12345678的獲得了哪些資助？"

"顯示資助項目BDNS 123456的詳細信息"

立法（BOE）

"搜索有關可再生能源的法律"

"今天官方公報發佈了什麼內容？"

"查找2023年有關公共補貼的立法"

"顯示數據保護法的全文"

公司註冊（BORME）

"今天馬德里註冊了哪些公司？"

"顯示2024年1月15日的公司註冊公報摘要"

"查找近期公司解散情況"

統計（INE）

"國家統計局有哪些統計操作可用？"

"顯示最新的消費者物價指數（IPC）數據"

"獲取勞動力調查（EPA）的失業統計數據"

"西班牙當前的通貨膨脹率是多少？"

"顯示過去12個季度的國內生產總值（GDP）增長數據"

"在人口普查操作中查找有關人口的表格"

綜合研究

"我想調查XYZ公司。檢查：
1. 他們獲得了哪些資助？
2. 有關他們的最新公司註冊公報條目？"

"查找可再生能源項目的所有資金機會：
1. 當前開放的資助項目
2. 相關立法"

"給我一份西班牙的經濟概況：
1. 最新的失業率（EPA）
2. 當前的通貨膨脹率（IPC）
3. 近期的GDP增長情況"

開放數據（datos.gob.es）

"搜索有關空氣質量的數據集"

"查找馬德里市議會的開放數據"

"datos.gob.es上有哪些數據類別？"

"顯示數據集e05068001-mapas-estrategicos-de-ruido的詳細信息"

📚 詳細文檔

可用的MCP工具

BDNS（資助） - 3個工具

BOE（立法） - 11個工具

BORME（公司註冊） - 1個工具

INE（統計） - 6個工具

datos.gob.es（開放數據） - 4個工具

通用 - 1個工具

工具參數參考

search_grants

{
  "date_from": "2024-01-01",    // 可選：開始日期 (YYYY-MM-DD)
  "date_to": "2024-12-31",      // 可選：結束日期 (YYYY-MM-DD)
  "granting_body": "E00003901", // 可選：資助機構代碼
  "limit": 20                   // 可選：最大結果數 (1-100, 默認20)
}

search_grant_awards

{
  "date_from": "2024-01-01",      // 可選：開始日期
  "date_to": "2024-12-31",        // 可選：結束日期
  "beneficiary_nif": "B12345678", // 可選：受益方NIF/CIF
  "limit": 20                     // 可選：最大結果數
}

get_grant_details

{
  "grant_id": "123456"  // 必需：BDNS資助項目ID
}

search_legislation

{
  "query": "energias renovables",  // 必需：搜索文本
  "date_from": "2020-01-01",       // 可選：開始日期
  "date_to": "2024-12-31",         // 可選：結束日期
  "title": "ley energia",          // 可選：按標題過濾
  "department_code": "4225",       // 可選：部門代碼（使用get_departments_table）
  "legal_range_code": "ley",       // 可選：法律範圍（使用get_legal_ranges_table）
  "matter_code": "170",            // 可選：主題代碼（使用get_matters_table）
  "include_derogated": false,      // 可選：包括已廢除的法律（默認false）
  "offset": 0,                     // 可選：跳過結果（分頁）
  "limit": 20                      // 可選：最大結果數 (1-100)
}

get_legislation_details

{
  "legislation_id": "BOE-A-2015-10566"  // 必需：BOE立法ID
}

get_legislation_text

{
  "legislation_id": "BOE-A-2015-10566"  // 必需：BOE立法ID
}

get_legislation_structure

{
  "legislation_id": "BOE-A-2015-10566"  // 必需：BOE立法ID
}

get_legislation_block

{
  "legislation_id": "BOE-A-2015-10566", // 必需：BOE立法ID
  "block_id": "a1"                       // 必需：塊ID（例如，"a1" 表示第1條）
}

get_departments_table

{}  // 無需參數

get_legal_ranges_table

{}  // 無需參數

get_matters_table

{}  // 無需參數

get_boe_summary

{
  "date": "2024-01-15"  // 可選：日期 (YYYY-MM-DD)，默認為今天
}

get_borme_summary

{
  "date": "2024-01-15"  // 可選：日期 (YYYY-MM-DD)，默認為今天
}

get_ine_operations

{}  // 無需參數

get_ine_operation

{
  "operation_id": "IPC"  // 必需：操作ID或代碼（例如，'IPC', 'EPA', '25'）
}

get_ine_table_data

{
  "table_id": "50902",  // 必需：國家統計局的表格ID
  "nult": 12            // 可選：最後週期數 (1-100, 默認12)
}

get_ine_series_data

{
  "series_code": "IPC251856", // 必需：國家統計局的系列代碼
  "nult": 12                   // 可選：最後週期數 (1-100, 默認12)
}

search_ine_tables

{
  "operation_id": "IPC"  // 必需：搜索表格的操作ID
}

get_ine_variables

{
  "operation_id": "IPC"  // 可選：按操作過濾變量
}

search_open_data

{
  "query": "air quality",           // 可選：搜索文本
  "theme": "medio-ambiente",        // 可選：主題代碼
  "publisher": "L01280796",         // 可選：發佈者ID
  "limit": 20                       // 可選：最大結果數 (1-100)
}

get_open_data_details

{
  "dataset_id": "e05068001-mapas-estrategicos-de-ruido"  // 必需：數據集ID
}

list_open_data_themes

{}  // 無需參數

list_open_data_publishers

{
  "limit": 50  // 可選：最大結果數（默認50）
}

項目結構

src/public_radar/
├── common/          # HTTP客戶端、日期處理、日誌記錄
├── sources/         # API客戶端（BDNS、BOE、INE、datos.gob.es）
│   ├── bdns.py      # BDNS客戶端（資助）
│   ├── boe.py       # BOE客戶端（立法、BORME）
│   ├── ine.py       # INE客戶端（統計）
│   └── datos_gob.py # datos.gob.es客戶端（開放數據）
├── mcp/             # MCP服務器和工具
│   ├── server.py    # MCP服務器 + 26個工具處理程序
│   └── logging.py   # 工具調用日誌記錄（JSONL）
├── __init__.py
└── __main__.py      # CLI入口點

tests/
├── unit/            # 帶模擬的單元測試（168個測試）
├── integration/     # 真實API測試（43個測試）
└── fixtures/        # 示例API響應

配置

環境變量

工具調用日誌

所有MCP工具調用都記錄到logs/mcp_calls_YYYY-MM-DD.jsonl：

{
  "timestamp": "2024-01-15T10:30:00Z",
  "tool": "search_grants",
  "input": {"date_from": "2024-01-01", "limit": 10},
  "output_summary": {"count": 10, "first_title": "..."},
  "duration_ms": 450,
  "success": true,
  "error": null
}

日誌會自動輪轉（7天后刪除）。

Docker部署

# 啟動MCP服務器
docker-compose up -d

# 檢查健康狀況
curl http://localhost:8080/health

# 查看日誌
docker-compose logs -f mcp

# 停止服務器
docker-compose down

開發

# 安裝開發依賴
uv sync --extra dev

# 運行測試
uv run pytest

# 運行測試並統計覆蓋率
uv run pytest --cov

# 運行代碼檢查
uv run pre-commit run --all-files

# 類型檢查
uv run mypy src/

當前測試覆蓋率

• 211個測試通過（168個單元測試 + 43個集成測試）
• 53%以上的代碼覆蓋率（僅單元測試）
• 所有解析器和工具處理程序都有單元測試
• 對真實API調用（BDNS、BOE、INE、datos.gob.es）進行集成測試

數據源

🔧 技術細節

• 架構：即時查詢官方API，無需數據庫。
• 測試：包含211個測試（168個單元測試 + 43個集成測試），單元測試覆蓋率達53%以上。
• 日誌：所有MCP工具調用記錄到logs/mcp_calls_YYYY-MM-DD.jsonl，日誌自動輪轉（7天后刪除）。

📄 許可證

本項目採用MIT許可證。

🔍 故障排除

Claude Desktop無法識別MCP

1. 檢查配置文件路徑是否正確。
2. 確保uv在你的PATH環境變量中。
3. 驗證cwd路徑指向項目目錄。
4. 完全重啟Claude Desktop。

API返回空結果

• BOE/BORME在週末或節假日不發佈數據。
• BDNS可能有速率限制。
• INE數據定期更新（每月、每季度）。

工具調用錯誤

檢查logs/mcp_calls_YYYY-MM-DD.jsonl中的日誌以獲取詳細錯誤信息。