Movies MCP Server

Um servidor abrangente de banco de dados de filmes que suporta pesquisa avançada, operações CRUD e gerenciamento de imagens via um banco de dados PostgreSQL.

GitHub

Experimente este MCPPatrocinado

Documentação

Movies MCP Server

Um servidor Model Context Protocol (MCP) pronto para produção para gerenciamento inteligente de banco de dados de filmes, construído com princípios de Clean Architecture e otimizado para ambientes assistidos por IA.

🎉 Desenvolvido com o Official Golang MCP SDK v1.1.0 Construído com o SDK MCP oficial mantido pela Anthropic e Google, fornecendo segurança de tipos, geração automática de esquemas e confiabilidade pronta para produção. Consulte SDK Migration para detalhes de migração.

✅ Implementação Somente com SDK O servidor personalizado legado foi arquivado. Este projeto agora usa apenas o servidor baseado no SDK oficial em cmd/server-sdk/. Consulte Server Status para detalhes.

O que é o Movies MCP Server?

O Movies MCP Server é um sistema sofisticado de gerenciamento de banco de dados de filmes que se comunica via Model Context Protocol—projetado especificamente para integração com assistentes de IA como o Claude. Diferente de APIs HTTP tradicionais, ele usa JSON-RPC sobre stdin/stdout para fornecer operações de dados de filmes e atores de forma contínua e inteligente.

Perfeito para:

Sistemas de recomendação de filmes com IA
Integrações com Claude Desktop
Análise e exploração inteligente de filmes
Pesquisa de carreira de diretores
Gerenciamento de banco de dados de filmes com assistência de IA

Por que Escolher o Movies MCP Server?

Nativo do Protocolo MCP: Construído especificamente para o Model Context Protocol usando o SDK oficial Golang
Type-Safe e Moderno: Utiliza o SDK oficial para validação em tempo de compilação e geração automática de esquemas
Clean Architecture: Separação exemplar de responsabilidades com design orientado a domínio
Recursos Inteligentes: Recomendações com IA, análise de carreira de diretores e buscas por similaridade
Gerenciamento Abrangente de Atores: Banco de dados completo de atores com associações de filmes e acompanhamento de carreira
Pronto para Produção: Health checks, métricas Prometheus, dashboards Grafana e monitoramento abrangente
Busca Avançada: Busca em texto completo, filtragem por década, faixas de avaliação, correspondência de gêneros e pontuação de similaridade
Suporte a Imagens: Armazene e recupere pôsteres de filmes via recursos MCP com codificação base64
Testes BDD: Cobertura abrangente de testes com cenários de comportamento Cucumber/Godog
Otimizado para Docker: Builds multi-estágio, imagens distroless, execução não-root

Principais Métricas de Desempenho

Throughput: >50 operações/segundo sob carga
Concorrência: Lida com segurança com 50+ requisições concorrentes
Tempo de Resposta: <100ms para operações típicas
Cobertura de Testes: Testes abrangentes de unidade e integração com cenários BDD
Eficiência de Código: 26% menos código com a migração do SDK (eliminadas ~1.200 linhas)

Capacidades MCP

23 Ferramentas Disponíveis

Gerenciamento de Filmes (8 ferramentas)

get_movie - Recuperar filme por ID
add_movie - Criar filme com título, diretor, ano, avaliação, gêneros, pôster
update_movie - Atualizar detalhes de filme existente
delete_movie - Excluir filme por ID
list_top_movies - Obter filmes mais bem avaliados com limite configurável
search_movies - Busca multi-critérios (título, diretor, gênero, faixa de anos, avaliação)
search_by_decade - Encontrar filmes de décadas específicas (anos 1990, 2000, etc.)
search_by_rating_range - Filtrar filmes por limites de avaliação

Gerenciamento de Atores (9 ferramentas)

add_actor - Criar ator com nome, ano de nascimento, biografia
get_actor - Recuperar ator por ID
update_actor - Atualizar informações do ator
delete_actor - Excluir ator
link_actor_to_movie - Associar ator a filme
unlink_actor_from_movie - Remover associação ator-filme
get_movie_cast - Obter todos os atores de um filme
get_actor_movies - Obter todos os filmes de um ator
search_actors - Buscar atores por nome com filtragem por ano de nascimento

Inteligência e Análise (3 ferramentas compostas)

bulk_movie_import - Importar múltiplos filmes com rastreamento de erros
movie_recommendation_engine - Recomendações com IA com pontuação de preferências
director_career_analysis - Trajetória de carreira com análise de fases inicial/média/final

Gerenciamento de Contexto (3 ferramentas)

create_search_context - Criar contexto de busca paginado para grandes conjuntos de resultados
get_context_page - Recuperar página específica do contexto de busca
get_context_info - Obter metadados do contexto e informações de página

5 Prompts Integrados

movie_recommendation - Gerar recomendações personalizadas com base em preferências
movie_analysis - Analisar temas, cinematografia e características
director_filmography - Explorar o corpo de trabalho e a evolução do diretor
genre_exploration - Mergulho profundo na história dos gêneros e filmes influentes
movie_comparison - Comparar dois filmes em múltiplas dimensões

3 Recursos MCP

movies://database/all - Banco de dados completo de filmes em formato JSON
movies://database/stats - Estatísticas e análises do banco de dados
movies://posters/collection - Todos os pôsteres de filmes (codificados em base64)
Dinâmico: movies://posters/{movie-id} - Pôsteres individuais de filmes

Arquitetura e Tecnologia

Implementação de Clean Architecture

Construído com separação estrita de responsabilidades:

internal/
├── domain/          # Pure business logic (entities, value objects)
├── application/     # Use cases and orchestration
├── infrastructure/  # Database and external integrations
├── mcp/            # MCP SDK tools and handlers
└── composition/     # Dependency injection

Benefícios:

Independência de framework
Lógica de negócio testável
Agnóstico de banco de dados (atualmente PostgreSQL)
Fácil de manter e estender

Stack de Tecnologia

Núcleo:

Go 1.23.0+ com toolchain Go 1.24.4
Official Golang MCP SDK v1.1.0 - Implementação de protocolo type-safe
PostgreSQL 17 com indexação avançada
Model Context Protocol (MCP) via JSON-RPC

Bibliotecas Principais:

github.com/modelcontextprotocol/go-sdk - SDK MCP oficial
github.com/lib/pq - Driver PostgreSQL
github.com/cucumber/godog - Testes BDD
github.com/testcontainers/testcontainers-go - Testes de integração
github.com/sirupsen/logrus - Logging estruturado
OpenTelemetry - Rastreamento distribuído

Recursos do Banco de Dados:

Busca em texto completo (índices GIN)
Filtragem de gêneros baseada em arrays
Relacionamentos muitos-para-muitos ator-filme
Gerenciamento automático de timestamps
Armazenamento de imagens (colunas BYTEA)

Início Rápido

Pré-requisitos

Go 1.24.4 ou posterior
Docker e Docker Compose (opcional, para o banco de dados)
PostgreSQL 17 (ou use a configuração baseada em Docker)
Make (opcional, para comandos mais fáceis)

Instalação

Clonar o Repositório:

git clone https://github.com/francknouama/movies-mcp-server.git
cd movies-mcp-server

Configurar o Ambiente:

cp .env.example .env
# Edit .env with your database settings

Iniciar o Banco de Dados (se usar Docker):
```
make docker-up
```

Inicializar o Banco de Dados:

make db-setup      # Create database
make db-migrate    # Run migrations
make db-seed       # Load sample data

Compilar o Servidor SDK (recomendado):

go build -o movies-mcp-server-sdk ./cmd/server-sdk/

Executar o Servidor SDK:

# With environment variables
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=movies_user
export DB_PASSWORD=movies_password
export DB_NAME=movies_mcp
export DB_SSLMODE=disable

./movies-mcp-server-sdk

Ou com flags:

./movies-mcp-server-sdk --version        # Show version
./movies-mcp-server-sdk --help           # Show help
./movies-mcp-server-sdk --skip-migrations # Skip DB migrations

Implantação com Docker

Desenvolvimento (somente bancos de dados):

docker-compose -f docker-compose.dev.yml up

Produção (com monitoramento):

docker-compose -f docker-compose.clean.yml up

Serviços Incluídos:

PostgreSQL 17 (porta 5432)
Movies MCP Server
Grafana (porta 3000)
pgAdmin (porta 5050)
Prometheus (porta 9090)

Integração com Claude Desktop

Configure o Claude Desktop para usar o Movies MCP Server com o servidor baseado em SDK:

Localização do Arquivo de Configuração:

SO	Caminho
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Configuração:

{
  "mcpServers": {
    "movies": {
      "command": "/absolute/path/to/movies-mcp-server-sdk",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_USER": "movies_user",
        "DB_PASSWORD": "movies_password",
        "DB_NAME": "movies_mcp",
        "DB_SSLMODE": "disable"
      }
    }
  }
}

Reinicie o Claude Desktop para ativar a integração.

O que Você Pode Fazer com o Claude

"Encontre filmes de suspense dos anos 1990 com avaliações acima de 8"
"Adicione um novo filme: Inception, dirigido por Christopher Nolan, lançado em 2010"
"Mostre todos os filmes estrelados por Leonardo DiCaprio"
"Analise a trajetória de carreira de Quentin Tarantino"
"Recomende filmes semelhantes a O Poderoso Chefão"
"Importe esta lista de filmes em lote"

Migração do SDK

Migração Concluída! 🎉

Este projeto foi totalmente migrado de uma implementação de protocolo MCP personalizada para o Official Golang MCP SDK v1.1.0.

Principais Melhorias:

✅ 26% menos código - Eliminadas ~1.200 linhas de camada de protocolo personalizada
✅ Handlers type-safe - Validação em tempo de compilação com tipos Go
✅ Geração automática de esquemas - Sem definições manuais de esquemas JSON
✅ Testes simplificados - 37% menos código de teste com melhor clareza
✅ Suporte oficial - Mantido pela Anthropic e Google
✅ Zero mudanças na lógica de negócio - Clean Architecture preservada

O Que Foi Migrado:

23 ferramentas MCP (todas as ferramentas planejadas)
Servidor principal baseado em SDK (cmd/server-sdk/main.go)
Testes de unidade abrangentes
Documentação completa

Documentação:

SDK Migration Comparison - Exemplos de código antes/depois
Testing Comparison - Melhorias de testes
Migration Complete - Resumo completo da migração

✅ Status do Servidor: Implementação Somente com SDK

Servidor Ativo: cmd/server-sdk/ - Implementação baseada no SDK oficial

O Movies MCP Server agora usa somente o Official Golang MCP SDK v1.1.0, fornecendo:

✅ SDK oficial mantido pela Anthropic e Google
✅ 26% menos código com melhor segurança de tipos
✅ Geração automática de esquemas
✅ Melhor manutenibilidade e testes
✅ Pronto para produção e totalmente testado

Servidor Legado Arquivado: O servidor personalizado descontinuado foi arquivado no diretório legacy/. Consulte legacy/README.md para detalhes do arquivamento.

Recursos Avançados

Mecanismo de Recomendação Inteligente

Algoritmo de pontuação multi-fator:

Correspondência de gênero (peso 40%)
Pontuação de avaliação (peso 30%)
Relevância do ano (peso 20%)
Impulso de popularidade (peso 10%)

Retorna recomendações classificadas com pontuações de correspondência e justificativas.

Análise de Carreira de Diretores

A análise automática inclui:

Detecção de fase de carreira (inicial/média/final)
Avaliação média por fase
Rastreamento de especialização em gêneros
Trajetória de carreira (ascendente/descendente/pico/ressurgimento)
Obras notáveis (melhor e pior avaliadas)

Operações de Importação em Lote

Importe múltiplos filmes de uma vez com:

Rastreamento de erros por item
Estatísticas de sucesso/fracasso
Tratamento de sucesso parcial
Relatórios de erro detalhados

Capacidades de Busca Avançada

Busca em texto completo: Título, diretor, descrição usando índices GIN do PostgreSQL
Análise de décadas: Trata inteligentemente formatos "1990s", "90s", "1990"
Pontuação de similaridade: Recomendações baseadas em gênero e avaliação
Filtragem multi-critérios: Combine título, gênero, faixa de anos, faixa de avaliação
Suporte a paginação: Lide com grandes conjuntos de resultados de forma eficiente

Monitoramento e Observabilidade

Métricas Prometheus

Disponíveis na porta 9090 com métricas abrangentes:

Tempos de requisição/resposta
Operações concorrentes
Estatísticas do pool de conexões do banco de dados
Desempenho de consultas
Utilização de memória e CPU

Dashboards Grafana

Acesse o Grafana na porta 3000 para:

Monitoramento de desempenho em tempo real
Visualização da saúde do banco de dados
Regras de alerta personalizadas
Rastreamento de recursos do sistema

Health Checks

Health checks integrados com:

Intervalos configuráveis (padrão: 30s)
Verificação de conectividade do banco de dados
Degradação graciosa
Relatórios de status

Regras de Alerta

Alertas pré-configurados para:

Altas taxas de erro
Desempenho lento de consultas
Problemas de conexão com o banco de dados
Limites de memória/CPU

Configuração: monitoring/alert_rules.yml

Guia do Desenvolvedor

Testes

Executar Todos os Testes:

make test                  # Unit tests
make test-integration      # Integration tests with testcontainers
make test-coverage         # Coverage report
make test-bdd              # BDD scenarios with Godog

Testes de Funcionalidades BDD:

40+ cenários de comportamento em Gherkin
PostgreSQL real via testcontainers
Testes de contrato para o protocolo MCP
Testes de desempenho e carga

Migrações de Banco de Dados

make db-migrate            # Apply migrations
make db-migrate-down       # Rollback last migration
make db-migrate-reset      # Reset database
make db-create-migration   # Create new migration

Qualidade de Código

make fmt                   # Format code
make vet                   # Run go vet
make lint                  # Run golangci-lint

Opções de Build

# Build SDK server (recommended)
go build -o movies-mcp-server-sdk ./cmd/server-sdk/

# Build legacy custom server
make build

# Build all variants
make build-all

# Build Docker image
make docker-build

# Create release
make release               # Create release with goreleaser

Variáveis de Ambiente

Banco de Dados:

DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD, DB_SSLMODE
DATABASE_URL - String de conexão completa (servidor legado)
DB_MAX_CONNECTIONS=100, DB_MAX_IDLE_CONNECTIONS=10

Servidor:

PORT=8080, METRICS_PORT=9090
READ_TIMEOUT=30s, WRITE_TIMEOUT=30s
LOG_LEVEL (debug/info/warn/error)

Segurança:

JWT_SECRET, API_KEY
RATE_LIMIT=1000 (por minuto por IP)
TLS_ENABLED, TLS_CERT_FILE, TLS_KEY_FILE

Monitoramento:

PROMETHEUS_ENABLED=true
HEALTH_CHECK_INTERVAL=30s

Consulte .env.example para opções de configuração completas.

Documentação

Documentação abrangente disponível no diretório /docs: Começando:

Guias:

Guia do Usuário - Passo a passo dos recursos
Exemplos - Exemplos de código

Arquitetura:

Visão Geral da Arquitetura - Detalhes da Clean Architecture
Guia Docker - Configuração e instalação do Docker
Guia de Implantação - Implantação em produção
Suporte a Imagens - Manipulação de imagens via MCP

Migração do SDK:

Comparação de Migração do SDK - Exemplos de código antes/depois
Comparação de Testes - Melhorias nos testes
Migração Concluída - Resumo completo da migração

Referência:

Referência da API - Documentação completa da API
Solução de Problemas - Problemas comuns
Perguntas Frequentes - Perguntas frequentes

Estrutura do Projeto

movies-mcp-server/
├── cmd/
│   └── server-sdk/          # ✅ Official SDK-based server (ACTIVE)
├── internal/
│   ├── domain/              # Business logic (entities, value objects)
│   ├── application/         # Use cases and services
│   ├── infrastructure/      # Database and integrations
│   ├── mcp/                # ✅ MCP SDK tools and handlers (58 tests)
│   └── config/              # Configuration management
├── legacy/                  # 📦 Archived legacy server code
│   ├── cmd/server/          # Deprecated custom server
│   ├── internal/            # Deprecated handlers and schemas
│   └── tests/integration/   # Legacy integration tests
├── migrations/              # Database migrations
├── tests/
│   └── bdd/                # BDD feature files (tests SDK server)
├── docs/                    # Documentation
├── monitoring/              # Prometheus and Grafana configs
└── docker/                  # Docker configurations

Contribuindo

Aceitamos contribuições! Consulte o Guia de Contribuição para:

Código de conduta
Configuração de desenvolvimento
Processo de pull request
Padrões de código
Requisitos de teste

Suporte e Comunidade

Encontrou um bug? Reporte um Problema
Tem perguntas? Consulte as Perguntas Frequentes
Precisa de ajuda? Consulte o Guia de Solução de Problemas
Quer contribuir? Leia o Guia de Desenvolvimento

Licença

Este projeto é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Agradecimentos especiais a:

Model Context Protocol pelo ecossistema MCP
Anthropic pelo desenvolvimento do Claude e do MCP
Google por co-manter o SDK oficial Golang MCP
Comunidade PostgreSQL pelo banco de dados robusto
Comunidade Go pelas excelentes ferramentas e bibliotecas
Todos os contribuidores e usuários deste projeto

O que vem a seguir?

Consulte IMPLEMENTATION_PLAN.md para o roadmap incluindo:

Integração GraphQL
Estratégias avançadas de cache
Algoritmos aprimorados de recomendação
Suporte a múltiplos idiomas
Notificações em tempo real

Construído com princípios de Clean Architecture e o SDK oficial Golang MCP para manutenibilidade, testabilidade e escalabilidade.