ibge-municipalities-list

Instructions

Implementation Reference

• src/tools/ibge/index.ts:81-115 (handler)

  Handler function that fetches municipalities list from Brasil API for given state 'uf', formats it (shows first 30 if more than 50), handles errors.

  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)

  Zod schema defining the input parameter 'uf': state abbreviation (e.g., SP, RJ).

  {
    uf: z.string()
      .describe("State abbreviation (e.g., SP, RJ)")
  },

• src/tools/ibge/index.ts:74-116 (registration)

  Registers the tool 'ibge-municipalities-list' on the MCP server with description, input schema, and handler function.

  server.tool(
    "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 the 'ibge-municipalities-list' tool.

  registerIbgeTools(server);

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

  Utility to fetch data from Brasil API endpoints via axios, handles errors, used by the tool handler.

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