# Clone repository
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# Install with uv (recommended)
uv sync

# For development
uv sync --extra dev

# Install dependencies
uv sync

# Run MCP server (HTTP/SSE mode)
uv run python -m public_radar

# Or on a specific port
uv run python -m public_radar --port 9000

# Or in stdio mode (for Claude Desktop)
uv run python -m public_radar --stdio

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

# Health check (HTTP mode)
curl http://localhost:8080/health

# Should return: {"status":"healthy","service":"spanish-public-data-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"
    }
  }
}

"Find grants published in the last month"

"Search for grants related to innovation or R&D"

"What grants has the company with NIF B12345678 received?"

"Show me details of grant BDNS 123456"

"Search for laws about renewable energy"

"What was published in the BOE today?"

"Find legislation about public subsidies from 2023"

"Show me the full text of the data protection law"

"What companies were registered in Madrid today?"

"Show me the BORME summary for January 15, 2024"

"Find recent company dissolutions"

"What statistical operations are available from INE?"

"Show me the latest CPI (IPC) data"

"Get unemployment statistics from the EPA survey"

"What is the current inflation rate in Spain?"

"Show me GDP growth data for the last 12 quarters"

"Find tables about population in the Census operation"

"I want to investigate company XYZ. Check:
1. What grants have they received?
2. Any recent BORME entries about them?"

"Find all funding opportunities for renewable energy projects:
1. Current open grants
2. Relevant legislation"

"Give me an economic overview of Spain:
1. Latest unemployment rate (EPA)
2. Current inflation (IPC)
3. Recent GDP growth"

"Search for datasets about air quality"

"Find open data from the Madrid city council"

"What data categories are available in datos.gob.es?"

"Show me details of dataset e05068001-mapas-estrategicos-de-ruido"

{
  "date_from": "2024-01-01",    // Optional: Start date (YYYY-MM-DD)
  "date_to": "2024-12-31",      // Optional: End date (YYYY-MM-DD)
  "granting_body": "E00003901", // Optional: Granting body code
  "limit": 20                   // Optional: Max results (1-100, default 20)
}

{
  "date_from": "2024-01-01",      // Optional: Start date
  "date_to": "2024-12-31",        // Optional: End date
  "beneficiary_nif": "B12345678", // Optional: Beneficiary NIF/CIF
  "limit": 20                     // Optional: Max results
}

{
  "grant_id": "123456"  // Required: BDNS grant ID
}

{
  "query": "energias renovables",  // Required: Search text
  "date_from": "2020-01-01",       // Optional: Start date
  "date_to": "2024-12-31",         // Optional: End date
  "title": "ley energia",          // Optional: Filter by title
  "department_code": "4225",       // Optional: Department code (use get_departments_table)
  "legal_range_code": "ley",       // Optional: Legal range (use get_legal_ranges_table)
  "matter_code": "170",            // Optional: Matter code (use get_matters_table)
  "include_derogated": false,      // Optional: Include repealed laws (default false)
  "offset": 0,                     // Optional: Skip results (pagination)
  "limit": 20                      // Optional: Max results (1-100)
}

{
  "legislation_id": "BOE-A-2015-10566"  // Required: BOE legislation ID
}

{
  "legislation_id": "BOE-A-2015-10566"  // Required: BOE legislation ID
}

{
  "legislation_id": "BOE-A-2015-10566"  // Required: BOE legislation ID
}

{
  "legislation_id": "BOE-A-2015-10566", // Required: BOE legislation ID
  "block_id": "a1"                       // Required: Block ID (e.g., "a1" for article 1)
}

{}  // No parameters required

{}  // No parameters required

{}  // No parameters required

{
  "date": "2024-01-15"  // Optional: Date (YYYY-MM-DD), defaults to today
}

{
  "date": "2024-01-15"  // Optional: Date (YYYY-MM-DD), defaults to today
}

{}  // No parameters required

{
  "operation_id": "IPC"  // Required: Operation ID or code (e.g., 'IPC', 'EPA', '25')
}

{
  "table_id": "50902",  // Required: Table ID from INE
  "nult": 12            // Optional: Number of last periods (1-100, default 12)
}

{
  "series_code": "IPC251856", // Required: Series code from INE
  "nult": 12                   // Optional: Number of last periods (1-100, default 12)
}

{
  "operation_id": "IPC"  // Required: Operation ID to search tables for
}

{
  "operation_id": "IPC"  // Optional: Filter variables by operation
}

{
  "query": "air quality",           // Optional: Search text
  "theme": "medio-ambiente",        // Optional: Theme code
  "publisher": "L01280796",         // Optional: Publisher ID
  "limit": 20                       // Optional: Max results (1-100)
}

{
  "dataset_id": "e05068001-mapas-estrategicos-de-ruido"  // Required: Dataset ID
}

{}  // No parameters required

{
  "limit": 50  // Optional: Max results (default 50)
}

src/public_radar/
├── common/          # HTTP client, dates, logging
├── sources/         # API clients (BDNS, BOE, INE, datos.gob.es)
│   ├── bdns.py      # BDNS client (grants)
│   ├── boe.py       # BOE client (legislation, BORME)
│   ├── ine.py       # INE client (statistics)
│   └── datos_gob.py # datos.gob.es client (open data)
├── mcp/             # MCP server and tools
│   ├── server.py    # MCP server + 26 tool handlers
│   └── logging.py   # Tool call logging (JSONL)
├── __init__.py
└── __main__.py      # CLI entry point

tests/
├── unit/            # Unit tests with mocks (168 tests)
├── integration/     # Real API tests (43 tests)
└── fixtures/        # Sample API responses

{
  "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
}

# Start MCP server
docker-compose up -d

# Check health
curl http://localhost:8080/health

# View logs
docker-compose logs -f mcp

# Stop server
docker-compose down

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run linting
uv run pre-commit run --all-files

# Type checking
uv run mypy src/