MCP RAN POC

Un servidor MCP para consultar bases de datos y gestionar clústeres de Kubernetes.

GitHubPrueba este MCPPatrocinado

Documentación

MCP RAN POC

⚠️ ADVERTENCIA: ESTO ES UNA PRUEBA DE CONCEPTO (POC) - NO PARA USO EN PRODUCCIÓN ⚠️

Este repositorio contiene servidores MCP (Model Context Protocol) y un agente ADK para consultas de bases de datos y gestión de clústeres de Kubernetes:

  1. Servidor MCP TALM - Interfaz TALM (Topology Aware Lifecycle Manager) para Red Hat ACM
  2. Servidor MCP PostgreSQL - Interfaz de consulta SQL en lenguaje natural para bases de datos PostgreSQL
  3. Agente ADK - Agente ADK de Google que proporciona una interfaz unificada de lenguaje natural basada en web para ambos servidores MCP

Resumen de Arquitectura

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│   Web Browser       │    │   Claude Desktop    │    │   Other MCP         │
│   + ADK Agent       │    │      Client         │    │    Clients          │
│     :8000           │    │                     │    │                     │
└─────────┬───────────┘    └─────────┬───────────┘    └─────────┬───────────┘
          │                          │                          │
          └──────────────┬───────────┴────────────┬─────────────┘
                         │                        │
                         ▼                        ▼
          ┌─────────────────────────┐   ┌─────────────────────────────────┐
          │   PostgreSQL MCP        │   │      TALM MCP Server            │
          │     Server :3000        │   │        :3001                    │
          └─────────┬───────────────┘   └─────────┬───────────────────────┘
                    │                             │
                    ▼                             ▼
          ┌─────────────────────────┐   ┌─────────────────────────────────┐
          │   PostgreSQL Database   │   │     Kubernetes Clusters         │
          └─────────────────────────┘   └─────────────────────────────────┘

Opciones de Despliegue

Desarrollo Local

# Install dependencies
uv sync

# Run PostgreSQL MCP server (port 3000)
uv run python servers/ocloud-pg.py --transport streamable-http --port 3000

# Run TALM MCP server (port 3001) 
uv run python servers/talm.py --transport streamable-http --port 3001

# Run ADK web interface (connects to both servers)
cd clients && adk web

Despliegue en OpenShift Container Platform (OCP)

Requisitos previos

  • CLI de OpenShift (oc) instalado y con sesión iniciada
  • Docker/Podman para construir imágenes
  • Acceso a un registro de contenedores (quay.io)

Despliegue Rápido

# 1. Setup environment variables
cp .env.example .env
# Edit .env with your PostgreSQL and OpenAI credentials

# 2. Build and push container image
make dev-build-push

# 3. Deploy to OpenShift
make deploy

# 4. Get application URL
oc get route mcp-app-route -n mcp-poc -o jsonpath='{.spec.host}'

Comandos Make Disponibles

  • make build - Construir imagen Docker
  • make push - Enviar imagen al registro
  • make dev-build-push - Construir y enviar con etiqueta de desarrollo
  • make deploy - Desplegar en OpenShift usando kustomize
  • make undeploy - Eliminar despliegue de OpenShift

Configuración de Entorno

Cree el archivo .env con las variables requeridas:

# Multi-Database Configuration
# Alarms Database
ALARMS_DB_HOST=your-postgres-host
ALARMS_DB_PORT=5432
ALARMS_DB_NAME=alarms
ALARMS_DB_USER=alarms
ALARMS_DB_PASSWORD=your-password

# Resources Database
RESOURCES_DB_HOST=your-postgres-host
RESOURCES_DB_PORT=5432
RESOURCES_DB_NAME=resources
RESOURCES_DB_USER=resources
RESOURCES_DB_PASSWORD=your-password

# Clusters Database
CLUSTERS_DB_HOST=your-postgres-host
CLUSTERS_DB_PORT=5432
CLUSTERS_DB_NAME=clusters
CLUSTERS_DB_USER=clusters
CLUSTERS_DB_PASSWORD=your-password

# OpenAI API Configuration
OPENAI_API_KEY=your-openai-api-key-here
OPENAI_MODEL=openai/gpt-4.1

# MCP Server URLs (automatically configured in deployment)
POSTGRES_MCP_URL=http://localhost:3000/mcp
TALM_MCP_URL=http://localhost:3001/mcp

Arquitectura de Despliegue

  • Despliegue de Pod Único: Tres contenedores se ejecutan en el mismo pod:
    • Servidor MCP PostgreSQL (puerto 3000)
    • Servidor MCP TALM (puerto 3001)
    • Interfaz web ADK (puerto 8000)
  • Red Compartida: El cliente ADK se conecta a ambos servidores MCP a través de localhost
  • Acceso Externo: Solo la interfaz web (puerto 8000) se expone mediante OpenShift Route
  • Seguridad: Terminación TLS en el borde, redirección automática a HTTPS
  • RBAC: Utiliza una ServiceAccount dedicada con ClusterRole de administrador para operaciones TALM

Opciones de Cliente Local

Opción 1: Interfaz Web de Google ADK (Recomendada)

cd clients && adk web

Acceda en http://localhost:8000 para una interfaz unificada de lenguaje natural para ambos:

  • Consulta y análisis de bases de datos PostgreSQL
  • Gestión de clústeres de Kubernetes mediante TALM

Opción 2: Cliente de Escritorio Claude

Configure los servidores MCP en la configuración de Claude Desktop:

Configurar el Cliente de Escritorio Claude

Agregue estas configuraciones a su configuración de Claude Desktop:

Configuración del Servidor TALM

{
 "mcpServers": {
  "talm": {
   "command": "uv",
   "args": [
    "run", 
    "python", "servers/talm.py"
   ],
   "cwd": "/path/to/mcp-ran-poc",
   "env": {
      "KUBECONFIG": "/path/to/your/kubeconfig.yaml"
   }
  }
 }
}

Configuración del Servidor PostgreSQL

{
 "mcpServers": {
  "postgres": {
   "command": "uv",
   "args": [
    "run", 
    "python", "servers/ocloud-pg.py"
   ],
   "cwd": "/path/to/mcp-ran-poc",
   "env": {
      "ALARMS_DB_HOST": "your-postgres-host",
      "ALARMS_DB_PORT": "5432",
      "ALARMS_DB_NAME": "alarms",
      "ALARMS_DB_USER": "alarms",
      "ALARMS_DB_PASSWORD": "your-password",
      "RESOURCES_DB_HOST": "your-postgres-host",
      "RESOURCES_DB_PORT": "5432",
      "RESOURCES_DB_NAME": "resources",
      "RESOURCES_DB_USER": "resources",
      "RESOURCES_DB_PASSWORD": "your-password",
      "CLUSTERS_DB_HOST": "your-postgres-host",
      "CLUSTERS_DB_PORT": "5432",
      "CLUSTERS_DB_NAME": "clusters",
      "CLUSTERS_DB_USER": "clusters",
      "CLUSTERS_DB_PASSWORD": "your-password"
   }
  }
 }
}

Ejemplo de Configuración Funcional

Este formato ha sido probado y funciona:

{
 "mcpServers": {
  "talm": {
   "command": "/path/to/uv",
   "args": [
    "run", 
    "--directory", "/path/to/mcp-ran-poc/servers",
    "python", "talm.py"
   ],
   "env": {
      "KUBECONFIG": "/path/to/your/kubeconfig.yaml"
   }
  },
  "postgres": {
   "command": "/path/to/uv",
   "args": [
    "run", 
    "--directory", "/path/to/mcp-ran-poc/servers",
    "python", "ocloud-pg.py"
   ],
   "env": {
    "ALARMS_DB_HOST": "your-postgres-host",
    "ALARMS_DB_PORT": "5432",
    "ALARMS_DB_NAME": "alarms",
    "ALARMS_DB_USER": "alarms",
    "ALARMS_DB_PASSWORD": "your-password",
    "RESOURCES_DB_HOST": "your-postgres-host",
    "RESOURCES_DB_PORT": "5432",
    "RESOURCES_DB_NAME": "resources",
    "RESOURCES_DB_USER": "resources",
    "RESOURCES_DB_PASSWORD": "your-password",
    "CLUSTERS_DB_HOST": "your-postgres-host",
    "CLUSTERS_DB_PORT": "5432",
    "CLUSTERS_DB_NAME": "clusters",
    "CLUSTERS_DB_USER": "clusters",
    "CLUSTERS_DB_PASSWORD": "your-password"
   }
  }
 }
}

Reemplace:

  • /path/to/mcp-ran-poc con la ruta absoluta de este repositorio
  • /path/to/your/kubeconfig.yaml con el archivo kubeconfig de su clúster
  • your-postgres-host con el nombre de host de su servidor PostgreSQL
  • your-password con las contraseñas reales de su base de datos para cada base de datos

Características del Servidor

Servidor TALM

  • Recursos: Acceso a clústeres gestionados, políticas y estado del clúster
  • Herramientas: Remediación de clústeres, comprobaciones de salud y gestión de CGU
  • Indicaciones: Flujos de trabajo guiados para operaciones del ciclo de vida del clúster

Servidor PostgreSQL

  • Herramientas: execute_query(database, query) - Ejecutar consultas SQL de solo lectura de forma segura
  • Seguridad: Solo se permiten consultas SELECT y WITH
  • Respuesta: Formato JSON con resultados de consulta, metadatos y SQL ejecutado

Agente ADK

  • Interfaz Unificada de Lenguaje Natural: Maneja operaciones de base de datos y de clúster
  • Operaciones de Base de Datos: Convierte preguntas en consultas SQL automáticamente
  • Operaciones de Clúster: Gestiona clústeres de Kubernetes mediante comandos TALM
  • Explicación de Consultas: Muestra el razonamiento SQL antes de la ejecución
  • Análisis de Resultados: Proporciona información y análisis de datos de base de datos y clúster
  • Exploración de Esquemas: Ayuda a comprender la estructura de la base de datos y la topología del clúster
  • Interfaz Web: Interacción amigable basada en navegador en http://localhost:8000
  • Integración MCP Dual: Se conecta sin problemas a ambos servidores MCP PostgreSQL y TALM