Introducción Detallada al Proyecto MCP Context Forge

Resumen del Proyecto

MCP Context Forge es una pasarela de protocolo de contexto de modelo (MCP) impulsada por FastAPI, rica en funciones y de código abierto de IBM, que unifica y federa herramientas, recursos, indicaciones (prompts), servidores y pasarelas de pares, envolviendo cualquier API REST como una herramienta o servidor virtual compatible con MCP. El proyecto admite la exposición de todas las funciones a través de protocolos de transporte HTTP/JSON-RPC, WebSocket, eventos enviados por el servidor (SSE) y stdio, y proporciona una interfaz de usuario de administración interactiva y rica, empaquetada como un contenedor, que admite cualquier base de datos compatible con SQLAlchemy.

Funcionalidades Principales

1. Funcionalidad de Pasarela de Protocolo

• Arquitectura de Pasarela Real: Registro centralizado de herramientas, recursos e indicaciones, manteniendo al mismo tiempo el estándar oficial del protocolo MCP 2025-03-26.
• Federación Multi-Servidor: Unifica múltiples servidores MCP en un único punto final: descubrimiento automático de nodos pares (mDNS o configuración explícita), comprobaciones de estado y fusión de sus funcionalidades.
• Servicios Virtualizados: Virtualiza servicios no MCP como "servidores virtuales", permitiendo registrar cualquier API REST o punto final de función y exponerlos bajo la semántica de MCP.

2. Funcionalidad de Adaptación de API

• Adaptador REST a MCP: Adapta cualquier API REST/HTTP a una herramienta MCP, admitiendo la validación de entrada JSON-Schema, políticas de reintento/limitación de velocidad y llamadas JSON-RPC transparentes.
• Conversión de Protocolo: Admite la conversión entre múltiples protocolos de transporte (stdio, SSE, HTTP Streamable).

3. Despliegue y Administración

• Interfaz de Usuario de Administración Completa: Proporciona protocolos de transporte ricos, canalizaciones de experiencia de desarrollo preconstruidas y observabilidad de nivel de producción.
• Funcionalidades de Nivel Empresarial: Incluye autenticación y autorización, caché, comprobaciones de estado, recopilación de métricas y otras funcionalidades completas.

Arquitectura del Sistema

El proyecto adopta un diseño de arquitectura modular:

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 Autenticación y Autorización      │
│  Interfaz de Administración        │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 Núcleo de la Pasarela MCP        │
    │     Inicialización del Protocolo Ping Completado      │
    │        Administrador de Federación              │
    │   Protocolos de Transporte HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           Capa de Servicio               │
    │  🧰 Servicio de Herramientas  📁 Servicio de Recursos      │
    │  📝 Servicio de Indicaciones  🧩 Servicio de Servidores    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          Capa de Persistencia              │
    │    💾 Base de Datos SQLAlchemy       │
    │    ⚡ Caché Redis/Memoria       │
    └───────────────────────────────┘

Características Técnicas

Protocolos y Transportes Soportados

• Soporte Completo de MCP 2025-03-26: initialize, ping, notify, completion, sampling (SSE), y fallback JSON-RPC.
• Multiples Protocolos de Transporte: HTTP/JSON-RPC, WebSocket (ping/pong), SSE (unidireccional + canal de retorno), stdio.
• Conversión de Protocolo: Soporte para la conversión transparente entre diferentes protocolos de transporte.

Federación y Descubrimiento

• Descubrimiento Automático: Soporte para el descubrimiento de pasarelas pares mediante mDNS o configuración explícita.
• Comprobaciones de Estado: Comprobaciones de estado periódicas, con soporte para la conmutación por error.
• Fusión Transparente: Fusión transparente de registros remotos en un directorio unificado.

Gestión de Recursos

• URI con Plantillas: Soporte para URI de recursos parametrizados.
• Caché Inteligente: Mecanismo de caché LRU+TTL, detección de tipo MIME.
• Suscripciones en Tiempo Real: Soporte para suscripciones en tiempo real a cambios de recursos mediante SSE.

Gestión de Indicaciones (Prompts)

• Plantillas Jinja2: Soporte para un potente motor de plantillas.
• Validación de Esquema: Validación forzada de JSON-Schema.
• Soporte Multimodal: Soporte para bloques de contenido multimodales.
• Control de Versiones: Gestión de versiones y funcionalidad de reversión.

Gestión de Herramientas

• Soporte Multi-Tipo: Herramientas MCP nativas o basadas en REST.
• Validación de Entrada: Mecanismo completo de validación de entrada.
• Lógica de Reintento: Reintento inteligente y limitación de velocidad/control de concurrencia.

Funcionalidades de Administración y Monitorización

Interfaz de Administración Web

• Pila Tecnológica: HTMX + Alpine.js + Tailwind CSS.
• CRUD Completo: Gestión completa de servidores, herramientas, recursos, indicaciones, pasarelas, directorio raíz y métricas.
• Monitorización en Tiempo Real: Monitorización de estado en tiempo real y visualización de registros.

Autenticación y Autorización

• Múltiples Métodos de Autenticación: Autenticación Basic, JWT Bearer, autenticación de encabezado personalizado.
• Control de Grano Fino: Control de inyección de dependencias por punto final.
• Cifrado Seguro: Almacenamiento cifrado AES de los encabezados de autenticación de herramientas.

Persistencia y Migración

• Soporte ORM: ORM SQLAlchemy asíncrono (SQLite, PostgreSQL, MySQL, etc.).
• Migraciones Automáticas: Migraciones automáticas de bases de datos con Alembic.
• Pool de Conexiones: Configuración completa del pool de conexiones de la base de datos.

Sistema de Eventos y Observabilidad

• Eventos Unificados: Envoltura de eventos unificados para WS/SSE fan-out.
• Filtrado del Lado del Servidor: Filtrado de eventos del lado del servidor y ganchos de retorno.
• Registro Estructurado: Registro de registros JSON estructurados.
• Comprobaciones de Estado: Punto final /health y decorador de métricas de latencia.
• Métricas Completas: Recopilación de métricas por controlador.

Experiencia de Desarrollo

Herramientas de Desarrollo

• Objetivos Makefile: Más de 100 objetivos de desarrollo predefinidos.
• Calidad del Código: Hooks pre-commit (ruff, black, mypy, isort).
• Recarga en Tiempo Real: El servidor de desarrollo admite la recarga en tiempo real.
• Cobertura de Pruebas: Más de 400 casos de prueba.
• CI/CD: Insignias de CI completas y procesos automatizados.

Opciones de Despliegue

• Despliegue Contenedorizado: Soporte para Docker/Podman.
• Nativo de la Nube: Soporte para el despliegue en IBM Cloud Code Engine.
• Multi-Entorno: Configuración de entornos de desarrollo, prueba y producción.
• SSL/TLS: Soporte completo de HTTPS.

Opciones de Configuración

Configuración Básica

# Configuración básica de la aplicación
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # Prefijo de subruta opcional

Configuración de Autenticación

# Autenticación Basic (interfaz de administración y API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# Configuración JWT
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # Minutos

# Control de autenticación
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

Configuración de Federación

# Funcionalidad de federación
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

Inicio Rápido

Ejecutar con Docker

docker run -d --name mcpgateway \
  -p 4444:4444 \
  -e HOST=0.0.0.0 \
  -e JWT_SECRET_KEY=my-secret-key \
  -e BASIC_AUTH_USER=admin \
  -e BASIC_AUTH_PASSWORD=changeme \
  -e AUTH_REQUIRED=true \
  -e DATABASE_URL=sqlite:///./mcp.db \
  ghcr.io/ibm/mcp-context-forge:latest

Desarrollo Local

# Crear un entorno virtual e instalar dependencias
make venv install serve

# O instalar manualmente
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
uvicorn mcpgateway.main:app --host 0.0.0.0 --port 4444

Generar Token de Autenticación

export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 10080 --secret my-test-key)

Ejemplos de Uso de la API

Inicialización del Protocolo

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "protocol_version":"2025-03-26",
    "capabilities":{},
    "client_info":{"name":"MyClient","version":"1.0.0"}
  }' \
  http://localhost:4444/protocol/initialize

Registrar Herramienta

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"clock_tool",
    "url":"http://localhost:9000/rpc",
    "description":"Returns current time",
    "input_schema":{
      "type":"object",
      "properties":{"timezone":{"type":"string"}},
      "required":[]
    }
  }' \
  http://localhost:4444/tools

Crear Plantilla de Indicación (Prompt)

curl -X POST -u admin:changeme \
  -H "Content-Type: application/json" \
  -d '{
    "name":"greet",
    "template":"Hello, {{ user }}!",
    "argument_schema":{
      "type":"object",
      "properties":{"user":{"type":"string"}},
      "required":["user"]
    }
  }' \
  http://localhost:4444/prompts

Despliegue en IBM Cloud Code Engine

El proyecto proporciona soporte completo para el despliegue en IBM Cloud Code Engine:

Configuración del Entorno

IBMCLOUD_REGION=us-south
IBMCLOUD_RESOURCE_GROUP=default
IBMCLOUD_PROJECT=my-codeengine-project
IBMCLOUD_CODE_ENGINE_APP=mcpgateway
IBMCLOUD_IMAGE_NAME=us.icr.io/myspace/mcpgateway:latest
IBMCLOUD_API_KEY=your_api_key_here

Comandos de Despliegue

make ibmcloud-check-env      # Comprobar variables de entorno
make ibmcloud-cli-install    # Instalar IBM Cloud CLI
make ibmcloud-login          # Iniciar sesión en IBM Cloud
make ibmcloud-ce-login       # Seleccionar proyecto Code Engine
make ibmcloud-tag            # Etiquetar imagen de contenedor
make ibmcloud-push           # Enviar a IBM Container Registry
make ibmcloud-deploy         # Desplegar en Code Engine

Estructura del Proyecto

mcpgateway/
├── admin.py                    # Rutas FastAPI y controlador de la interfaz de administración
├── cache/
│   └── resource_cache.py      # Caché LRU+TTL en memoria de los recursos
├── config.py                  # Cargador de configuración Pydantic
├── db.py                      # Modelos ORM SQLAlchemy y configuración de la base de datos
├── federation/
│   ├── discovery.py           # Descubrimiento de pasarelas pares
│   ├── forward.py             # Lógica de reenvío RPC
│   └── manager.py             # Coordinación de la federación y comprobaciones de estado
├── handlers/
│   └── sampling.py            # Controlador de solicitudes de muestreo en streaming MCP
├── services/
│   ├── completion_service.py  # Lógica de finalización de parámetros de indicaciones y recursos
│   ├── gateway_service.py     # Registro y gestión de pasarelas pares
│   ├── prompt_service.py      # CRUD y renderizado de plantillas de indicaciones
│   ├── resource_service.py    # Registro, recuperación y suscripción de recursos
│   ├── server_service.py      # Registro de servidores y monitorización de estado
│   └── tool_service.py        # Registro, invocación y métricas de herramientas
├── transports/
│   ├── sse_transport.py       # Transporte de eventos enviados por el servidor
│   ├── stdio_transport.py       # Transporte stdio
│   └── websocket_transport.py # Transporte WebSocket
└── utils/
    ├── create_jwt_token.py    # Herramienta de generación y comprobación de JWT
    └── verify_credentials.py # Dependencia de autenticación FastAPI

Desarrollo y Contribución

Configuración del Entorno de Desarrollo

# Instalar dependencias de desarrollo
make install-dev

# Ejecutar comprobaciones de código
make lint

# Ejecutar pruebas
make test

# Ejecutar pruebas de cobertura
make coverage

Herramientas de Calidad del Código

El proyecto integra varias herramientas de calidad del código:

• Formateo: black, isort, autoflake
• Análisis Estático: mypy, pylint, pyright, pyre
• Escaneo de Seguridad: bandit, pip-audit
• Análisis de Complejidad: radon, wily
• Comprobación de Dependencias: fawltydeps, pip-licenses

Resumen

MCP Context Forge es una solución de pasarela de protocolo de contexto de modelo completa y lista para producción, especialmente adecuada para las necesidades de integración y gestión de herramientas de aplicaciones LLM de nivel empresarial. No solo implementa la funcionalidad completa del protocolo MCP, sino que también proporciona ricas funciones de extensión, como el descubrimiento de federación, la conversión de protocolo, los servicios de virtualización, etc., lo que lo convierte en un componente de infraestructura ideal para construir ecosistemas de aplicaciones de IA complejas.