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

MCP 组合服务：3D 卡通生成器与文件系统工具

专业级服务，提供两项主要功能：

1. 使用 Google Gemini AI 生成高质量 3D 风格卡通图像
2. 安全地读取、写入和管理文件

🌟 功能特性

图像生成

• 3D 卡通生成：创建高质量 3D 风格卡通图像
• 适合儿童的设计：注重色彩丰富、活泼有趣且引人入胜的视觉效果
• 即时预览：自动在默认浏览器中打开生成的图像
• 本地存储：将图像和预览保存到结构清晰的输出目录中

文件系统操作

• 安全文件访问：路径验证和安全检查
• 读写文件：读取和写入文本文件内容
• 目录操作：列出、创建和浏览目录
• 文件搜索：查找符合模式的文件

系统功能

• 专业配置：完善的错误处理和受控日志记录
• 跨平台支持：针对 Windows、macOS 和 Linux 智能处理文件路径
• 智能操作系统检测：自动为每种操作系统找到最佳保存位置
• 安全控制：通过配置限制目录访问

🛠️ 技术栈

• 核心框架：Model Context Protocol (MCP) SDK
• AI 集成：Google Generative AI (Gemini)
• 运行时：Node.js v14+
• 语言：TypeScript
• 包管理器：npm

📋 前提条件

• Node.js（v14 或更高版本）
• Google Gemini API 密钥
• TypeScript

⚙️ 安装

1. 克隆代码仓库：

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

2. 安装依赖项：

npm install

3. 配置环境： 在根目录中创建一个 .env 文件：

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

4. 构建项目：

npm run build

🔧 配置 Claude Desktop 与 MCP 服务

要将此组合服务集成到 Claude Desktop：

1. 找到配置文件：

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

2. 添加以下配置：

{
  "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 辅助脚本

Windows 用户可以使用随附的 fix_claude_config.ps1 脚本自动配置 Claude Desktop：

1. 编辑脚本，更新服务构建目录的路径和 Gemini API 密钥
2. 在 PowerShell 中运行脚本：

powershell -ExecutionPolicy Bypass -File .\fix_claude_config.ps1

此操作将创建或更新配置文件，并设置正确的编码和配置项。

🚀 可用工具

1. 图像生成工具

{
  "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. 文件系统工具

读取文件

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

写入文件

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

列出目录

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

创建目录

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

搜索文件

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

📄 使用示例

图像生成示例

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

文件系统示例

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

🔒 安全特性

此服务采用了多项安全措施：

1. 路径验证：验证所有文件路径，确保其位于允许访问的目录内。
2. 允许的目录：只能访问在 ALLOWED_DIRECTORIES 环境变量中明确指定的目录。
3. 符号链接保护：防止通过符号链接访问允许范围之外的目录。
4. 受控日志记录：默认禁用调试日志，以防止信息泄露。

⚙️ 配置选项

环境变量

变量	描述	默认值
GEMINI_API_KEY	用于生成图像的 Google Gemini API 密钥	（必填）
ALLOWED_DIRECTORIES	以逗号分隔的允许访问的文件系统路径列表	用户主目录、当前目录
IS_REMOTE	以远程模式运行，不打开浏览器	false
SAVE_TO_DESKTOP	强制保存到桌面目录	false
DETECT_OS_PATHS	启用操作系统专属路径检测	true
DEBUG	启用详细调试日志	false

🛠️ 故障排除

常见问题：

1. Claude 中的 JSON 解析错误：

   • 确保将 DEBUG 设为 "false"，以防止日志干扰 JSON 通信
   • 检查 Claude 配置中的 JSON 格式是否正确

2. 文件访问被拒绝：

   • 确认要访问的路径已包含在 ALLOWED_DIRECTORIES 中
   • 检查目标文件或目录的文件权限

3. 图片未保存：

   • 将 SAVE_TO_DESKTOP 设为 "true"，以确保图片保存到桌面
   • 检查服务日志中的桌面路径检测情况（可临时启用 DEBUG）

📄 许可证

MIT 许可证

🤝 参与贡献

欢迎贡献！请随时提交 Pull Request。