🇨🇴 mcp-colombia-demo: Servidor MCP de Departamentos de Colombia

Servidor de Model Context Protocol (MCP) minimalista desarrollado en Node.js que conecta un Modelo de Lenguaje de Inteligencia Artificial (LLM) con la API REST oficial y pública de la República de Colombia para consultar información geográfica en tiempo real sobre los departamentos del país.

2. Descripción General

¿Qué es MCP (Model Context Protocol)?

Model Context Protocol (MCP) es un protocolo abierto y estandarizado desarrollado por Anthropic que actúa como un "conector universal" o "puerto USB" para aplicaciones de Inteligencia Artificial. Permite que los modelos de lenguaje (LLM) descubran, comprendan e invoquen de manera autónoma y segura fuentes de datos externas, bases de datos y herramientas locales.

¿Qué hace este proyecto?

Este proyecto expone un servidor MCP local que proporciona a cualquier cliente de IA (Claude Desktop, Cursor, VS Code, MCP Inspector) la capacidad de consultar datos geográficos reales sobre Colombia.

• API que utiliza: API pública de Colombia (https://api-colombia.com/api/v1).

• Herramienta que expone: obtener_departamentos.

• Beneficio para la IA: Gracias a este servidor MCP, el modelo de IA puede responder a preguntas del usuario utilizando datos oficiales y en tiempo real (capital, población, superficie en $\text{km}^2$, municipios y prefijo telefónico) evitando alucinaciones o datos desactualizados.

💡 Diferencia Fundamental: API vs MCP

• API REST: Es la fuente de información o servicio externo que almacena y entrega los datos mediante HTTP.

• MCP: Es el protocolo de comunicación estandarizado que describe la herramienta a la IA en formato JSON Schema, permitiendo que el modelo decida por sí solo cuándo y cómo invocar la API.

Related MCP server: psgc-mcp

3. ¿Qué problema resuelve?

Sin MCP (Desarrollo Tradicional)

En una aplicación convencional o chatbot estático sin conectores:

Usuario / Aplicación ──► Petición Rígida ──► API Colombia ──► Datos Estáticos

• Problema: El código es rígido y programado a mano para consultas fijas. Si el usuario hace una pregunta abierta o compleja, la IA depende de su memoria estática preentrenada, lo que produce información desactualizada o inventada (alucinaciones).

Con MCP (Model Context Protocol)

[Usuario] ──► [IA] ──► [MCP Client] ──► [MCP Server] ──► [Tool] ──► [API REST] ──► [Datos] ──► [MCP] ──► [IA] ──► [Usuario]

• Ventajas de MCP:

  1. Autonomía: La IA razona dinámicamente sobre la pregunta del usuario y decide por sí misma si debe consultar todos los departamentos o filtrar uno específico.

  2. Estandarización: Se escribe el servidor MCP una sola vez en Node.js y funciona en cualquier cliente compatible con MCP (Claude, Cursor, etc.).

  3. Veracidad: Garantiza respuestas basadas en datos reales provenientes directamente de la fuente oficial en tiempo real.

4. Arquitectura del Proyecto

┌──────────┐
│ Usuario  │
└────┬─────┘
     │ 1. Hace una pregunta en lenguaje natural ("¿Existe el departamento de Antioquia?")
     ▼
┌──────────────┐
│ Modelo de IA │ 2. Analiza las herramientas disponibles y emite un Tool Call
└──────┬───────┘
       │ 3. Solicitud JSON-RPC con argumentos ({ "nombre": "Antioquia" })
       ▼
┌──────────────┐
│  MCP Client  │ 4. Transmite el mensaje al servidor local mediante Stdio
└──────┬───────┘
       │
       ▼
┌──────────────┐
│  MCP Server  │ 5. Recibe la orden y ejecuta el controlador en index.js
└──────┬───────┘
       │ 6. Invoca la función interna de la Tool
       ▼
┌───────────────────────────┐
│ Tool obtener_departamentos│ 7. Petición HTTP GET con fetch()
└──────────┬────────────────┘
           │
           ▼
┌───────────────────────────┐
│  API Colombia (Externa)   │ 8. Devuelve objeto JSON con datos reales
└──────────┬────────────────┘
           │
           │ 9. Retorna la respuesta HTTP JSON
           ▼
┌───────────────────────────┐
│  MCP Server (Node.js)     │ 10. Filtra los campos y empaqueta en formato MCP
└──────────┬────────────────┘
           │
           │ 11. Envía resultado estructurado a la IA
           ▼
┌──────────────┐
│ Modelo de IA │ 12. Interpreta la información y genera la respuesta final
└──────┬───────┘
       │
       ▼
┌──────────┐
│ Usuario  │ 13. Recibe la respuesta informada en lenguaje natural
└──────────┘

Explicación de Componentes:

• Usuario: Entabla conversación mediante texto en lenguaje natural.

• Modelo de IA (LLM): Motor que razona la intención del usuario y decide si invocar herramientas.

• MCP Client: Aplicación (Claude Desktop, MCP Inspector, Cursor) que gestiona el canal de comunicación y le pasa las herramientas al LLM.

• MCP Server: Nuestro programa Node.js (index.js) que escucha por StdioServerTransport y ejecuta las funciones de la herramienta.

• Tool (obtener_departamentos): Función JavaScript que construye la URL y realiza la llamada fetch a la API.

• API Colombia: Servicio público externo REST que almacena los datos de la República de Colombia.

5. ¿Qué hace nuestra Tool?

Nombre

obtener_departamentos

Descripción

Obtiene información oficial de los departamentos de Colombia desde la API pública de Colombia. Permite obtener la lista completa de departamentos o consultar/buscar un departamento específico por su nombre.

Parámetros (JSON Schema)

• nombre (opcional, string): Nombre o palabra clave del departamento a consultar (ejemplo: "Antioquia", "Norte de Santander", "Cundinamarca"). Si se omite, retorna la lista completa.

Entrada (Input)

{
  "nombre": "Antioquia"
}

Proceso Interno

1. Captura y sanitiza el parámetro nombre.

2. Si se recibió un nombre, construye la URL https://api-colombia.com/api/v1/Department/search/Antioquia. Si no, usa https://api-colombia.com/api/v1/Department.

3. Ejecuta la llamada fetch(url) a la API REST.

4. Procesa la respuesta JSON y extrae únicamente los 7 campos más relevantes (id, nombre, capital, poblacion, superficie_km2, cantidad_municipios, prefijo_telefonico).

5. Empaqueta y devuelve la respuesta a la IA en el formato estándar MCP { content: [{ type: "text", text: "..." }] }.

Salida (Output para la IA)

[
  {
    "id": 2,
    "nombre": "Antioquia",
    "capital": "Medellín",
    "poblacion": 6887306,
    "superficie_km2": 63612,
    "cantidad_municipios": 125,
    "prefijo_telefonico": "4"
  }
]

6. Tecnologías y Herramientas Necesarias

7. Requisitos Previos

• Node.js: Versión 18.0.0 o superior instalada.

• Acceso a Internet: Perteneciente al entorno donde se ejecuta el servidor para consultar api-colombia.com.

• Sin llaves de API (API Keys): La API de Colombia es 100% libre y no requiere autenticación.

8. Estructura de Carpetas

mcp-colombia-demo/
├── index.js             # Código fuente principal del Servidor MCP y la Tool
├── package.json         # Configuración de dependencias y scripts de Node.js
├── package-lock.json    # Registro exacto de versiones instaladas
└── README.md            # Documentación general y guía del proyecto

9. Crear el Proyecto desde Cero (Paso a Paso)

Si deseas recrear este proyecto en una carpeta completamente vacía, sigue estos pasos:

Paso 1: Crear la carpeta del proyecto

mkdir mcp-colombia-demo
cd mcp-colombia-demo

Crea un directorio llamado mcp-colombia-demo y entra en él.

Paso 2: Inicializar el proyecto Node.js

npm init -y

Genera un archivo package.json por defecto con la configuración básica.

Paso 3: Configurar ES Modules y scripts en package.json

Edita package.json para asegurarte de incluir "type": "module" y el script de inspección:

{
  "name": "mcp-colombia-demo",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "scripts": {
    "start": "node index.js",
    "inspect": "npx @modelcontextprotocol/inspector node index.js"
  }
}

Paso 4: Instalar las dependencias de MCP

npm install @modelcontextprotocol/sdk

Descarga e instala el SDK oficial de Model Context Protocol en la carpeta node_modules.

Paso 5: Crear el archivo principal index.js

Crea el archivo index.js e incluye el código del servidor:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const API_BASE_URL = "https://api-colombia.com/api/v1";

const server = new Server(
  {
    name: "mcp-colombia-departamentos",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 1. Declarar la herramienta
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "obtener_departamentos",
        description:
          "Obtiene información oficial de los departamentos de Colombia desde la API pública de Colombia. Permite obtener la lista completa de departamentos o consultar/buscar un departamento específico por su nombre.",
        inputSchema: {
          type: "object",
          properties: {
            nombre: {
              type: "string",
              description:
                "Nombre o palabra clave del departamento a consultar (ejemplo: 'Antioquia', 'Norte de Santander', 'Cundinamarca'). Si se omite, retorna la lista de todos los departamentos de Colombia.",
            },
          },
          required: [],
        },
      },
    ],
  };
});

// 2. Ejecutar la herramienta
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name !== "obtener_departamentos") {
    throw new Error(`La herramienta '${name}' no existe en este servidor MCP.`);
  }

  const nombreFiltro = args?.nombre ? String(args.nombre).trim() : null;

  try {
    let url = `${API_BASE_URL}/Department`;
    if (nombreFiltro) {
      url = `${API_BASE_URL}/Department/search/${encodeURIComponent(nombreFiltro)}`;
    }

    const response = await fetch(url);
    if (!response.ok) {
      return {
        isError: true,
        content: [{ type: "text", text: `Error en la API de Colombia: Status ${response.status}` }],
      };
    }

    const data = await response.json();
    if (!data || (Array.isArray(data) && data.length === 0)) {
      return {
        content: [{ type: "text", text: `No se encontraron departamentos para: '${nombreFiltro}'.` }],
      };
    }

    const departamentos = Array.isArray(data) ? data : [data];
    const resultadoLimpio = departamentos.map((dept) => ({
      id: dept.id,
      nombre: dept.name,
      capital: dept.cityCapital?.name || "No reportada",
      poblacion: dept.population,
      superficie_km2: dept.surface,
      cantidad_municipios: dept.municipalities,
      prefijo_telefonico: dept.phonePrefix,
    }));

    return {
      content: [{ type: "text", text: JSON.stringify(resultadoLimpio, null, 2) }],
    };
  } catch (error) {
    return {
      isError: true,
      content: [{ type: "text", text: `Excepción en la Tool: ${error.message}` }],
    };
  }
});

// 3. Iniciar servidor Stdio
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("🟢 Servidor MCP de Colombia listo (Stdio)...");
}

main().catch((err) => {
  console.error("🔴 Error al iniciar servidor MCP:", err);
  process.exit(1);
});

10. Instalación y Ejecución

Probar en el Navegador con MCP Inspector (Recomendado para Pruebas)

npm run inspect

Abre la herramienta visual interactiva MCP Inspector en tu navegador para ejecutar obtener_departamentos sin configurar un cliente de IA aún.

11. Integración con Clientes MCP

Configuración en Claude Desktop

Para conectar este servidor MCP con la aplicación de escritorio Claude Desktop, agrega la siguiente ruta a tu archivo %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "colombia-departamentos": {
      "command": "node",
      "args": [
        "C:/Users/Usuario/Desktop/Julio trabajos del sena/Hyalure/index.js"
      ]
    }
  }
}

Al reiniciar Claude Desktop, verás el icono de herramienta 🛠️ activo en la interfaz de chat.

📜 Licencia

Este proyecto es de código abierto bajo la licencia MIT y está diseñado exclusivamente con fines educativos y de investigación académica.