# Gipuzkoa Irekia MCP

> Gipuzkoa Irekia connects your AI agent directly to the public open data of the Gipuzkoa region, Spain. You can search for datasets, list publishing organizations, and get deep metadata on specific resources—all using plain conversation. It turns complex government portals into simple Q&A sessions.

## Overview
- **Category:** knowledge-management
- **Price:** Free
- **Tags:** open-data, public-sector, dataset-discovery, metadata-management, regional-data, transparency

## Description

Need to find a dataset about local transport or environmental regulations? Instead of navigating through dozens of departmental websites and clicking through confusing menus, your AI agent handles it all. This MCP lets you talk to the entire public sector catalog for Gipuzkoa directly. You can ask your agent to list every organization that publishes data or pinpoint specific datasets by theme. The system reads everything—from listing available groups to checking the metadata of a resource file. If you're building an application, this Vinkius catalog integration allows developers to retrieve necessary IDs and structure public APIs instantly through natural language prompts. It’s about turning weeks of manual portal research into seconds of conversation.

## Tools

### list_groups
Lists every available thematic group used to categorize datasets.

### show_group
Retrieves detailed information for a single thematic group.

### list_organizations
Retrieves a list of all government organizations that contribute open data.

### show_organization
Gets comprehensive details about one specific publishing organization.

### list_packages
Gets the names of all available datasets (packages) in the catalog.

### search_packages
Searches for specific datasets using keywords or filters.

### show_package
Fetches all the metadata associated with a named dataset package.

### search_resources
Searches through individual data files (resources) by keyword.

### show_resource
Retrieves full details, formats, and links for an individual data resource file.

## Prompt Examples

**Prompt:** 
```
List all the organizations that publish open data in Gipuzkoa.
```

**Response:** 
```
I've retrieved the list of publishing organizations. There are several entities including 'Diputación Foral de Gipuzkoa', 'Ayuntamiento de Donostia', and various regional agencies. Would you like to see the details for a specific one?
```

**Prompt:** 
```
Search for datasets related to 'environment' in the Gipuzkoa Irekia catalog.
```

**Response:** 
```
Searching for 'environment'... I found several datasets, such as 'Air Quality Measurements' and 'Waste Management Statistics'. Which one would you like to explore further?
```

**Prompt:** 
```
Show me the metadata for the dataset named 'presupuestos-municipales'.
```

**Response:** 
```
Fetching metadata for 'presupuestos-municipales'... This dataset contains municipal budget information. It includes resources in CSV and XLS formats, last updated recently by the Finance Department. Do you want the specific resource IDs for downloading?
```

## Capabilities

### Identify data sources
List all available thematic groups or specific organizations that publish open records.

### Search for datasets
Find packages of public data using keywords, filtering by organization or theme.

### Inspect resource metadata
Get detailed information about specific downloadable files, including their format and origin.

### View dataset details
Retrieve the full metadata package for a known public dataset.

### Browse publishing entities
Get information on specific governmental departments or municipalities responsible for the data.

## Use Cases

### Tracking regional environmental trends
A researcher needs data spanning multiple years. They ask their agent to search datasets related to 'environment' using `search_packages`. The agent returns several options, allowing the researcher to then use `show_package` on the most promising one to check for specific historical resource IDs.

### Building an app dashboard
A developer needs a list of all available data sources. They prompt the agent to execute `list_organizations`, getting the full names and scope of every contributing department, which they then use to structure their application's API calls.

### Verifying budget figures
A citizen wants to check municipal spending. They ask about a specific dataset like 'presupuestos-municipales'. The agent uses `show_package` to confirm the data exists, and then uses `search_resources` to find the exact CSV file they need.

## Benefits

- Find datasets instantly. Instead of clicking through dozens of menus, use `search_packages` to find specific data sets using natural language prompts.
- Know your sources. Use `list_organizations` and `show_organization` to see exactly which government body published the record, improving trust in the data.
- Deep dive into files. If you know a dataset name, use `show_package` then inspect resources with `show_resource` for format details and download links.
- Browse by topic. You don't need to guess what's available; you can start broad by listing groups (`list_groups`) or themes.
- Save time on structure. Developers use this MCP to get IDs and metadata directly, eliminating manual API calls needed for integration.

## How It Works

The bottom line is you talk naturally; the MCP does the complex database queries in the background.

1. Subscribe to this MCP and provide your Gipuzkoa Irekia API Key (optional, but recommended).
2. Ask your AI client a question about open records—for example, 'What datasets exist for waste management?'
3. The agent uses the tools to search the catalog and returns structured data or metadata directly into your chat.

## Frequently Asked Questions

**How does `search_packages` help me find datasets?**
It searches the entire catalog for dataset names using keywords. If you're looking for 'transport', this tool finds all packages related to transportation, even if they come from different organizations.

**What is the difference between `list_organizations` and `show_organization`?**
`list_organizations` just gives you a list of names. You run `show_organization` when you need deep details about one specific body, like its contact info or scope.

**Can I use `search_resources` to check for formats?**
Yes. This tool searches individual files by keyword. Running it shows the file's metadata, including its format (CSV, XLS) and whether it has a download link.

**Do I need all 9 tools to query data?**
No. You typically start with `list_groups` or `search_packages`. The other tools are for drilling down: getting specific details like running `show_organization`.

**Do I need an API key to use the `search_packages` function?**
No, you can start querying public data without an API key. However, we highly recommend obtaining one; it increases your query limits and ensures stable performance when running complex or repeated searches.

**How do I find datasets related to a specific topic using `list_groups`?**
The `list_groups` tool shows every available thematic category. Once you identify the correct group name, you use that context to refine your dataset search or call the `show_group` function.

**What is the difference between searching and using `show_package`?**
Searching finds datasets based on keywords. Using `show_package` fetches the complete, detailed metadata for a single dataset, including its full history, all contributing organizations, and resource IDs.

**When running complex queries with `search_resources`, what helps improve speed?**
The faster your results, the more specific your query. Include known data formats (like 'CSV' or 'XLS') and use precise keywords; vague searches can slow down the process significantly.

**How can I search for datasets related to a specific topic like 'transport'?**
You can use the `search_packages` tool. Simply provide the search term in the `q` parameter (e.g., 'transport'), and the agent will return a list of matching datasets from the Gipuzkoa Irekia catalog.

**Can I see which organizations are publishing data on this portal?**
Yes! Use the `list_organizations` tool to get a complete list of all departments, municipalities, and entities that contribute to the Gipuzkoa Irekia open data catalog.

**How do I get the download links or format details for a specific data file?**
Use the `show_resource` tool with the specific Resource ID. It will provide detailed metadata, including the file format (CSV, JSON, etc.) and the direct URL to access the data.