ApiColombiaMCP

Instructions

Implementation Reference

• src/services/country.services.ts:32-80 (handler)

  The main handler function for the 'getCountry' tool. It fetches data about Colombia from the API Colombia service, formats it into a structured text response, handles errors, and returns an ApiColombiaResponse.

  export async function getCountry(): Promise<ApiColombiaResponse> {
      try {
          const apiUrl = process.env.API_COLOMBIA_URL || 'https://api-colombia.com/api/';
          const response = await fetch(`${apiUrl}v1/Country/Colombia`);
          
          if (!response.ok) {
              throw new Error(`HTTP error! status: ${response.status}`);
          }
          
          const countryData: CountryData = await response.json(); 
          
          const countryInfo = `
  Country: ${countryData.name}
  Capital: ${countryData.stateCapital}
  Population: ${countryData.population.toLocaleString()}
  Area: ${countryData.surface.toLocaleString()} km²
  Region: ${countryData.region} - ${countryData.subRegion}
  Languages: ${countryData.languages.join(', ')}
  Currency: ${countryData.currency} (${countryData.currencyCode} ${countryData.currencySymbol})
  Time Zone: ${countryData.timeZone}
  ISO Code: ${countryData.isoCode}
  Internet Domain: ${countryData.internetDomain}
  Phone Prefix: ${countryData.phonePrefix}
  Borders: ${countryData.borders.join(', ')}
  
  Description:
  ${countryData.description}
  
  Flag URLs:
  ${countryData.flags.join('\n')}
          `.trim();
          
          return {
              content: [{
                  type: 'text',
                  text: countryInfo
              }]
          };
          
      } catch (error) {
          const errorMessage = error instanceof Error ? error.message : ERROR_MESSAGES.UNKNOWN_ERROR;
          return {
              content: [{
                  type: 'text',
                  text: `${ERROR_MESSAGES.FETCH_ERROR}: ${errorMessage}`
              }]
          };
      }
  }

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

  Registers the 'getCountry' tool in the tools array, specifying its name, description (from constants), and handler function.

  {
    name: TOOL_NAMES.GET_COUNTRY,
    description: TOOL_DESCRIPTIONS.GET_COUNTRY,
    handler: getCountry,
  },

• src/tools/index.ts:7-11 (schema)

  Defines the schema/interface for tool configurations used in the registration, including handler signature expecting ApiColombiaResponse.

  export interface ToolConfig {
    name: string;
    description: string;
    handler: (...args: any[]) => Promise<ApiColombiaResponse>;
  }

• src/shared/constants/index.ts:1-6 (helper)

  Constants for tool names, including GET_COUNTRY used in tool registration.

  export const TOOL_NAMES = {
    GET_COUNTRY: 'getCountry',
    GET_REGIONS: 'getRegions',
    GET_REGION_BY_ID: 'getRegionById',
    GET_DEPARTMENTS_BY_REGION: 'getDepartmentsByRegion',
  } as const;

• src/shared/constants/index.ts:8-13 (helper)

  Constants for tool descriptions, including for GET_COUNTRY used in registration.

  export const TOOL_DESCRIPTIONS = {
    GET_COUNTRY: 'Get information about a country',
    GET_REGIONS: 'Get list of regions in Colombia',
    GET_REGION_BY_ID: 'Get detailed information about a specific region by ID',
    GET_DEPARTMENTS_BY_REGION: 'Get list of departments for a specific region by region ID',
  } as const;