Cookiecutter MCP UV Container

Cookiecutter MCP UV Container

Una plantilla de cookiecutter para crear rápidamente servidores MCP (Protocolo de Contexto de Modelo) con soporte para contenedores de Apple.

¿Por qué contenedores de Apple?

Los contenedores de Apple proporcionan aislamiento a nivel de VM con la simplicidad de Docker:

• Seguridad superior: Cada contenedor se ejecuta en su propia VM ligera
• Nativo de macOS: Integración profunda con los frameworks de macOS
• Bajo demanda: Iniciar/detener servidores según sea necesario (no en ejecución constante)
• Eficiente en recursos: Menos sobrecarga que las VM tradicionales
• Compatible con OCI: Funciona con registros de contenedores existentes

Características

• 🚀 Configuración de servidor FastMCP con herramientas de ejemplo
• 🐳 Dockerfile de múltiples etapas para contenedores optimizados
• 📦 Gestión de paquetes UV
• 🔒 Aislamiento a nivel de VM con usuario de contenedor no root
• 🌐 Múltiples métodos de transporte (stdio, streamable-http, sse)
• 🍎 Optimizado para Apple Silicon
• 📝 Herramientas de calculadora de ejemplo con parámetros tipados

Uso

Requisitos previos

1. Instalar UV (si aún no está instalado):

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

2. Instalar cookiecutter:

   uv tool install cookiecutter
   # or
   pip install cookiecutter
   

3. Instalar Apple/Container:

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

Crear un nuevo proyecto

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

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

Variables de la plantilla

Se te solicitará:

• project_name: Nombre legible del proyecto (ej., "My Calculator MCP")
• project_slug: Nombre del paquete (generado automáticamente a partir de project_name)
• mcp_name: El nombre del servidor MCP (ej., "MyCalculatorMCP")
• description: Descripción del proyecto
• author_name: Tu nombre
• author_email: Tu correo electrónico
• python_version: Versión de Python (predeterminado: 3.13)
• mcp_version: Versión del SDK de MCP (predeterminado: 1.9.4)

Estructura del proyecto

Después de la generación, tu proyecto tendrá:

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 pasos

Después de crear tu proyecto:

1. Navega a tu proyecto:

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

2. Inicia el sistema de contenedores (solo la primera vez):

   container system start
   

3. Construye el contenedor:

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

4. Ejecuta el servidor MCP:

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

5. Personaliza: Edita hello.py para agregar tus propias herramientas MCP

Integración con Claude Desktop

Para Claude Desktop, tienes dos opciones:

Opción 1: Ejecutar localmente sin contenedor (recomendado para desarrollo)

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

Opción 2: Usar transporte HTTP con contenedor

Luego configura Claude Desktop para conectarse mediante STDIO:

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

Opciones de transporte

La plantilla admite múltiples métodos de transporte mediante variables de entorno:

• stdio: Predeterminado
• Más en progreso para el flujo de local a nube

Configura mediante: MCP_TRANSPORT=<transport-type>

Licencia

MIT