# Dados RS MCP

> Rio Grande do Sul (Dados RS) connects your AI client directly to the official public dataset portal. It lets you search, list, and query government records from Rio Grande do Sul without downloading files manually. Use tools like `search_datasets` to find data on education or finance, or run complex SQL queries against the DataStore using `search_datastore_sql`. This is direct access to state-level public information.

## Overview
- **Category:** data-management
- **Price:** Free
- **Tags:** open-data, brazil, public-sector, ckan, regional-statistics, data-transparency

## Description

Listen up. This **Dados RS** server connects your AI client right into the official public data portal for Rio Grande do Sul. It lets you work with government records without ever having to mess around downloading files manually. You're getting direct access to state-level public information, and it’s built entirely on tools so your agent can handle it.

When you need to find what kind of data exists out there, you start broad. Use `list_datasets` to get a master list of every single public dataset available on the portal. If you're looking for something more specific, `search_datasets` lets you pinpoint datasets just by throwing in keywords or topics—say, education or finance. You can also narrow your search down using `list_groups`, which gives you thematic data groups like 'Environment' or 'Security,' or run `list_organizations` to see all the government bodies that publish this stuff.

Need to drill into what a specific dataset is about? Don't just rely on keywords. Use `show_dataset` to pull all the metadata and details for a package you found, which tells you everything about its resources and who maintains it. If you want to inspect an individual file or resource attached to a dataset, run `show_resource` to get its structure and metadata. You can also check out the backstory using `show_organization`, which gives you a full profile for any government body that published data.

When discovery isn't enough, you gotta query the raw numbers. If you think certain keywords live inside structured tables in the DataStore, use `search_datastore` to search across those key terms directly. But if you need maximum power—the kind of deep dive that requires specific filtering and joining tables—you run complex Structured Query Language (SQL) commands with `search_datastore_sql`. This tool lets your agent talk straight to the raw database layer, pulling exact data points you specify.

If you just want a comprehensive overview of every group or organization available on the portal, `show_group` pulls up detailed information for any specified thematic area. The whole point here is that your AI client doesn't guess; it executes these tools—from finding general packages with `search_resources` to running complicated SQL queries against the DataStore via `search_datastore_sql`—giving you structured results every time.

## Tools

### search_datastore_sql
Allows running custom, complex SQL queries directly against the raw data store.

### search_datastore
Searches key terms across structured data tables in the DataStore.

### list_groups
Retrieves a list of thematic data groups (e.g., 'Environment' or 'Security').

### show_group
Retrieves detailed information for a specified thematic data group.

### list_organizations
Lists all government bodies that publish data on Dados RS.

### show_organization
Gets the profile and full details for a specific government organization.

### list_datasets
Lists every public dataset available on the portal.

### search_datasets
Finds datasets by searching keywords or topics within the catalog.

### show_dataset
Pulls all the metadata and details about a specific, named dataset package.

### search_resources
Searches for specific individual files or metadata resources within a dataset.

### show_resource
Displays metadata and structure for an individual data file or resource attached to a dataset.

## Prompt Examples

**Prompt:** 
```
Search for datasets about 'educação' in Rio Grande do Sul.
```

**Response:** 
```
I found several datasets related to education, including 'Escolas Estaduais' and 'Taxa de Analfabetismo'. Which one would you like to explore further?
```

**Prompt:** 
```
List all government organizations available on the Dados RS portal.
```

**Response:** 
```
I've retrieved the list of organizations. There are over 50 bodies, including the 'Secretaria da Saúde', 'Secretaria da Fazenda', and 'Brigada Militar'.
```

**Prompt:** 
```
Show the details for the dataset 'receita-corrente-liquida'.
```

**Response:** 
```
The dataset 'Receita Corrente Líquida' contains metadata about state revenue. It includes 3 resources (CSV and PDF) and is maintained by the Secretaria da Fazenda.
```

## Capabilities

### Search available data packages
The agent finds multiple relevant public datasets across different topics using keyword searches.

### Query raw database tables with SQL
You run complex Structured Query Language (SQL) commands directly against the DataStore to pull specific data points.

### List all official publishing organizations
The agent retrieves a complete list of government bodies that manage and publish data on the portal.

### View metadata for any dataset or resource
You get detailed information about a specific data package, including its resources, maintainer, and structure.

## Use Cases

### Auditing public spending records
A journalist needs to track state revenue changes. Instead of manually navigating the finance portal, they ask their agent: 'Find all datasets related to state revenue.' The agent runs `search_datasets` and identifies 'receita-corrente-liquida'. They then use `show_dataset` to confirm it's from the correct source before pulling specific records.

### Building a local data dashboard
A developer needs real-time educational stats. They instruct their agent: 'Get current school enrollment numbers.' The agent uses `search_datastore` to find relevant tables, and then runs a targeted query via `search_datastore_sql` to pull the exact counts needed for an API endpoint.

### Mapping governmental data ownership
A researcher wants a full picture of environmental regulations. They start by running `list_groups` and narrow it to 'Environment'. Then they use `search_datasets` within that group, and finally run `show_organization` for each resulting dataset to determine which state body published the rules.

### Verifying data completeness
A team wants to ensure all related stats are present. They ask their agent to list all datasets (`list_datasets`). Then, they check the organizations involved (`list_organizations`) and use `show_organization` for key players (like 'Secretaria da Saúde') to verify data coverage.

## Benefits

- Stop guessing where data lives. Use `search_datasets` or `list_groups` to quickly narrow down public datasets by topic (like 'Health' or 'Economy').
- Bypass the GUI entirely. Instead of clicking through filters, use `search_datastore_sql` to run precise SQL queries against the raw data layer.
- Get full context before downloading. Run `show_dataset` or `show_resource` to inspect metadata and understand a file's structure first.
- Map out who owns the data. Use `list_organizations` and then `show_organization` to trace which government body is responsible for specific records.
- Find everything in one flow. Your agent can run `search_datasets` followed by `show_resource` to map a dataset down to its individual components, all in one chat session.

## How It Works

The bottom line is: you talk to your agent, it talks to this server, and you get clean data structures back without touching a website GUI.

1. Your agent identifies the need (e.g., finding all education records).
2. It invokes the correct tool (`search_datasets`, `list_organizations`, etc.) with specific parameters.
3. The server connects to Dados RS and returns structured JSON data containing the requested metadata or query results.

## Frequently Asked Questions

**How do I start finding data about education using search_datasets?**
Use `search_datasets` with 'educação'. This will return all packages tagged or named related to education, giving you a list of options like 'Escolas Estaduais' to choose from.

**What is the difference between search_datastore and search_datastore_sql?**
`search_datastore` handles simple keyword searches across existing data structures. `search_datastore_sql` lets you run custom, complex SQL queries for maximum control over your results.

**Can I use show_organization to find a specific dataset?**
No. `show_organization` only gives details about the publishing body. You must first use `list_organizations` or `search_datasets` to get the data package, then run `show_dataset` to see who published it.

**How do I list all groups and their contents?**
First, call `list_groups`. This gives you a master list of thematic categories. Then, if you want details on one group (e.g., 'Economy'), run `show_group`.

**What should I do if I hit rate limits when calling list_datasets?**
You need to provide your Dados RS API Key for higher rate limits. Adding the key ensures consistent data access, which is crucial when running many calls like listing all datasets or checking multiple resources.

**When should I use show_resource versus running an SQL query with search_datastore_sql?**
Use `show_resource` to get metadata and understand a file's structure before using it. Use `search_datastore_sql` when you need to run complex operations directly on the raw, tabular data tables.

**If search_datasets returns no results, does that mean the data doesn't exist?**
No; it usually means your search terms need refinement. Try using broader keywords or checking related thematic groups first via `list_groups` to narrow down your scope.

**Does list_organizations only show government bodies, or does it include private sources?**
It lists official government organizations that publish public sector data. This server connects exclusively to the authorized open data portal for Rio Grande do Sul state records.

**How can I search for datasets related to a specific topic like 'COVID'?**
Use the `search_datasets` tool with the `q` parameter set to your topic. For example, searching for 'covid' will return all matching packages from the portal.

**Can I perform advanced data analysis using SQL on the portal's data?**
Yes! The `search_datastore_sql` tool allows you to execute full SQL SELECT statements against datasets stored in the CKAN DataStore, enabling complex filtering and aggregation.

**How do I find which government departments are publishing data?**
Use the `list_organizations` tool to get a complete list of all government bodies. You can then use `show_organization` with a specific ID to see their metadata and datasets.