# STF Dados Abertos MCP

> STF Dados Abertos connects your AI client directly to the Brazilian Supreme Federal Court's open data portal. You can list all available datasets, search for specific legal topics, and run structured queries against massive judicial records without downloading files. It gives you immediate access to metadata, organizational structures, and query results from Brazil’s largest public legal repository.

## Overview
- **Category:** knowledge-management
- **Price:** Free
- **Tags:** brazil-law, legal-transparency, stf, open-data, judicial-data

## Description

Yo, listen up. This server hooks your AI agent straight into the Brazilian Supreme Federal Court's open data portal—STF Dados Abertos. Forget downloading massive files just to find one piece of info; this lets you run structured queries and analyze judicial records using natural language prompts. It gives you immediate access to deep metadata, organizational structure, and query results from Brazil’s biggest public legal repository without the headache.

When you're scoping out what data's available, you start by listing everything. You can use `list_packages` or `search_packages` to see every dataset package hosted on the portal, or you can narrow it down fast by running a keyword search across the whole catalog. Need something specific? Running a targeted search with `search_packages` lets you pinpoint relevant legal packages immediately.

Once you've found a potential dataset, you need to know what you're dealing with. You can use `get_package` to get all the metadata and resource links for an entire package. If you want details on just one file within that set—the format, size, or specific record info—you run `get_resource`. For a deeper dive into a dataset’s structure, `get_metadata` pulls comprehensive information about what's inside. This whole process lets you map out the data's exact shape before running any queries.

If you know roughly where your data lives, you can find it by listing all available organizational groups using `list_groups`. From there, you can drill down to get detailed metadata and information for a specific group using `get_group`, or you can learn about the source itself with `list_organizations` which gives you a list of every institution contributing data. To see who's behind the curtain, run `get_organization` to fetch comprehensive details on any single institutional organization.

Now comes the good part: querying the live stuff. You don’t wanna download gigabytes just to check three rows, right? That's where `search_datastore` shines. It lets you perform structured, SQL-like queries directly against a resource's live data store, pulling out exactly the targeted information you need instantly.

This setup gives your AI client granular control over judicial and institutional data. You can first list all available organizational groups with `list_groups`, then check which institutions are feeding that data using `list_organizations`. By pairing those calls with `get_organization` or `get_group`, you trace the entire data provenance—you know exactly who's responsible for maintaining the open data sets. If you suspect a certain dataset is key, run `get_package` to inspect its metadata and resource links. To find that package in the first place, use `search_packages` with your keywords. Once selected, if you want deep structural details on any file, check it with `get_resource`. Remember, running `search_datastore` is your main tool for getting answers without downloading a single mega-file.

## Tools

### get_group
Retrieves the detailed metadata and information for a specified organizational group within STF Dados Abertos.

### get_organization
Fetches comprehensive details about a specific institutional organization that contributes data to the portal.

### get_package
Gets all available metadata and resource links for an entire dataset (package).

### get_resource
Retrieves detailed information, including formats and size, for a specific data file or record within a package.

### list_groups
Lists all available organizational groups that categorize the open data sets.

### list_organizations
Provides a list of all institutional organizations contributing to STF Dados Abertos.

### list_packages
Lists every available dataset package hosted on the STF open data portal.

### search_datastore
Runs structured, SQL-like queries against a specific resource's live data store to extract targeted information.

### search_packages
Searches the entire catalog of datasets using keywords and filters to find relevant packages.

## Prompt Examples

**Prompt:** 
```
List all available datasets in the STF Dados Abertos portal.
```

**Response:** 
```
I've retrieved the list of datasets. Notable packages include 'Processos Eletrônicos', 'Gastos com Pessoal', and 'Decisões'. Which one would you like to explore further?
```

**Prompt:** 
```
Search for datasets related to 'votações'.
```

**Response:** 
```
Searching... I found 3 datasets matching 'votações'. The most relevant is 'Votações em Plenário'. Would you like to see the available resources for this package?
```

**Prompt:** 
```
Get the details and resources for the dataset 'folha-de-pagamento'.
```

**Response:** 
```
Fetching details for 'folha-de-pagamento'... This dataset contains 12 resources (CSV and JSON formats) and is maintained by the 'Secretaria de Gestão Estratégica'. Do you want to inspect a specific resource ID?
```

## Capabilities

### Find Available Datasets
List all available datasets or search the catalog using keywords to pinpoint relevant legal packages.

### Query Structured Data Stores
Perform targeted, SQL-like queries directly on data resources without downloading entire files.

### Get Metadata Details
Retrieve deep metadata for specific datasets (packages) or individual files (resources), revealing their structure and update history.

### Map Data Provenance
List and inspect the organizational groups and institutions responsible for maintaining the open data, showing its source.

### Search Across Packages
Filter the entire catalog of available datasets by specific keywords or criteria.

## Use Cases

### Tracking changes in public spending
A journalist needs to compare budget allocations across three different years. Instead of opening three separate datasets and cross-referencing dates, they ask their agent to use `list_packages` to find the correct financial records, then run targeted queries with `search_datastore` to pull comparative figures into one output.

### Investigating a legal precedent
A law student needs facts from an obscure case file. They use `search_packages` for 'precedent' and then, when they find the correct package, they run `get_resource` to inspect the available files before asking the agent to retrieve specific data points using `get_package` details.

### Mapping institutional responsibility
A corporate compliance analyst needs to know who owns a particular type of public record. They use `list_organizations` and then drill down with `get_organization` until they identify the exact responsible department, documenting the data source's ownership.

### Validating dataset scope
A developer integrating STF data needs to know if a resource contains salary information. They first use `search_packages` to find the payroll package, then they call `get_resource` and inspect the metadata fields before writing any integration code.

## Benefits

- Skip manual browsing. Instead of clicking through menus to find a dataset, simply use `search_packages` and tell your agent what you need by topic or keyword.
- Stop downloading huge ZIP files just to check one column. Use `search_datastore` to run precise queries on live data resources directly in the chat output.
- Know where your data comes from. By calling `get_organization`, you immediately map which department maintained a dataset, giving instant provenance context.
- Get the full picture of a data set's structure using `get_package`. This gives you all resource details and metadata upfront—no guessing what files are available.
- Build your knowledge graph. Use `list_groups` and `list_organizations` to systematically map out the entire institutional network contributing to STF’s open data.

## How It Works

The bottom line is: Your AI client talks to STF, and you get the answer without ever visiting a browser page.

1. Subscribe to this server and provide your API key, if required.
2. Send a natural language query (e.g., 'List all packages related to labor law').
3. The agent uses the appropriate tool (`list_packages`, `search_packages`, etc.) and returns structured metadata or data results directly in your chat.

## Frequently Asked Questions

**How do I find all available dataset packages using list_packages?**
Run the `list_packages` tool directly. This provides an immediate catalog of every major dataset category published by STF, giving you a starting point for your research.

**Can I run SQL queries on the data in STF Dados Abertos using search_datastore?**
Yes. `search_datastore` allows you to write structured queries against specific resources. This lets you filter and extract exact information without having to download large, raw files.

**How do I check the metadata for a whole dataset using get_package?**
Pass the package ID to `get_package`. This tool fetches comprehensive details, showing you all related resources and the overall structure of the data before you start querying.

**What is the difference between list_groups and list_organizations?**
Use `list_groups` to see how the open data is categorized (the thematic groups). Use `list_organizations` to see which specific institutional bodies are responsible for creating or maintaining that data.

**What specific details about an individual data file does the `get_resource` tool provide?**
It gives deep metadata for a single resource ID. You retrieve details like the file format (CSV, JSON), exact size in bytes, and the precise timestamp of when it was last updated.

**How do I refine my search to narrow down available datasets using `search_packages`?**
The tool filters the entire dataset catalog based on keywords you provide. You pass a topic or phrase, and it returns a list of matching package IDs, so you don't have to sift through irrelevant results.

**If my data queries hit the default rate limit, how do I increase my access capacity?**
You must provide your STF API Key in the server settings. Using this key bypasses standard usage limits and grants you higher request quotas for repeated or large-scale querying.

**Using `get_organization`, how do I determine who is responsible for a specific data package?**
You use the tool with the relevant organizational ID. This pulls details about the maintainer group, showing their official scope and purpose within the court's structure.

**Can I perform SQL-like queries on the court's data files?**
Yes! If a resource is integrated into the DataStore, you can use the `search_datastore` tool with the Resource ID to query the data within the file directly.

**How do I find datasets related to a specific legal topic?**
Use the `search_packages` tool. Simply provide a search term (e.g., 'processos' or 'votação') and the agent will return all matching datasets from the portal.

**Is it possible to list all organizations that publish data on the STF portal?**
Absolutely. Use the `list_organizations` tool to see all departments and entities, or `get_organization` to see details and datasets owned by a specific one.