3D Cartoon Generator & File System Tools

Genera imágenes de dibujos animados en 3D usando la IA Gemini de Google y proporciona operaciones seguras del sistema de archivos.

GitHub
3
Prueba este MCPPatrocinado

Documentación

Servidor Combinado MCP: 3D Cartoon Generator & File System Tools

Un servidor de grado profesional que proporciona dos capacidades principales:

  1. Generación de imágenes de caricatura en estilo 3D de alta calidad utilizando la IA Gemini de Google
  2. Operaciones seguras del sistema de archivos para leer, escribir y gestionar archivos

3D Cartoon Generator Demo

🌟 Características

Generación de Imágenes

  • Generación de Caricaturas 3D: Crea imágenes de caricatura en estilo 3D de alta calidad
  • Diseño Amigable para Niños: Se centra en visuales coloridos, divertidos y atractivos
  • Vista Previa Instantánea: Abre automáticamente las imágenes generadas en tu navegador predeterminado
  • Almacenamiento Local: Guarda imágenes y vistas previas en un directorio de salida organizado

Operaciones del Sistema de Archivos

  • Acceso Seguro a Archivos: Validación de rutas y comprobaciones de seguridad
  • Leer/Escribir Archivos: Leer y escribir contenidos de archivos de texto
  • Operaciones de Directorio: Listar, crear y navegar directorios
  • Búsqueda de Archivos: Encontrar archivos que coincidan con patrones

Características del Sistema

  • Configuración Profesional: Manejo robusto de errores y registro controlado
  • Soporte Multiplataforma: Manejo inteligente de rutas de archivos para Windows, macOS y Linux
  • Detección Inteligente del SO: Encuentra automáticamente la mejor ubicación de guardado para cada sistema operativo
  • Controles de Seguridad: Acceso restringido a directorios mediante configuración

🛠️ Pila Tecnológica

  • Framework Principal: Model Context Protocol (MCP) SDK
  • Integración de IA: Google Generative AI (Gemini)
  • Runtime: Node.js v14+
  • Lenguaje: TypeScript
  • Gestor de Paquetes: npm

📋 Requisitos Previos

  • Node.js (v14 o superior)
  • Clave de API de Google Gemini
  • TypeScript

⚙️ Instalación

  1. Clona el repositorio:
git clone https://github.com/falahgs/mcp-3d-style-cartoon-gen-server.git
cd mcp-3d-style-cartoon-gen-server
  1. Instala las dependencias:
npm install
  1. Configura el entorno: Crea un archivo .env en el directorio raíz:
GEMINI_API_KEY=your_api_key_here
ALLOWED_DIRECTORIES=/path/to/allowed/dir1,/path/to/allowed/dir2
  1. Compila el proyecto:
npm run build

🔧 Configurando Claude Desktop con el Servidor MCP

Para integrar este servidor combinado con Claude Desktop:

  1. Localiza el archivo de configuración:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Añade la siguiente configuración:

{
  "mcpServers": {
    "mcp-3d-cartoon-generator": {
      "command": "node",
      "args": [
        "path/to/your/build/index.js"
      ],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here",
        "IS_REMOTE": "true",
        "SAVE_TO_DESKTOP": "true",
        "DETECT_OS_PATHS": "true",
        "ALLOWED_DIRECTORIES": "C:\\Users\\YourUsername\\Desktop,C:\\Users\\YourUsername\\Documents",
        "DEBUG": "false"
      }
    }
  }
}

Script de Ayuda de PowerShell para Windows

Para usuarios de Windows, puedes usar el script fix_claude_config.ps1 incluido para configurar automáticamente Claude Desktop:

  1. Edita el script para actualizar la ruta a tu compilación del servidor y tu clave de API de Gemini
  2. Ejecuta el script en PowerShell:
powershell -ExecutionPolicy Bypass -File .\fix_claude_config.ps1

Esto creará o actualizará el archivo de configuración con la codificación y configuración adecuadas.

🚀 Herramientas Disponibles

1. Herramienta de Generación de Imágenes

{
  "name": "generate_3d_cartoon",
  "description": "Generates a 3D style cartoon image for kids based on the given prompt",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "The prompt describing the 3D cartoon image to generate"
      },
      "fileName": {
        "type": "string",
        "description": "The name of the output file (without extension)"
      }
    },
    "required": ["prompt", "fileName"]
  }
}

2. Herramientas del Sistema de Archivos

Leer Archivo

{
  "name": "read_file",
  "description": "Read the contents of a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to read"
      }
    },
    "required": ["path"]
  }
}

Escribir Archivo

{
  "name": "write_file",
  "description": "Write content to a file",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to write"
      },
      "content": {
        "type": "string",
        "description": "Content to write to the file"
      }
    },
    "required": ["path", "content"]
  }
}

Listar Directorio

{
  "name": "list_directory",
  "description": "List the contents of a directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the directory to list"
      }
    },
    "required": ["path"]
  }
}

Crear Directorio

{
  "name": "create_directory",
  "description": "Create a new directory",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the directory to create"
      }
    },
    "required": ["path"]
  }
}

Buscar Archivos

{
  "name": "search_files",
  "description": "Search for files matching a pattern",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Base directory to search from"
      },
      "pattern": {
        "type": "string",
        "description": "Search pattern (glob format)"
      },
      "excludePatterns": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Patterns to exclude from search (glob format)"
      }
    },
    "required": ["path", "pattern"]
  }
}

📄 Ejemplo de Uso

Ejemplos de Generación de Imágenes

// Generate a 3D cartoon
{
  "name": "generate_3d_cartoon",
  "arguments": {
    "prompt": "A friendly robot playing with a cat",
    "fileName": "robot_cat_play"
  }
}

Ejemplos del Sistema de Archivos

// Read a file
{
  "name": "read_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/example.txt"
  }
}

// Write a file
{
  "name": "write_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-file.txt",
    "content": "This is the content of the file."
  }
}

// List directory contents
{
  "name": "list_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents"
  }
}

// Create a directory
{
  "name": "create_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-folder"
  }
}

// Search for files
{
  "name": "search_files",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents",
    "pattern": "*.txt",
    "excludePatterns": ["temp*", "*.tmp"]
  }
}

🔒 Características de Seguridad

El servidor implementa varias medidas de seguridad:

  1. Validación de Rutas: Todas las rutas de archivos se validan para asegurar que estén dentro de los directorios permitidos.
  2. Directorios Permitidos: Solo se pueden acceder a los directorios establecidos explícitamente en la variable de entorno ALLOWED_DIRECTORIES.
  3. Protección de Enlaces Simbólicos: Evita el acceso a directorios fuera del alcance permitido mediante enlaces simbólicos.
  4. Registro Controlado: Los registros de depuración están deshabilitados por defecto para evitar fugas de información.

⚙️ Opciones de Configuración

Variables de Entorno

VariableDescripciónPredeterminado
GEMINI_API_KEYClave de API de Google Gemini para generación de imágenes(Requerido)
ALLOWED_DIRECTORIESLista separada por comas de rutas de sistema de archivos permitidasDirectorio de inicio del usuario, directorio actual
IS_REMOTEEjecutar en modo remoto sin abrir el navegadorfalse
SAVE_TO_DESKTOPForzar guardado en el directorio de escritoriofalse
DETECT_OS_PATHSHabilitar detección de rutas específicas del SOtrue
DEBUGHabilitar registro de depuración detalladofalse

🛠️ Solución de Problemas

Problemas Comunes:

  1. Errores de Análisis JSON en Claude:

    • Asegúrate de que DEBUG esté establecido en "false" para evitar que los registros interfieran con la comunicación JSON
    • Verifica el formato JSON adecuado en la configuración de Claude

  2. Acceso Denegado a Archivos:

    • Verifica que las rutas a las que intentas acceder estén incluidas en ALLOWED_DIRECTORIES
    • Comprueba los permisos de archivo en los archivos/directorios de destino

  3. Imágenes No Guardadas:

    • Establece SAVE_TO_DESKTOP en "true" para asegurar que las imágenes se guarden en el escritorio
    • Verifica la detección de la ruta del escritorio en los registros del servidor (habilita DEBUG temporalmente)

📄 Licencia

Licencia MIT

🤝 Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Pull Request.