Cookiecutter MCP UV Container

Cookiecutter MCP UV Container

Um template cookiecutter para criar rapidamente servidores MCP (Model Context Protocol) com suporte a containers Apple.

Por que Containers Apple?

Containers Apple fornecem isolamento em nível de VM com simplicidade semelhante ao Docker:

• Segurança Superior: Cada container roda em sua própria VM leve
• Nativo para macOS: Integração profunda com frameworks do macOS
• Sob Demanda: Inicie/pare servidores conforme necessário (não ficam rodando constantemente)
• Eficiente em Recursos: Menos overhead que VMs tradicionais
• Compatível com OCI: Funciona com registries de containers existentes

Recursos

• 🚀 Configuração de servidor FastMCP com exemplos de ferramentas
• 🐳 Dockerfile multi-estágio para containers otimizados
• 📦 Gerenciamento de pacotes UV
• 🔒 Isolamento em nível de VM com usuário de container não-root
• 🌐 Múltiplos métodos de transporte (stdio, streamable-http, sse)
• 🍎 Otimizado para Apple Silicon
• 📝 Exemplos de ferramentas de calculadora com parâmetros tipados

Uso

Pré-requisitos

1. Instale o UV (se ainda não estiver instalado):

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Instale o cookiecutter:

   uv tool install cookiecutter
   # or
   pip install cookiecutter
   

3. Instale o Apple/Container:

   Visite https://github.com/apple/container

Criar um novo projeto

# From local directory
cookiecutter /path/to/cookiecutter-mcp-uv-container

# From GitHub 
cookiecutter https://github.com/daviddrummond95/cookiecutter-mcp-uv-container

Variáveis do Template

Você será solicitado a fornecer:

• project_name: Nome legível do projeto (ex.: "My Calculator MCP")
• project_slug: Nome do pacote (gerado automaticamente a partir do project_name)
• mcp_name: O nome do servidor MCP (ex.: "MyCalculatorMCP")
• description: Descrição do projeto
• author_name: Seu nome
• author_email: Seu email
• python_version: Versão do Python (padrão: 3.13)
• mcp_version: Versão do SDK MCP (padrão: 1.9.4)

Estrutura do Projeto

Após a geração, seu projeto terá:

my-mcp-server/
├── Dockerfile          # Multi-stage build for containers
├── pyproject.toml      # UV project configuration
├── hello.py            # MCP server implementation
├── QUICKSTART.md       # Quick start guide
└── .env.example        # Environment configuration

Próximos Passos

Após criar seu projeto:

1. Navegue até seu projeto:

   cd my-mcp-server # or whatever you put as project-slug
   

2. Inicie o Sistema de Containers (apenas na primeira vez):

   container system start
   

3. Construa o Container:

   container build --tag my-mcp . # Replace my-mcp with whatever you want to name the container
   

4. Execute o Servidor MCP:

   # Interactive stdio mode
   container run --interactive my-mcp
   

5. Personalize: Edite hello.py para adicionar suas próprias ferramentas MCP

Integração com Claude Desktop

Para o Claude Desktop, você tem duas opções:

Opção 1: Executar localmente sem container (recomendado para desenvolvimento)

{
  "mcpServers": {
    "My MCP Server (Local)": {
      "command": "uv",
      "args": ["run", "fastmcp", "/path/to/my-mcp-server/hello.py"]
    }
  }
}

Opção 2: Usar transporte HTTP com container

Em seguida, configure o Claude Desktop para conectar via STDIO:

{
  "mcpServers": {
    "My MCP Server (Container)": {
      "command": "container",
   	 "args": ["run",  "--interactive", "my-mcp-container"]
    }
  }
}

Opções de Transporte

O template suporta múltiplos métodos de transporte via variáveis de ambiente:

• stdio: Padrão
• Mais em andamento para fluxo de local -> nuvem

Defina via: MCP_TRANSPORT=<transport-type>

Licença

MIT