MCP-ALBERTO

MCP-ALBERTO: Servidor de Herramientas Fundamentales para IA

Este proyecto implementa un servidor MCP (Model Context Protocol) diseñado para extender las capacidades de un asistente de IA. Proporciona un conjunto de herramientas fundamentales y atómicas que, si bien pueden tener una utilidad limitada de forma aislada, están diseñadas para ser combinadas y orquestadas por un modelo de IA para ejecutar flujos de trabajo complejos e interactuar con servicios externos específicos (actualmente, un sistema denominado "ALBERTO" relacionado con TotalCheck).

El objetivo no es ofrecer herramientas complejas pre-empaquetadas, sino componentes básicos (primitivas) que la IA puede utilizar dinámicamente para resolver tareas como obtener credenciales, autenticarse y potencialmente interactuar con otros endpoints del servicio subyacente.

Configuración de Ejecución (Ejemplo para integración)

La siguiente configuración (ejemplo) muestra cómo podría integrarse este MCP con una herramienta que lo utilice:

Estructura del Proyecto

• main.ts: Punto de entrada de la aplicación. Inicializa el servidor MCP, configura el transporte (actualmente StdioServerTransport) y registra las herramientas disponibles.
• userservice/:
  • userservice-api-rest.ts: Contiene la lógica para interactuar con la API REST del servicio de usuarios (ej. obtener ticket de autenticación).
  • userservice-tool.ts: Define y registra las herramientas MCP relacionadas con el servicio de usuarios (ej. get_ticket).
• README.md: Este archivo.
• .gitignore: Especifica los archivos y directorios ignorados por Git.
• package.json / package-lock.json: Gestión de dependencias del proyecto Node.js.
• tsconfig.json: Configuración del compilador TypeScript.

Herramientas MCP Disponibles

Este servidor expone las siguientes herramientas. Es crucial entender que estas herramientas son bloques de construcción de bajo nivel. Su verdadero potencial se desbloquea cuando una IA las utiliza en secuencia o combinación para lograr un objetivo mayor.

• get_node_info
  • Descripción: Obtiene información detallada y completa de un nodo específico del sistema.
  • Implementación: nodeservice/nodeservice-tool.ts
  • Parámetros: unique_id (string, requerido), alf_ticket (string).
  • Uso: Ideal cuando se conoce el unique_id exacto del nodo y se necesitan todos sus detalles.
• search_by_type
  • Descripción: Realiza búsquedas flexibles por Tenant y Tipo en ElasticSearch, permitiendo encontrar nodos basados en diversos criterios.
  • Implementación: searchservice/by_type/tool.ts
  • Endpoint API: /searchservice/tenant/{tenant}/type/{type}/...
  • Parámetros:
    • tenant_name (string, requerido): El tenant donde buscar.
    • type_name (string, requerido): El índice/tipo específico a consultar (ej. expediente_inscripcion_mt).
    • query_body (string, requerido): Query ElasticSearch en formato JSON string.
    • alf_ticket (string): Ticket de autenticación.
    • from_index (number, opcional): Paginación.
    • page_size (number, opcional): Paginación.
    • sort (string, opcional): Ordenación.
  • Uso: Para búsquedas dirigidas a un índice específico (expedientes, usuarios, etc.).
• search_workflow
  • Descripción: Realiza búsquedas flexibles en el alias taskmanager de Workflow en ElasticSearch.
  • Implementación: searchservice/workflow/tool.ts
  • Endpoint API: /searchservice/workflow/...
  • Parámetros:
    • query_body (string, requerido): Query ElasticSearch en formato JSON string.
    • alf_ticket (string): Ticket de autenticación.
    • from_index (number, opcional): Paginación.
    • page_size (number, opcional): Paginación.
  • Uso: Para encontrar tareas o información de workflow, útil como paso intermedio para descubrir unique_id o type_name de un caso si solo se tienen datos parciales (patente, operación).
• get_ticket
  • Descripción: Obtiene un ticket de autenticación desde el servicio de login externo.
  • Implementación: userservice/userservice-tool.ts
  • Parámetros:
    • usuario (string): Nombre de usuario para la autenticación.
    • password (string): Contraseña del usuario.
  • Retorna: El ticket de autenticación como texto.
• get_config_credentials
  • Descripción: Obtiene una lista predefinida de credenciales de configuración (usuario, clave, descripción).
  • Implementación: configuraciones/configuraciones-tool.ts
  • Parámetros: Ninguno.
  • Retorna: Un array de objetos JSON, cada uno con username, clave y description.
  • Nota: Provee a la IA de las identidades disponibles para interactuar con el sistema.

Flujos de Trabajo Comunes

• Obtener Ticket con Credenciales de Configuración:
  1. Llamar a get_config_credentials para obtener el usuario y la contraseña preconfigurados.
  2. Extraer el usuario y password del resultado JSON.
  3. Llamar a get_ticket pasando el usuario y password obtenidos en el paso anterior.

Orquestación por IA (Ejemplo Conceptual)

Un asistente de IA podría recibir una solicitud como "Obtén un ticket para el usuario administrador". La IA, utilizando las herramientas disponibles, ejecutaría los siguientes pasos:

1. Llamar a get_config_credentials: Para obtener la lista de usuarios y sus descripciones.
2. Identificar Usuario: Procesar la respuesta para encontrar el username correspondiente a la descripción "Usuario de Administrador".
3. Llamar a get_ticket: Utilizar el username identificado y su clave (implícita o extraída) para solicitar el ticket de autenticación.
4. Presentar Resultado: Devolver el ticket obtenido al usuario.

Este ejemplo ilustra cómo herramientas simples se combinan bajo la dirección de la IA para satisfacer una necesidad compleja.

Interacción entre Servicios y Elasticsearch

Es fundamental entender cómo search_by_type, search_workflow y get_node_info interactúan y cómo se relacionan con la estructura de datos en Elasticsearch:

1. Índices Primarios: Cada tipo principal de entidad (ej. expediente_inscripcion_mt, expediente_operacion_leasing, user, tenant) reside en su propio índice ElasticSearch. search_by_type puede consultar estos índices directamente especificando el type_name apropiado.
2. Índices de Workflow (taskmanager_*): Cuando un nodo entra en un flujo de trabajo, se generan entradas en índices específicos del workflow (ej. taskmanager_expediente_inscripcion_mt).
3. Alias taskmanager: Existe un alias llamado taskmanager que agrupa todos los índices de workflow. Usar search_workflow o search_by_type permite buscar en todas las tareas activas.
4. Flujo Típico:
   • Si se conoce el tipo primario, la IA usará search_by_type directamente.
   • Si se busca información general o se desconoce el tipo exacto, la IA podría usar search_workflow (consultando el alias taskmanager) como paso de descubrimiento.
   • El resultado de search_workflow o search_by_type puede contener la información necesaria o el unique_id del nodo principal.
   • Si se obtiene un unique_id y se necesitan todos los detalles, la IA puede usar get_node_info.

Guía para la IA: Condiciones Mínimas de Búsqueda

Para asegurar resultados relevantes y eficientes, al construir el query_body para search_by_type o search_workflow, la IA debe aplicar las siguientes condiciones mínimas por defecto, a menos que la solicitud del usuario indique explícitamente lo contrario:

• Al consultar Índices Primarios (ej. expediente_*, user, tenant):
  • Excluir registros borrados. Incluir en la query:
    { "query": { "bool": { "must_not": [{ "term": { "deleted": true } }] } } }
    (Combinar con otras cláusulas must, filter según sea necesario dentro del bool).
• Al consultar el Alias taskmanager:
  • Incluir solo tareas activas y excluir registros borrados.
  • Incluir en la query:
    { "query": { "bool": { "must": [{ "term": { "status": "active" } }], "must_not": [{ "term": { "deleted": true } }] } } }
    (Ajustar el campo status y su valor active si los nombres reales difieren; combinar con otras cláusulas must, filter).

Detalles Técnicos Clave

1- Configuración adicional de package.json - "type": "module": Habilita el uso de módulos ES6 (import/export).

2- Paquetes importantes (dependencies) - @modelcontextprotocol/sdk: SDK para crear el servidor MCP. - zod: Para validación de esquemas (usado en la definición de herramientas). - axios: Cliente HTTP para realizar llamadas a la API REST. - tsx: Para ejecutar directamente archivos TypeScript.

3- Archivos principales del MCP - main.ts: Orquestador principal. - userservice/userservice-api-rest.ts: Lógica de llamadas a la API. - userservice/userservice-tool.ts: Definición de herramientas MCP.

Comandos para Desarrollo Local

1. Instalar dependencias:
   npm install
2. Ejecutar el servidor MCP:
   npx tsx main.ts
   El servidor se iniciará y esperará comunicación a través de stdio.