ibge-state-search

Find information about Brazilian states using state codes or abbreviations. Retrieve IBGE data for states through the Brasil API MCP server.

Instructions

Find information about a Brazilian state by its code or abbreviation

Input Schema

TableJSON Schema

Name	Required	Description	Default
`code`	Yes	State code or abbreviation (e.g., SP, RJ, 35)

Implementation Reference

src/tools/ibge/index.ts:47-70 (handler)

The handler function for the 'ibge-state-search' tool. It takes a state code or abbreviation, fetches data from BrasilAPI, handles errors, and formats the state information (name, sigla, region, ID) into a text response.

    async ({ code }) => {
      console.error(`Finding state by code/abbreviation: ${code}`);
      
      const result = await getBrasilApiData(`/ibge/uf/v1/${code}`);
      
      if (!result.success) {
        return formatErrorResponse(`Error finding state: ${result.message}`);
      }
      
      // Format the response data
      const state = result.data;
      return {
        content: [{ 
          type: "text" as const, 
          text: `
State Information:
Name: ${state.nome}
Abbreviation: ${state.sigla}
Region: ${state.regiao.nome}
ID: ${state.id}
` 
        }]
      };
    }

src/tools/ibge/index.ts:43-46 (schema)
Zod schema for the tool input, validating the 'code' parameter as a string with description.
```
{
  code: z.string()
    .describe("State code or abbreviation (e.g., SP, RJ, 35)")
},
```

src/tools/ibge/index.ts:39-71 (registration)

Registration of the 'ibge-state-search' tool on the MCP server, including name, description, input schema, and handler function.

  // Tool to find state by code or abbreviation
  server.tool(
    "ibge-state-search",
    "Find information about a Brazilian state by its code or abbreviation",
    {
      code: z.string()
        .describe("State code or abbreviation (e.g., SP, RJ, 35)")
    },
    async ({ code }) => {
      console.error(`Finding state by code/abbreviation: ${code}`);
      
      const result = await getBrasilApiData(`/ibge/uf/v1/${code}`);
      
      if (!result.success) {
        return formatErrorResponse(`Error finding state: ${result.message}`);
      }
      
      // Format the response data
      const state = result.data;
      return {
        content: [{ 
          type: "text" as const, 
          text: `
State Information:
Name: ${state.nome}
Abbreviation: ${state.sigla}
Region: ${state.regiao.nome}
ID: ${state.id}
` 
        }]
      };
    }
  );

src/index.ts:29-29 (registration)
Top-level registration call to registerIbgeTools, which includes the 'ibge-state-search' tool among others.
```
registerIbgeTools(server);
```

src/utils/api.ts:11-40 (helper)

Helper function used by the handler to fetch data from the BrasilAPI endpoint.

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
    };
  }
}

Brasil API MCP