ibge-municipalities-list
Retrieve a list of all municipalities in a Brazilian state by entering its abbreviation, simplifying access to IBGE data for research, planning, or analysis purposes.
Instructions
List all municipalities of a Brazilian state by its abbreviation
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| uf | Yes | State abbreviation (e.g., SP, RJ) |
Implementation Reference
- src/tools/ibge/index.ts:81-115 (handler)The handler function that executes the tool logic: fetches municipalities for the given state (uf) from the Brasil API, handles errors, formats the list (limiting if >50), and returns a formatted text response.async ({ uf }) => { console.error(`Listing municipalities for state: ${uf}`); const result = await getBrasilApiData(`/ibge/municipios/v1/${uf}`); if (!result.success) { return formatErrorResponse(`Error listing municipalities: ${result.message}`); } // Format the response data const municipalities = result.data; // If there are too many municipalities, limit the display let formattedText; if (municipalities.length > 50) { const first30 = municipalities.slice(0, 30).map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf} (showing first 30 of ${municipalities.length}):\n${first30}\n\n...and ${municipalities.length - 30} more municipalities.`; } else { const formattedMunicipalities = municipalities.map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf}:\n${formattedMunicipalities}`; } return { content: [{ type: "text" as const, text: formattedText }] }; }
- src/tools/ibge/index.ts:77-80 (schema)Input schema using Zod to validate the 'uf' parameter (state abbreviation).{ uf: z.string() .describe("State abbreviation (e.g., SP, RJ)") },
- src/tools/ibge/index.ts:75-116 (registration)Registers the 'ibge-municipalities-list' tool on the MCP server with name, description, input schema, and handler function."ibge-municipalities-list", "List all municipalities of a Brazilian state by its abbreviation", { uf: z.string() .describe("State abbreviation (e.g., SP, RJ)") }, async ({ uf }) => { console.error(`Listing municipalities for state: ${uf}`); const result = await getBrasilApiData(`/ibge/municipios/v1/${uf}`); if (!result.success) { return formatErrorResponse(`Error listing municipalities: ${result.message}`); } // Format the response data const municipalities = result.data; // If there are too many municipalities, limit the display let formattedText; if (municipalities.length > 50) { const first30 = municipalities.slice(0, 30).map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf} (showing first 30 of ${municipalities.length}):\n${first30}\n\n...and ${municipalities.length - 30} more municipalities.`; } else { const formattedMunicipalities = municipalities.map((municipality: any) => `${municipality.nome} (Code: ${municipality.codigo_ibge})` ).join("\n"); formattedText = `Municipalities in ${uf}:\n${formattedMunicipalities}`; } return { content: [{ type: "text" as const, text: formattedText }] }; } );
- src/index.ts:29-29 (registration)Top-level call to registerIbgeTools, which includes registration of the 'ibge-municipalities-list' tool.registerIbgeTools(server);
- src/utils/api.ts:11-40 (helper)Shared helper function to make API requests to brasilapi.com.br, used by the tool to fetch municipality data.export async function getBrasilApiData(endpoint: string, params: Record<string, any> = {}) { try { const url = `${BASE_URL}${endpoint}`; console.error(`Making request to: ${url}`); const response = await axios.get(url, { params }); return { data: response.data, success: true }; } catch (error: any) { console.error(`Error in API request: ${error.message}`); // Handle API errors in a structured format if (error.response) { return { success: false, statusCode: error.response.status, message: error.response.data?.message || error.message, error: error.response.data }; } return { success: false, message: error.message, error }; } }