Brasil API MCP

Instructions

Implementation Reference

• src/tools/ddd/index.ts:19-42 (handler)

  The handler function for the 'ddd-info' tool. It fetches DDD data from BrasilAPI, processes cities, and returns formatted text or error response.

      async ({ ddd }) => {
        console.error(`Getting info for DDD: ${ddd}`);
        
        const result = await getBrasilApiData(`/ddd/v1/${ddd}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error getting DDD information: ${result.message}`);
        }
        
        // Format the response data
        const dddInfo = result.data;
        const cities = dddInfo.cities.join(", ");
        
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  DDD ${ddd} Information:
  State: ${dddInfo.state}
  Cities: ${cities}
  ` 
          }]
        };
      }

• src/tools/ddd/index.ts:14-18 (schema)

  Zod input schema for the 'ddd-info' tool validating a 2-digit DDD string.

  {
    ddd: z.string()
      .regex(/^\d{2}$/, "DDD must contain exactly 2 digits")
      .describe("Area code (DDD) to be queried (only numbers, 2 digits)")
  },

• src/tools/ddd/index.ts:11-43 (registration)

  Registration of the 'ddd-info' tool on the MCP server, specifying name, description, input schema, and handler.

    server.tool(
      "ddd-info",
      "Get information about a Brazilian area code (DDD) including state and cities",
      {
        ddd: z.string()
          .regex(/^\d{2}$/, "DDD must contain exactly 2 digits")
          .describe("Area code (DDD) to be queried (only numbers, 2 digits)")
      },
      async ({ ddd }) => {
        console.error(`Getting info for DDD: ${ddd}`);
        
        const result = await getBrasilApiData(`/ddd/v1/${ddd}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error getting DDD information: ${result.message}`);
        }
        
        // Format the response data
        const dddInfo = result.data;
        const cities = dddInfo.cities.join(", ");
        
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  DDD ${ddd} Information:
  State: ${dddInfo.state}
  Cities: ${cities}
  ` 
          }]
        };
      }
    );

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

  Utility function to fetch data from BrasilAPI endpoints, returning structured success/error responses.

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

• src/utils/api.ts:47-54 (helper)

  Utility function to format error messages into MCP tool response format.

  export function formatErrorResponse(message: string) {
    return {
      content: [{ 
        type: "text" as const, 
        text: message 
      }],
      isError: true
    };