Brasil API MCP

Instructions

Implementation Reference

• src/tools/registrobr/index.ts:18-75 (handler)

  The core handler function that processes the domain input, calls the BrasilAPI, and formats the markdown response with availability status, nameservers, expiry, and suggestions.

      async ({ domain }) => {
        console.error(`Checking domain status: ${domain}`);
        
        // Make sure we're using the domain name only without http or https
        let cleanDomain = domain.toLowerCase();
        cleanDomain = cleanDomain.replace(/^https?:\/\//i, "");
        cleanDomain = cleanDomain.replace(/^www\./i, "");
        
        // If domain doesn't end with .br, we don't add it automatically
        // as the API accepts any domain name to evaluate
  
        const result = await getBrasilApiData(`/registrobr/v1/${cleanDomain}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error checking domain: ${result.message}`);
        }
        
        // Format the response data
        const domainInfo = result.data;
        
        // Create a formatted response based on the domain status
        let statusText;
        if (domainInfo.status === "AVAILABLE") {
          statusText = `${cleanDomain} is AVAILABLE for registration`;
        } else if (domainInfo.status === "REGISTERED") {
          statusText = `${cleanDomain} is REGISTERED`;
          
          // Add more details if available
          if (domainInfo.hosts && domainInfo.hosts.length > 0) {
            statusText += `\nNameservers: ${domainInfo.hosts.join(", ")}`;
          }
          
          if (domainInfo.expiresAt) {
            statusText += `\nExpires at: ${domainInfo.expiresAt}`;
          }
          
          if (domainInfo.suggestions && domainInfo.suggestions.length > 0) {
            statusText += `\n\nSimilar available domains:\n${domainInfo.suggestions.join("\n")}`;
          }
        } else {
          statusText = `Status for ${cleanDomain}: ${domainInfo.status}`;
          
          if (domainInfo.suggestions && domainInfo.suggestions.length > 0) {
            statusText += `\n\nSuggested available domains:\n${domainInfo.suggestions.join("\n")}`;
          }
        }
        
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Domain Check Result:
  ${statusText}
  ` 
          }]
        };
      }
    );

• src/tools/registrobr/index.ts:14-17 (schema)

  Zod input schema defining the 'domain' parameter for the tool.

  {
    domain: z.string()
      .describe("Domain name to check (with or without .br extension)")
  },

• src/tools/registrobr/index.ts:9-76 (registration)

  The registration function for the Registro.br tool, called from main index to add the tool to the MCP server.

  export function registerRegistroBrTools(server: McpServer) {
    // Tool to check domain availability and status in Registro.br
    server.tool(
      "registrobr-domain-check",
      "Check the status and availability of a .br domain name",
      {
        domain: z.string()
          .describe("Domain name to check (with or without .br extension)")
      },
      async ({ domain }) => {
        console.error(`Checking domain status: ${domain}`);
        
        // Make sure we're using the domain name only without http or https
        let cleanDomain = domain.toLowerCase();
        cleanDomain = cleanDomain.replace(/^https?:\/\//i, "");
        cleanDomain = cleanDomain.replace(/^www\./i, "");
        
        // If domain doesn't end with .br, we don't add it automatically
        // as the API accepts any domain name to evaluate
  
        const result = await getBrasilApiData(`/registrobr/v1/${cleanDomain}`);
        
        if (!result.success) {
          return formatErrorResponse(`Error checking domain: ${result.message}`);
        }
        
        // Format the response data
        const domainInfo = result.data;
        
        // Create a formatted response based on the domain status
        let statusText;
        if (domainInfo.status === "AVAILABLE") {
          statusText = `${cleanDomain} is AVAILABLE for registration`;
        } else if (domainInfo.status === "REGISTERED") {
          statusText = `${cleanDomain} is REGISTERED`;
          
          // Add more details if available
          if (domainInfo.hosts && domainInfo.hosts.length > 0) {
            statusText += `\nNameservers: ${domainInfo.hosts.join(", ")}`;
          }
          
          if (domainInfo.expiresAt) {
            statusText += `\nExpires at: ${domainInfo.expiresAt}`;
          }
          
          if (domainInfo.suggestions && domainInfo.suggestions.length > 0) {
            statusText += `\n\nSimilar available domains:\n${domainInfo.suggestions.join("\n")}`;
          }
        } else {
          statusText = `Status for ${cleanDomain}: ${domainInfo.status}`;
          
          if (domainInfo.suggestions && domainInfo.suggestions.length > 0) {
            statusText += `\n\nSuggested available domains:\n${domainInfo.suggestions.join("\n")}`;
          }
        }
        
        return {
          content: [{ 
            type: "text" as const, 
            text: `
  Domain Check Result:
  ${statusText}
  ` 
          }]
        };
      }
    );
  }

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

  Utility function to make API requests to BrasilAPI, handling success and error responses. Used to fetch domain 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
      };
    }
  }

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

  Utility function to format error messages into MCP-compatible responses. Used when API calls fail.

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