MCP Server Template

Complete template for creating MCP (Model Control Protocol) servers with data loader architecture and PostgreSQL support.

Architecture

This template follows a modular architecture that allows creating MCP servers for different domains with ease. The architecture is composed of the following layers:

1. Configuration Layer

• Centralized Configuration: All server configurations are maintained in a single location (CONFIG)
• Environment Variables: Support for different environments (development, production)
• Database Connection: Configuration for PostgreSQL with seed data initialization

2. Data Layer (SQLAlchemy Models)

• Contexts: Models to represent different data contexts
• Jobs: Models for data loader job management
• Seed Data: Initial data for database initialization
• ORM Connection: Integration with PostgreSQL using SQLAlchemy

3. Service Layer (MCP Server)

• MCP Server: Main server instance
• Decorators: Tools for defining tools, resources and prompts
• Connection Management: Connection verification (e.g., IB - Interactive Brokers)
• Lifecycle Management: Server startup and shutdown

4. Business Layer (Data Loader)

• Job Manager: Complete system for creating, executing and monitoring jobs
• Job Types: Support for different job types (ingestion, processing, etc.)
• Job Status: Complete job status management
• Parameters: Support for custom parameters in jobs

5. Interface Layer (Tools)

• Main Tools: Basic context and management functionalities
• Data Loader Tools: Specific operations for data loader jobs
• Specific Tools: Domain-specific functionalities
• Resources: Direct access to server information
• Prompts: Usage guides and documentation

Componentes Principais

1. Configuração (CONFIG)

CONFIG = {
    "host": "127.0.0.1",
    "port": 8080,
    "transport": "tcp",
    "ib_enabled": False,
    "database_url": "postgresql://user:password@localhost/mcp_db",
    "data_loader_enabled": True,
    "max_concurrent_jobs": 5
}

2. Modelos SQLAlchemy

• Context: Representa diferentes contextos de dados
• Job: Representa jobs de data loader com status e parâmetros

3. Gerenciador de Jobs (JobManager)

• create_job(): Cria novos jobs
• get_job(): Obtém job específico
• update_job_status(): Atualiza status de jobs
• list_jobs(): Lista todos os jobs
• get_jobs_by_type(): Filtra jobs por tipo

4. Ferramentas Principais

• todo_method(): Método placeholder para implementações específicas
• get_context_info(): Obter informações de contexto
• search_context(): Buscar contextos
• list_contexts(): Listar todos os contextos
• trigger_job(): Executar jobs de data loader
• get_job_status(): Obter status de job
• cancel_job(): Cancelar job

5. Recursos

• server_status(): Status do servidor
• server_health(): Saúde do servidor
• server_capabilities(): Capacidades do servidor

6. Prompts

• usage_guide(): Guia de uso do servidor
• data_loader_guide(): Guia de uso do data loader

Como Usar

1. Configuração: Atualize a string de conexão do PostgreSQL em CONFIG["database_url"]
2. Personalização: Modifique o método todo_method para implementar funcionalidades específicas
3. Extensão: Adicione novos modelos e ferramentas conforme necessário
4. Execução: python final_mcp_template.py

Estrutura de Diretórios

.
├── final_mcp_template.py     # Template principal
├── README.md                 # Documentação
└── (outros arquivos de template)

Funcionalidades

• Data Loader Completo: Sistema completo de gerenciamento de jobs
• PostgreSQL: Suporte a banco de dados relacional
• Seed Data: Dados iniciais para inicialização
• MCP Compatível: Totalmente compatível com protocolo MCP
• Extensível: Fácil de estender para novos domínios
• Seguro: Sistema de gerenciamento de conexões e erros

Exemplo de Uso

# Executar o servidor
python final_mcp_template.py

# O servidor estará disponível em:
# http://127.0.0.1:8080

Personalização

Para criar um novo MCP server baseado neste template:

1. Atualize as configurações no arquivo CONFIG
2. Modifique o método todo_method para implementar lógica específica
3. Adicione novos modelos no sistema de dados conforme necessário
4. Crie novas ferramentas usando o decorator @server.tool
5. Adicione novos recursos usando o decorator @server.resource
6. Crie novos prompts usando o decorator @server.prompt

Requisitos

• Python 3.7+
• mcp
• SQLAlchemy
• PostgreSQL
• Docker e Docker Compose (opcional, para execução em container)

Execução com Docker

Para executar o servidor MCP em um container Docker:

1. Construir a imagem:

docker-compose build

2. Iniciar os serviços:

docker-compose up -d

3. Verificar o status:

docker-compose ps

4. Acessar o servidor: O servidor estará disponível em: http://localhost:8080

5. Para parar os serviços:

docker-compose down

Estrutura de Diretórios

.
├── final_mcp_template.py     # Template principal
├── README.md                 # Documentação
├── Dockerfile                # Dockerfile para container
├── docker-compose.yml        # Compose para múltiplos containers
├── requirements.txt          # Dependências Python
├── .env                      # Variáveis de ambiente
└── logs/                     # Diretório para logs