# Campinas Open Data MCP

> Campinas Open Data connects your agent directly to Campinas, Brazil's public data portal. Ask questions about city services—like health metrics or education statistics—and retrieve structured metadata for datasets, resources, and organizational sources without leaving your client.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** campinas, open-data, ckan, brazil, public-records

## Description

This MCP lets you talk to a massive repository of public records from the city of Campinas using natural language. You don't need to know how to navigate complex government websites; just ask your agent what data you need—say, all datasets related to finance or transport. The system handles the heavy lifting: it finds relevant organizational departments and pulls back metadata for specific files, whether they are PDFs, CSVs, or APIs.

It's really about discovery. You can explore data by tag, browse groups like 'Health,' or check out every department providing records. When you connect this MCP via Vinkius, your agent gets a single point of access to thousands of public resources across the entire catalog, letting you query everything from one place.

## Tools

### list_groups
Lists all major thematic groupings (like 'Saúde' or 'Educação') used to categorize datasets.

### list_organizations
Provides a list of every official city department that publishes data through the portal.

### list_packages
Gives you a comprehensive list of all available dataset names on the platform.

### search_packages
Searches and finds dataset packages based on keywords or criteria you provide.

### get_package
Fetches all the metadata details for a single, specific dataset package.

### search_resources
Narrows down the search to find specific data files using detailed field names.

### get_resource
Retrieves the metadata and structure of an individual data file or resource within a package.

### list_tags
Shows every tag used across the portal, allowing for very granular filtering.

## Prompt Examples

**Prompt:** 
```
Search for datasets about 'educação' in Campinas.
```

**Response:** 
```
I found several datasets related to education, including 'Vagas em Creches' and 'Escolas Municipais'. Which one would you like to explore?
```

**Prompt:** 
```
List all organizations that provide data to the portal.
```

**Response:** 
```
I've retrieved the list of organizations. There are 25 entities, including the 'Secretaria Municipal de Saúde' and 'Secretaria de Finanças'.
```

**Prompt:** 
```
Get full metadata for the dataset 'vagas-em-creches'.
```

**Response:** 
```
Fetching metadata for 'vagas-em-creches'... This dataset includes 3 resources (CSV and PDF) and was last updated on June 2023. It covers nursery school availability by region.
```

## Capabilities

### Find dataset metadata
Retrieves full details and structural information for any specific data package.

### Check resource files
Gets metadata for individual resources, like a single CSV or PDF file hosted within a larger dataset.

### List thematic groups
Provides a list of high-level categories (like 'Education' or 'Health') used to organize the data.

### Map city departments
Lists all municipal organizations that are contributing public data to the portal.

### List available datasets
Retrieves a complete list of every dataset package available on the platform.

### Search by category or tag
Filters and finds packages based on specific keywords, tags, or thematic groups.

### Search for specific resources
Narrows down searches to find individual data files using field names.

## Use Cases

### Investigating public spending
A journalist needs to track departmental funding. They ask their agent to list all contributing organizations, then use this MCP to search for financial packages across those departments. The system pulls together the metadata and links they need immediately.

### Mapping educational resources
An academic needs data on school availability. They ask their agent to list groups, select 'Education,' then use `search_packages` to find all relevant dataset names like 'Vagas em Creches'. The MCP gives them the full metadata for further analysis.

### Debugging a data pipeline
A developer needs to know what fields are available in an existing CSV. They use their agent to get resource metadata via `get_resource`, confirming column names and formats without downloading or running the actual file.

## Benefits

- Metadata inspection is instant. You get full details on resources and packages using `get_package` or `get_resource`, meaning you know the data structure before your code even runs.
- You never have to guess where information lives. By running `list_organizations`, you instantly see which specific city department holds the records you need, cutting down research time dramatically.
- Finding relevant data is fast. Instead of clicking through pages, simply ask your agent to use `search_packages` with keywords like 'finance' or 'transport'.
- Explore by topic effortlessly. The `list_groups` tool lets you browse all city departments' offerings organized into manageable themes.
- It handles scale. Whether you need a broad overview of every available dataset using `list_packages`, or a targeted search with `search_resources`, the MCP keeps up.

## How It Works

The bottom line is, you talk to it in plain English, and it translates those questions into data queries against the city's official records.

1. Subscribe to the MCP and provide your Campinas Portal API Key (if required by the data).
2. Ask your agent a question like: 'List all organizations that track public spending.'
3. The MCP sends structured requests, and your agent returns the list of departments or dataset metadata you asked for.

## Frequently Asked Questions

**How do I find all data provided by a specific city department using list_organizations?**
You use `list_organizations` first. This tool provides the full roster of contributing entities. Once you identify the correct name, you can then search for that organization's packages using other tools.

**What is the difference between list_packages and search_packages?**
`list_packages` gives you a complete dump of every dataset name available. `search_packages` lets you filter that massive list instantly by providing keywords or criteria, which is usually faster.

**If I find a resource link, what does get_resource do?**
`get_resource` pulls the specific metadata for an individual file. It tells you if that file is a CSV, what its column names are, and how big it is, without needing to download anything.

**Can I search by theme? Should I use list_groups or tags?**
Use `list_groups` for broad, official categories (like 'Finance'). Use `list_tags` if you need a more specific, operational keyword that might apply across multiple groups.

**When I run get_package, what specific details about the dataset structure do I receive?**
It returns a comprehensive metadata record for that entire package. Beyond the title and description, you'll get critical information like associated tags, groups, the number of contained resources, and the last update date.

**If I use search_resources, what is the difference between those results and packages found via search_packages?**
The key difference is scope: A package is a container that holds related data. Using search_resources targets actual files or data points (like a specific CSV), giving you immediate access to the content level.

**What happens if I forget to include my API key when running search_packages?**
The MCP will typically reject the request with an authentication error. Remember that while some public data is accessible without a key, restricted or high-volume queries require proper credentials for successful execution.

**If I use list_packages and there are thousands of results, should I worry about rate limits?**
Yes, large lists can hit API rate limits. If the initial output is too long to process in one call, structure your subsequent queries iteratively or use pagination parameters if they become available.

**How can I search for datasets related to a specific topic like 'Health'?**
You can use the `search_packages` tool with a query string. For example, searching for 'saude' will return all datasets categorized under health in the Campinas portal.

**Can I see which city departments are publishing data?**
Yes! Use the `list_organizations` tool to get a complete list of all city departments and entities that contribute to the Open Data Portal.

**How do I get the download link for a specific data file?**
Use the `get_resource` tool with the specific Resource ID. It will return the metadata, including the URL to download the file (CSV, PDF, etc.).