MCP RAN POC

Um servidor MCP para consultar bancos de dados e gerenciar clusters Kubernetes.

GitHubExperimente este MCPPatrocinado

Documentação

MCP RAN POC

⚠️ AVISO: ISTO É UMA PROVA DE CONCEITO (POC) - NÃO PARA USO EM PRODUÇÃO ⚠️

Este repositório contém servidores MCP (Model Context Protocol) e um agente ADK para consultas a banco de dados e gerenciamento de clusters Kubernetes:

  1. TALM MCP Server - Interface TALM (Topology Aware Lifecycle Manager) para Red Hat ACM
  2. PostgreSQL MCP Server - Interface de consulta SQL em linguagem natural para bancos de dados PostgreSQL
  3. ADK Agent - Agente Google ADK fornecendo interface unificada de linguagem natural baseada na web para ambos os servidores MCP

Visão Geral da Arquitetura

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

Opções de Implantação

Desenvolvimento 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

Implantação no OpenShift Container Platform (OCP)

Pré-requisitos

  • OpenShift CLI (oc) instalado e conectado
  • Docker/Podman para construir imagens
  • Acesso a um registry de contêineres (quay.io)

Implantação Rápida

# 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 Disponíveis

  • make build - Construir imagem Docker
  • make push - Enviar imagem para o registry
  • make dev-build-push - Construir e enviar com tag de desenvolvimento
  • make deploy - Implantar no OpenShift usando kustomize
  • make undeploy - Remover implantação do OpenShift

Configuração de Ambiente

Crie o arquivo .env com as variáveis necessárias:

# 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

Arquitetura de Implantação

  • Implantação em Pod Único: Três contêineres são executados no mesmo pod:
    • Servidor MCP PostgreSQL (porta 3000)
    • Servidor MCP TALM (porta 3001)
    • Interface web ADK (porta 8000)
  • Rede Compartilhada: O cliente ADK se conecta a ambos os servidores MCP via localhost
  • Acesso Externo: Apenas a interface web (porta 8000) é exposta via OpenShift Route
  • Segurança: Terminação TLS na borda, redirecionamento automático para HTTPS
  • RBAC: Usa ServiceAccount dedicado com ClusterRole admin para operações TALM

Opções de Cliente Local

Opção 1: Interface Web Google ADK (Recomendado)

cd clients && adk web

Acesse em http://localhost:8000 para interface unificada de linguagem natural para ambos:

  • Consultas e análise de banco de dados PostgreSQL
  • Gerenciamento de clusters Kubernetes via TALM

Opção 2: Cliente Claude Desktop

Configure os servidores MCP no config do Claude Desktop:

Configurar o Cliente Claude Desktop

Adicione estas configurações ao seu config do Claude Desktop:

Configuração do 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"
   }
  }
 }
}

Configuração do 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"
   }
  }
 }
}

Exemplo de Configuração Funcional

Este formato foi testado e 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"
   }
  }
 }
}

Substitua:

  • /path/to/mcp-ran-poc pelo caminho absoluto deste repositório
  • /path/to/your/kubeconfig.yaml pelo arquivo kubeconfig do seu cluster
  • your-postgres-host pelo hostname do seu servidor PostgreSQL
  • your-password pelas senhas reais do seu banco de dados para cada banco de dados

Recursos do Servidor

Servidor TALM

  • Recursos: Acesso a clusters gerenciados, políticas e status do cluster
  • Ferramentas: Remediação de cluster, verificações de saúde e gerenciamento de CGU
  • Prompts: Fluxos de trabalho guiados para operações de ciclo de vida do cluster

Servidor PostgreSQL

  • Ferramentas: execute_query(database, query) - Executar consultas SQL somente leitura com segurança
  • Segurança: Apenas consultas SELECT e WITH são permitidas
  • Resposta: Formato JSON com resultados da consulta, metadados e SQL executado

Agente ADK

  • Interface Unificada de Linguagem Natural: Lida com operações de banco de dados e cluster
  • Operações de Banco de Dados: Converte perguntas em consultas SQL automaticamente
  • Operações de Cluster: Gerencia clusters Kubernetes via comandos TALM
  • Explicação de Consultas: Mostra o raciocínio SQL antes da execução
  • Análise de Resultados: Fornece insights e análise de dados de banco de dados e cluster
  • Exploração de Esquema: Ajuda a entender a estrutura do banco de dados e a topologia do cluster
  • Interface Web: Interação amigável baseada em navegador em http://localhost:8000
  • Integração Dupla com MCP: Conecta-se perfeitamente aos servidores MCP PostgreSQL e TALM