MCP RGEK - Knowledge Base Server

Servidor MCP (Model Context Protocol) para acceder a la Base de Conocimientos RGEK. Permite a los clientes MCP buscar, consultar y recuperar artículos de conocimiento mediante una API REST.

📋 Tabla de Contenidos

• Características
• Arquitectura
• Instalación
• Configuración
• Uso
• Herramientas Disponibles
• Desarrollo
• Flujos de Trabajo

✨ Características

• 🔍 Búsqueda inteligente con múltiples keywords (o sin keywords para listar todo)
• 📄 Recuperación de artículos específicos por ID
• 🏷️ Filtrado por áreas y tags
• 🔐 Autenticación mediante tokens JWT
• 📦 Paginación de resultados
• 🔄 Eliminación automática de duplicados
• 🚀 Comunicación vía stdio (MCP estándar)
• 🏢 Filtrado automático por áreas mediante variables de entorno (RGEK_API_AREAS)

🏗️ Arquitectura

graph TB
    subgraph "Cliente MCP"
        A[Cliente MCP<br/>Claude, IDEs, etc.]
    end
    
    subgraph "MCP Server"
        B[RGEKServer]
        C[Tool Handlers]
        D[Auth Manager]
    end
    
    subgraph "API RGEK"
        E[Auth Endpoint]
        F[Search Endpoint]
        G[Article Endpoint]
        H[Areas Endpoint]
        I[Tags Endpoint]
    end
    
    A <-->|stdio| B
    B --> C
    C --> D
    D -->|POST| E
    C -->|GET + Bearer Token| F
    C -->|GET + Bearer Token| G
    C -->|GET + Bearer Token| H
    C -->|GET + Bearer Token| I
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style E fill:#ffe1e1
    style F fill:#ffe1e1
    style G fill:#ffe1e1
    style H fill:#ffe1e1
    style I fill:#ffe1e1

Componentes Principales

classDiagram
    class RGEKServer {
        -Server server
        -setupToolHandlers()
        -getToken() Promise~string~
        -makeRequest(endpoint, params)
        -resolveEnvAreaIds(token) Promise~number[]~
        -searchArticles(args)
        -getArticle(args)
        -listCategories()
        +run()
    }
    
    class MCPServer {
        +setRequestHandler()
        +connect()
    }
    
    class StdioTransport {
        +stdio communication
    }
    
    RGEKServer --> MCPServer
    RGEKServer --> StdioTransport

📦 Instalación

Instalación Global

npm install -g mcp-rgek-server

Instalación desde Código Fuente

# Clonar el repositorio
git clone <repository-url>
cd kb-mcp-rgek

# Instalar dependencias
npm install

# Compilar TypeScript
npm run build

Instalación desde Compilado

1. Descomprimir el archivo

   unzip mcp-rgek-compiled.zip
   cd dist

2. Instalar dependencias

   npm install @modelcontextprotocol/sdk axios

3. Ejecutar

   node index.js

⚙️ Configuración

Variables de Entorno

# URL base de la API RGEK
export RGEK_API_URL="http://domain.com/base"

# Usuario para autenticación
export RGEK_API_USER="your-username"

# (Opcional) Áreas por defecto para filtrar búsquedas, separadas por comas
export RGEK_API_AREAS="Franquicia,IAuto"

# (Opcional) Combinar áreas del entorno con las del usuario. Default: true
export RGEK_API_AREAS_MERGE="true"

Comportamiento de RGEK_API_AREAS

Cuando se configura RGEK_API_AREAS, el servidor resuelve automáticamente los nombres de áreas a sus IDs consultando la API en cada búsqueda.

| RGEK_API_AREAS | RGEK_API_AREAS_MERGE | Usuario pasa areas | Resultado | |---|---|---|---| | No definida | - | [10] | Se usa [10] | | No definida | - | ninguna | Sin filtro | | Sí (IDs: [1,2]) | true (default) | [10] | Se combinan: [1,2,10] | | Sí (IDs: [1,2]) | true (default) | ninguna | Se usa [1,2] | | Sí (IDs: [1,2]) | false | [10] | Se ignora la variable, se usa [10] del usuario | | Sí (IDs: [1,2]) | false | ninguna | Se usa [1,2] |

Configuración en Cliente MCP

Claude Desktop

Editar ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "rgek": {
      "command": "mcp-rgek-server",
      "env": {
        "RGEK_API_URL": "http://domain.com/base",
        "RGEK_API_USER": "your-username",
        "RGEK_API_AREAS": "Franquicia,IAuto",
        "RGEK_API_AREAS_MERGE": "true"
      }
    }
  }
}

Otros Clientes MCP

{
  "mcpServers": {
    "rgek": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "RGEK_API_URL": "http://domain.com/base",
        "RGEK_API_USER": "your-username",
        "RGEK_API_AREAS": "Franquicia,IAuto",
        "RGEK_API_AREAS_MERGE": "true"
      }
    }
  }
}

🚀 Uso

Desde Cliente MCP

Una vez configurado, el servidor estará disponible automáticamente en tu cliente MCP. Puedes hacer preguntas como:

• "Busca información sobre configuración de Docker"
• "¿Qué artículos hay sobre seguridad?"
• "Muéstrame el artículo con ID 123"
• "Lista todas las áreas y tags disponibles"

Ejecución Manual

# Desarrollo
npm run dev

# Producción
npm start

🛠️ Herramientas Disponibles

1. search_articles

Busca artículos en la base de conocimientos usando múltiples keywords.

Parámetros:

• keywords (array, opcional): Lista de palabras clave (máximo 5). Si se omite o se pasa vacío, busca todos los artículos
• areas (array, opcional): IDs de áreas para filtrar
• tags (array, opcional): IDs de tags para filtrar
• page (number, opcional): Número de página (default: 1)
• per_page (number, opcional): Artículos por página (default: 30)

Ejemplo con keywords:

{
  "keywords": ["docker", "kubernetes", "deployment"],
  "areas": [1, 3],
  "page": 1,
  "per_page": 10
}

Ejemplo solo por tag (sin keywords):

{
  "keywords": [],
  "tags": [65],
  "per_page": 30
}

Ejemplo solo por área (sin keywords):

{
  "keywords": [],
  "areas": [3],
  "per_page": 30
}

Respuesta:

{
  "keywords_used": ["docker", "kubernetes"],
  "areas_used": [1, 3],
  "tags_used": [],
  "articles": [...],
  "total": 25,
  "total_searches": 50,
  "page": 1,
  "per_page": 10
}

2. get_article

Obtiene el contenido completo de un artículo específico.

Parámetros:

• id (number, requerido): ID del artículo

Ejemplo:

{
  "id": 123
}

3. list_categories

Lista todas las áreas y tags disponibles en la base de conocimientos.

Parámetros: Ninguno

Respuesta:

{
  "areas": [...],
  "tags": [...]
}

💻 Desarrollo

Estructura del Proyecto

kb-mcp-rgek/
├── src/
│   └── index.ts          # Código principal del servidor
├── dist/                 # Código compilado
├── package.json          # Dependencias y scripts
├── tsconfig.json         # Configuración TypeScript
├── rgek-knowledge-agent.json  # Configuración del agente
└── README.md

Scripts Disponibles

# Compilar TypeScript
npm run build

# Ejecutar en producción
npm start

# Ejecutar en desarrollo (con hot reload)
npm run dev

Dependencias

Producción:

• @modelcontextprotocol/sdk: SDK oficial de MCP
• axios: Cliente HTTP para llamadas a la API

Desarrollo:

• typescript: Compilador TypeScript
• tsx: Ejecutor TypeScript para desarrollo
• @types/node: Tipos de Node.js

🔄 Flujos de Trabajo

Flujo de Autenticación

sequenceDiagram
    participant C as Cliente MCP
    participant S as MCP Server
    participant A as API RGEK
    
    C->>S: Solicita herramienta
    S->>A: POST Auth Endpoint
    A->>S: {token: "jwt-token"}
    S->>A: GET Endpoint + Bearer Token
    A->>S: Datos solicitados
    S->>C: Respuesta formateada

Flujo de Búsqueda Múltiple

sequenceDiagram
    participant C as Cliente
    participant S as Server
    participant A as API
    
    C->>S: search_articles(["k1", "k2", "k3"])
    S->>S: getToken()
    
    par Búsqueda Paralela
        S->>A: Search {keyword: "k1"}
        S->>A: Search {keyword: "k2"}
        S->>A: Search {keyword: "k3"}
    end
    
    A-->>S: Resultados k1
    A-->>S: Resultados k2
    A-->>S: Resultados k3
    
    S->>S: Combinar y eliminar duplicados
    S->>S: Aplicar paginación
    S->>C: Artículos únicos

Flujo de Obtención de Artículo

sequenceDiagram
    participant C as Cliente
    participant S as Server
    participant A as API
    
    C->>S: get_article(123)
    S->>S: getToken()
    S->>A: GET Article by ID + Bearer Token
    A->>S: Contenido completo del artículo
    S->>C: Artículo formateado

🔒 Seguridad

• Autenticación mediante JWT tokens
• Tokens renovados en cada petición
• Variables de entorno para credenciales
• Sin almacenamiento de credenciales en código

📄 Licencia

Este proyecto es privado y de uso interno.

🤝 Contribución

Para contribuir al proyecto:

1. Crea una rama para tu feature
2. Realiza tus cambios
3. Asegúrate de que compila: npm run build
4. Envía un pull request

📞 Soporte

Para soporte o preguntas, contacta al equipo de desarrollo.