brasil-api-mcp-server

Instructions

Implementation Reference

• src/tools/cep-v2.ts:20-34 (handler)

  The handler function that implements the core logic of the tool: fetches postal code (CEP) data from Brasil API using the provided CEP and returns formatted text response or throws an error.

  handler: async ({ cep }): Promise<McpResponse> => {
    try {
      const result = await brasilApiClient.cep.getBy(cep);
      const content: McpTextContent = {
        type: "text",
        text: `CEP found:\n${prettifyJson(result.data)}`,
      };
      return {
        content: [content],
      };
    } catch (error: any) {
      console.error(error);
      throw new Error(`Failed to fetch cep ${cep}`);
    }
  },

• src/tools/cep-v2.ts:10-12 (schema)

  Zod-based input schema defining the required 'cep' parameter as a string.

  const getCepV2ToolParams = {
    cep: z.string().describe("The CEP to query"),
  };

• src/tools/cep-v2.ts:16-35 (registration)

  The tool definition object exported from the file, specifying name, description, params schema, and handler.

  export const getCepV2Tool: McpToolDefinition<GetCepV2ToolParams> = {
    name: "get_postal_code_v2",
    description: "Version 2 of get a location data given a CEP (postal code).",
    params: getCepV2ToolParams,
    handler: async ({ cep }): Promise<McpResponse> => {
      try {
        const result = await brasilApiClient.cep.getBy(cep);
        const content: McpTextContent = {
          type: "text",
          text: `CEP found:\n${prettifyJson(result.data)}`,
        };
        return {
          content: [content],
        };
      } catch (error: any) {
        console.error(error);
        throw new Error(`Failed to fetch cep ${cep}`);
      }
    },
  };

• src/index.ts:30-41 (registration)

  The tool is imported and included in the central tools array, then registered to the MCP server.

  const tools = [
    getCepTool,
    getCepV2Tool,
    getBookByISBNTool,
    getCNPJTool,
    getAllBanksTool,
    getBankByCodeTool,
  ];
  
  tools.forEach((tool) => {
    registerTool(server, tool);
  });