Apresentação Detalhada do Projeto MCP Context Forge

Visão Geral do Projeto

MCP Context Forge é um gateway de Protocolo de Contexto de Modelo (MCP) rico em recursos, impulsionado por FastAPI e de código aberto da IBM, que unifica e federa ferramentas, recursos, prompts, servidores e gateways pares, encapsulando qualquer API REST como uma ferramenta ou servidor virtual compatível com MCP. O projeto suporta a exposição de todas as funcionalidades através de protocolos de transporte HTTP/JSON-RPC, WebSocket, Server-Sent Events (SSE) e stdio, e oferece uma rica UI de gerenciamento interativa, empacotada como um contêiner, suportando qualquer banco de dados suportado pelo SQLAlchemy.

Funcionalidades Principais

1. Funcionalidade de Gateway de Protocolo

• Arquitetura de Gateway Verdadeira: Centraliza o registro de ferramentas, recursos e prompts, mantendo o padrão oficial do protocolo MCP 2025-03-26
• Federação Multi-Servidor: Unifica múltiplos servidores MCP em um único endpoint – descobrindo automaticamente nós pares (mDNS ou configuração explícita), verificando a saúde e mesclando suas funcionalidades
• Serviços Virtualizados: Virtualiza serviços não-MCP como "servidores virtuais", permitindo registrar qualquer API REST ou endpoint de função e expô-los sob a semântica MCP

2. Funcionalidade de Adaptação de API

• Adaptador REST para MCP: Adapta qualquer API REST/HTTP para uma ferramenta MCP, suportando validação de entrada JSON-Schema, políticas de repetição/limitação de taxa e chamadas JSON-RPC transparentes
• Conversão de Protocolo: Suporta a conversão entre vários protocolos de transporte (stdio, SSE, Streamable HTTP)

3. Implantação e Gerenciamento

• UI de Gerenciamento Completa: Fornece protocolos de transporte ricos, pipelines de experiência de desenvolvimento pré-construídos e observabilidade de nível de produção
• Funcionalidades de Nível Empresarial: Inclui autenticação e autorização, cache, verificações de saúde, coleta de métricas e outras funcionalidades completas

Arquitetura do Sistema

O projeto adota um design de arquitetura modular:

┌─────────────────┐    ┌──────────────────┐
│  🖥️ Admin UI    │    │  🔐 Autenticação e Autorização │
│  Interface de Gerenciamento │    │  JWT + Basic     │
└─────────────────┘    └──────────────────┘
         │                        │
         └────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │        🚪 Núcleo do Gateway MCP        │
    │     Inicialização do Protocolo Ping Concluída      │
    │        Gerenciador de Federação              │
    │   Protocolos de Transporte HTTP WS SSE Stdio  │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │           Camada de Serviço               │
    │  🧰 Serviço de Ferramentas  📁 Serviço de Recursos      │
    │  📝 Serviço de Prompts  🧩 Serviço de Servidores    │
    └─────────────┬─────────────────┘
                  │
    ┌─────────────▼─────────────────┐
    │          Camada de Persistência              │
    │    💾 Banco de Dados SQLAlchemy       │
    │    ⚡ Cache Redis/Memory       │
    └───────────────────────────────┘

Características Técnicas

Protocolos e Transportes Suportados

• Suporte Completo ao MCP 2025-03-26: initialize, ping, notify, completion, sampling (SSE), e fallback JSON-RPC
• Multi-Protocolo de Transporte: HTTP/JSON-RPC, WebSocket (ping/pong), SSE (unidirecional + canal de retorno), stdio
• Conversão de Protocolo: Suporta a conversão perfeita entre diferentes protocolos de transporte

Federação e Descoberta

• Descoberta Automática: Suporta descoberta de gateway par mDNS ou configuração explícita
• Verificação de Saúde: Verificações de saúde periódicas, suportando failover
• Mesclagem Transparente: Mescla registros remotos de forma transparente em um diretório unificado

Gerenciamento de Recursos

• URIs Modelados: Suporta URIs de recursos parametrizados
• Cache Inteligente: Mecanismo de cache LRU+TTL, detecção de tipo MIME
• Assinatura em Tempo Real: Suporta assinatura em tempo real de alterações de recursos via SSE

Gerenciamento de Prompts

• Templates Jinja2: Suporte a um poderoso motor de templates
• Validação de Schema: Validação forçada de JSON-Schema
• Suporte Multimodal: Suporta blocos de conteúdo multimodais
• Controle de Versão: Gerenciamento de versão e funcionalidade de rollback

Gerenciamento de Ferramentas

• Suporte a Múltiplos Tipos: MCP nativo ou ferramentas baseadas em REST
• Validação de Entrada: Mecanismo completo de validação de entrada
• Lógica de Repetição: Repetição inteligente e limitação de taxa/controle de concorrência

Funcionalidades de Gerenciamento e Monitoramento

Interface de Gerenciamento Web

• Pilha de Tecnologia: HTMX + Alpine.js + Tailwind CSS
• CRUD Completo: Gerenciamento completo de servidores, ferramentas, recursos, prompts, gateways, diretórios raiz e métricas
• Monitoramento em Tempo Real: Monitoramento de status em tempo real e visualização de logs

Autenticação e Autorização

• Múltiplos Métodos de Autenticação: Autenticação Basic, JWT Bearer, Autenticação de Cabeçalho Personalizado
• Controle Granular: Controle de injeção de dependência para cada endpoint
• Criptografia Segura: Armazenamento criptografado AES de cabeçalhos de autenticação de ferramentas

Persistência e Migração

• Suporte a ORM: ORM SQLAlchemy assíncrono (SQLite, PostgreSQL, MySQL, etc.)
• Migração Automática: Migração automática de banco de dados Alembic
• Pool de Conexões: Configuração completa do pool de conexões de banco de dados

Sistema de Eventos e Observabilidade

• Eventos Unificados: Encapsulamento de eventos unificados para fan-out WS/SSE
• Filtragem no Lado do Servidor: Filtragem de eventos no lado do servidor e hooks de retorno
• Logs Estruturados: Registro de logs JSON estruturados
• Verificação de Saúde: Endpoint /health e decorador de métricas de latência
• Métricas Completas: Coleta de métricas para cada manipulador

Experiência de Desenvolvimento

Ferramentas de Desenvolvimento

• Alvos Makefile: Mais de 100 alvos de desenvolvimento pré-definidos
• Qualidade do Código: Hooks pre-commit (ruff, black, mypy, isort)
• Recarregamento em Tempo Real: Servidor de desenvolvimento suporta recarregamento em tempo real
• Cobertura de Teste: Mais de 400 casos de teste
• CI/CD: Insígnias de CI completas e processos automatizados

Opções de Implantação

• Implantação em Contêiner: Suporte a Docker/Podman
• Nativo da Nuvem: Suporte à implantação do IBM Cloud Code Engine
• Múltiplos Ambientes: Configuração de ambientes de desenvolvimento, teste e produção
• SSL/TLS: Suporte HTTPS completo

Opções de Configuração

Configuração Básica

# Configuração básica da aplicação
APP_NAME=MCP Gateway
HOST=0.0.0.0
PORT=4444
DATABASE_URL=sqlite:///./mcp.db
APP_ROOT_PATH=/gateway  # Prefixo de subcaminho opcional

Configuração de Autenticação

# Autenticação Basic (Interface de Gerenciamento e API)
BASIC_AUTH_USER=admin
BASIC_AUTH_PASSWORD=changeme

# Configuração JWT
JWT_SECRET_KEY=my-test-key
JWT_ALGORITHM=HS256
TOKEN_EXPIRY=10080  # Minutos

# Controle de Autenticação
AUTH_REQUIRED=true
AUTH_ENCRYPTION_SECRET=my-test-salt

Configuração de Federação

# Funcionalidade de Federação
FEDERATION_ENABLED=true
FEDERATION_DISCOVERY=false
FEDERATION_PEERS=["http://peer1:4444","http://peer2:4444"]
FEDERATION_TIMEOUT=30
FEDERATION_SYNC_INTERVAL=300

Início Rápido

Executando com 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

Desenvolvimento Local

# Crie um ambiente virtual e instale as dependências
make venv install serve

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

Gerar Token de Autenticação

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

Exemplos de Uso da API

Inicialização do 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 Ferramenta

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

Criar Template de Prompt

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

Implantação no IBM Cloud Code Engine

O projeto oferece suporte completo à implantação no IBM Cloud Code Engine:

Configuração do Ambiente

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 Implantação

make ibmcloud-check-env      # Verifica as variáveis de ambiente
make ibmcloud-cli-install    # Instala o IBM Cloud CLI
make ibmcloud-login          # Faz login no IBM Cloud
make ibmcloud-ce-login       # Seleciona o projeto Code Engine
make ibmcloud-tag            # Marca a imagem do contêiner
make ibmcloud-push           # Envia para o IBM Container Registry
make ibmcloud-deploy         # Implanta no Code Engine

Estrutura do Projeto

mcpgateway/
├── admin.py                    # Rotas FastAPI e controlador da UI de gerenciamento
├── cache/
│   └── resource_cache.py      # Cache LRU+TTL na memória para recursos
├── config.py                  # Carregador de configurações Pydantic
├── db.py                      # Modelos SQLAlchemy ORM e configuração do banco de dados
├── federation/
│   ├── discovery.py           # Descoberta de gateway par
│   ├── forward.py             # Lógica de encaminhamento RPC
│   └── manager.py             # Coordenação de federação e verificação de saúde
├── handlers/
│   └── sampling.py            # Manipulador de requisições de amostragem de fluxo MCP
├── services/
│   ├── completion_service.py  # Lógica de conclusão de parâmetros de prompt e recurso
│   ├── gateway_service.py     # Registro e gerenciamento de gateway par
│   ├── prompt_service.py      # CRUD e renderização de templates de prompt
│   ├── resource_service.py    # Registro, recuperação, assinatura de recursos
│   ├── server_service.py      # Registro de servidor e monitoramento de saúde
│   └── tool_service.py        # Registro, invocação, métricas de ferramentas
├── transports/
│   ├── sse_transport.py       # Transporte de Server-Sent Events
│   ├── stdio_transport.py     # Transporte stdio
│   └── websocket_transport.py # Transporte WebSocket
└── utils/
    ├── create_jwt_token.py    # Ferramenta de geração e verificação de JWT
    └── verify_credentials.py # Dependência de autenticação FastAPI

Desenvolvimento e Contribuição

Configuração do Ambiente de Desenvolvimento

# Instale as dependências de desenvolvimento
make install-dev

# Execute a verificação de código
make lint

# Execute os testes
make test

# Execute os testes de cobertura
make coverage

Ferramentas de Qualidade de Código

O projeto integra várias ferramentas de qualidade de código:

• Formatação: black, isort, autoflake
• Análise Estática: mypy, pylint, pyright, pyre
• Verificação de Segurança: bandit, pip-audit
• Análise de Complexidade: radon, wily
• Verificação de Dependências: fawltydeps, pip-licenses

Resumo

MCP Context Forge é uma solução de gateway de protocolo de contexto de modelo completa e pronta para produção, especialmente adequada para as necessidades de integração e gerenciamento de ferramentas de aplicações LLM de nível empresarial. Ele não apenas implementa a funcionalidade completa do protocolo MCP, mas também fornece ricas funcionalidades de extensão, como descoberta de federação, conversão de protocolo, serviços virtualizados, etc., tornando-o um componente de infraestrutura ideal para construir ecossistemas complexos de aplicações de IA.