# Campinas Open Data MCP

> Campinas Open Data connects your AI agent directly to the Campinas Open Data Portal, allowing you to explore public datasets from city departments. You can search for specific topics like health or education, list all available organizations, and retrieve detailed metadata for any resource—CSV, PDF, or API endpoint. It’s pure data discovery, straight out of Brazil's civic records.

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

## Description

Need information on urban policy but don't know where to start? This MCP lets you talk to the Campinas Open Data Portal like a human librarian. You simply ask your agent what you need—maybe datasets related to public spending or transport infrastructure—and it handles the deep search through thousands of records. It doesn't just give you links; it helps map out which city departments own which data packages, and it provides full technical metadata for every file type found. This is how you get structured insight without manual clicking. The Vinkius catalog makes this connection available across any compatible AI client, meaning your research workflow stays in one place. You can inspect the API schemas of resources or find thematic groups like 'Education' or 'Finance' with simple conversation prompts.

## Tools

### campinas_list_groups
Lists all major thematic groups used to categorize the available datasets.

### campinas_list_organizations
Provides a list of every city department that contributes data to the portal.

### campinas_list_packages
Lists the names of all available dataset packages in the portal.

### campinas_search_packages
Searches for datasets that match specific keywords or criteria you provide.

### campinas_get_package
Retrieves the full metadata definition for a specific dataset package.

### campinas_search_resources
Searches for individual data files (resources) based on defined fields like name or category.

### campinas_get_resource
Gets metadata details about one specific data resource within a package.

### campinas_list_tags
Returns a list of all tags used to categorize data across the entire platform.

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

### Discover specific datasets
Search for data packages using keywords across all available topics.

### Map city departments
Get a complete list of organizations that contribute public data to the portal.

### Inspect data structure metadata
Retrieve full technical details for any dataset or individual resource file, showing formats and update dates.

### Filter by topic group or tag
Narrow down the scope of search results to a specific thematic category (e.g., 'Health' or 'Transport').

### Find raw resources and links
Get direct access points and metadata for files like CSVs, PDFs, or API endpoints.

## Use Cases

### Finding all public records on education
A researcher needs every dataset related to schooling. They ask their agent, which uses `campinas_list_groups` first to see the 'Education' category, then uses `campinas_search_packages` within that group to pull out specific datasets like 'Vagas em Creches'.

### Verifying data source ownership
An analyst needs to know who published a dataset before using it. They use `campinas_list_organizations` to get a definitive list of all contributing entities, ensuring they cite the correct department.

### Inspecting an unknown data schema
A developer finds a promising but opaque dataset name. Instead of downloading it and trying to parse it, they run `campinas_get_package` for full metadata, immediately seeing if the required fields exist.

## Benefits

- Stop guessing where data lives. By using `campinas_list_organizations`, you immediately see every department providing records, eliminating the need to check multiple departmental websites manually.
- You don't have to sift through everything. If you know your topic (e.g., 'health'), use `campinas_search_packages` to filter thousands of datasets down to relevant groups instantly.
- Metadata deep dive: When a dataset looks promising, run `campinas_get_package` to get the full technical schema, letting developers know exactly what fields they're dealing with before writing code.
- Better browsing: If you just want an idea of available topics, checking the thematic groups via `campinas_list_groups` gives you a quick map of all civic data domains.
- Pinpoint resources: Instead of searching by dataset name, use `campinas_search_resources` to hunt for specific files—like a single PDF report on spending—using its unique fields.

## How It Works

The bottom line is you talk to it naturally; the MCP figures out which tool calls are needed behind the scenes.

1. Subscribe to the MCP and provide your Campinas Portal API Key (if restricted access is needed).
2. Ask your AI client a discovery question, such as 'List all organizations that hold data on transport.'
3. The agent executes the necessary lookups and returns structured metadata about packages, groups, or specific resources.

## Frequently Asked Questions

**How do I find all groups in Campinas data using campinas_list_groups?**
Run `campinas_list_groups`. This tool provides the top-level thematic groupings (like 'Health' or 'Education'). It’s a quick way to map out every major domain of public records available.

**What is the difference between campinas_search_packages and campinas_list_packages?**
Use `campinas_list_packages` for a raw, exhaustive list of *all* dataset names. Use `campinas_search_packages` when you know keywords and want to narrow that huge list down to only the relevant results.

**Can campinas_get_resource tell me what format the data is in?**
Yes, `campinas_get_resource` provides metadata for individual files. It tells you if the resource is a CSV, PDF, or API endpoint, which dictates how your agent can access it.

**Do I need to use campinas_list_organizations first?**
It’s helpful but not required. Using `campinas_list_organizations` gives you a map of contributors; if you know the organization name, you can skip it and go straight to searching data.

**When I use `campinas_get_package`, what specific fields can I expect to see in the dataset's metadata?**
It provides a detailed data dictionary, including update cycles and available field types. This lets you confirm the underlying structure before retrieving any resources or running queries.

**If I need to filter results by keywords within the actual files, how do I use `campinas_search_resources`?**
You must provide specific field names and exact values. This tool searches the data content itself, going deeper than just searching titles or descriptions.

**After running `campinas_list_tags`, how do I best use those keywords to narrow my search?**
The list gives you available categorization terms. You pass these tags into the search function (like `campinas_search_packages`) to filter results quickly by a common theme.

**What happens if `campinas_list_organizations` returns few or no entries?**
This usually means the data is restricted or requires special access. You should verify with the portal documentation or check if your API key needs specific permissions.

**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.).