MCP Combined Server: 3D Cartoon Generator & File System Tools

MCP Combined Server: 3D Cartoon Generator & File System Tools

A professional-grade server that provides two major capabilities:

1. High-quality 3D-style cartoon image generation using Google's Gemini AI
2. Secure file system operations for reading, writing, and managing files

🌟 Features

Image Generation

• 3D Cartoon Generation: Creates high-quality 3D-style cartoon images
• Child-Friendly Design: Focuses on colorful, playful, and engaging visuals
• Instant Preview: Automatically opens generated images in your default browser
• Local Storage: Saves images and previews in an organized output directory

File System Operations

• Secure File Access: Path validation and security checks
• Read/Write Files: Read and write text file contents
• Directory Operations: List, create, and navigate directories
• File Search: Find files matching patterns

System Features

• Professional Configuration: Robust error handling and controlled logging
• Cross-Platform Support: Intelligent file path handling for Windows, macOS, and Linux
• Smart OS Detection: Automatically finds the best save location for each operating system
• Security Controls: Restricted directory access through configuration

🛠️ Technical Stack

• Core Framework: Model Context Protocol (MCP) SDK
• AI Integration: Google Generative AI (Gemini)
• Runtime: Node.js v14+
• Language: TypeScript
• Package Manager: npm

📋 Prerequisites

• Node.js (v14 or higher)
• Google Gemini API key
• TypeScript

⚙️ Installation

1. Clone the repository:

git clone https://github.com/falahgs/mcp-3d-style-cartoon-gen-server.git
cd mcp-3d-style-cartoon-gen-server

2. Install dependencies:

npm install

3. Configure environment: Create a .env file in the root directory:

GEMINI_API_KEY=your_api_key_here
ALLOWED_DIRECTORIES=/path/to/allowed/dir1,/path/to/allowed/dir2

4. Build the project:

npm run build

🔧 Configuring Claude Desktop with MCP Server

To integrate this combined server with Claude Desktop:

1. Locate the Configuration File:

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

2. Add the following configuration:

{
  "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"
      }
    }
  }
}

Windows PowerShell Helper Script

For Windows users, you can use the included fix_claude_config.ps1 script to automatically configure Claude Desktop:

1. Edit the script to update the path to your server build and your Gemini API key
2. Run the script in PowerShell:

powershell -ExecutionPolicy Bypass -File .\fix_claude_config.ps1

This will create or update the configuration file with proper encoding and settings.

🚀 Available Tools

1. Image Generation Tool

{
  "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. File System Tools

Read File

{
  "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"]
  }
}

Write File

{
  "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"]
  }
}

List Directory

{
  "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"]
  }
}

Create Directory

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

Search Files

{
  "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"]
  }
}

📄 Example Usage

Image Generation Examples

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

File System Examples

// 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"]
  }
}

🔒 Security Features

The server implements several security measures:

1. Path Validation: All file paths are validated to ensure they are within allowed directories.
2. Allowed Directories: Only directories explicitly set in the ALLOWED_DIRECTORIES environment variable can be accessed.
3. Symlink Protection: Prevents access to directories outside the allowed scope via symlinks.
4. Controlled Logging: Debug logs are disabled by default to prevent information leakage.

⚙️ Configuration Options

Environment Variables

Variable	Description	Default
GEMINI_API_KEY	Google Gemini API key for image generation	(Required)
ALLOWED_DIRECTORIES	Comma-separated list of allowed file system paths	User's home dir, current dir
IS_REMOTE	Run in remote mode without browser opening	false
SAVE_TO_DESKTOP	Force saving to desktop directory	false
DETECT_OS_PATHS	Enable OS-specific path detection	true
DEBUG	Enable verbose debug logging	false

🛠️ Troubleshooting

Common Issues:

1. JSON Parsing Errors in Claude:

   • Ensure DEBUG is set to "false" to prevent logs from interfering with JSON communication
   • Check for proper JSON formatting in the Claude configuration

2. File Access Denied:

   • Verify that the paths you're trying to access are included in ALLOWED_DIRECTORIES
   • Check file permissions on the target files/directories

3. Images Not Saving:

   • Set SAVE_TO_DESKTOP to "true" to ensure images save to the desktop
   • Check desktop path detection in the server logs (enable DEBUG temporarily)

📄 License

MIT License

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.