ApiColombiaMCP

Instructions

Implementation Reference

• src/services/regions.services.ts:56-104 (handler)

  The handler function that implements the logic for the getRegionById tool. It fetches detailed information about a specific region from the Colombia API using the provided regionId, handles errors including 404, formats the response in a readable text format, and returns it as ApiColombiaResponse.

  export async function getRegionById(regionId: string): Promise<ApiColombiaResponse> {
      try {
          const apiUrl = process.env.API_COLOMBIA_URL || 'https://api-colombia.com/api/';
          const response = await fetch(`${apiUrl}v1/Region/${regionId}`);
          
          if (!response.ok) {
              if (response.status === 404) {
                  return {
                      content: [{
                          type: 'text',
                          text: `❌ No se encontró una región con el ID: ${regionId}`
                      }]
                  };
              }
              throw new Error(`HTTP error! status: ${response.status}`);
          }
          
          const regionData: RegionData = await response.json();
          
          // Format the region data into a readable text format
          const regionInfo = `
  🇨🇴 DETALLE DE LA REGIÓN
  ${'═'.repeat(80)}
  
  🌎 REGIÓN: ${regionData.name}
  📍 ID: ${regionData.id}
  📝 Descripción: ${regionData.description}
  ${regionData.departments ? `🏛️ Departamentos: ${regionData.departments.join(', ')}` : '🏛️ Departamentos: No especificados'}
  
  ${'═'.repeat(80)}
          `;
          
          return {
              content: [{
                  type: 'text',
                  text: regionInfo.trim()
              }]
          };
          
      } 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:24-28 (registration)

  Registration of the 'getRegionById' tool in the tools configuration array, linking the name, description from constants, and the handler function.

  {
    name: TOOL_NAMES.GET_REGION_BY_ID,
    description: TOOL_DESCRIPTIONS.GET_REGION_BY_ID,
    handler: getRegionById,
  },

• src/shared/constants/index.ts:1-13 (schema)

  Constants defining the tool name ('getRegionById') and description used in the tool schema and registration.

  export const TOOL_NAMES = {
    GET_COUNTRY: 'getCountry',
    GET_REGIONS: 'getRegions',
    GET_REGION_BY_ID: 'getRegionById',
    GET_DEPARTMENTS_BY_REGION: 'getDepartmentsByRegion',
  } as const;
  
  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;

• src/services/regions.services.ts:4-9 (helper)

  Type definition for the region data structure used in the getRegionById handler.

  interface RegionData {
      id: number;
      name: string;
      description: string;
      departments: string[] | null;
  }