三维风格卡通生成服务器

Name: 三维风格卡通生成服务器
Author: falahgs

作者：falahgs3 星标更新：2025-04-21

安装使用来源：spider==github.com

项目介绍

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

一款专业级服务器，提供两大主要功能：

使用Google的Gemini AI生成高质量的3D风格卡通图像
安全的文件系统操作，包括读取、写入和管理文件

3D 卡通生成器演示

🌟 功能特性

图像生成

3D 卡通生成：创建高质量的3D风格卡通图像
儿童友好设计：专注于色彩丰富、有趣且吸引人的视觉效果
即时预览：自动生成的图像自动在默认浏览器中打开
本地存储：将图像和预览保存到一个组织良好的输出目录

文件系统操作

安全文件访问：路径验证和安全性检查
读取/写入文件：读取和写入文本文件内容
目录操作：列出、创建和导航目录
文件搜索：查找匹配模式的文件

系统特性

专业配置：强大的错误处理和控制日志记录
跨平台支持：智能文件路径处理，适用于Windows、macOS和Linux
智能操作系统检测：自动找到每个操作系统最佳的保存位置
安全控制：通过配置限制目录访问

🛠️ 技术栈

核心框架：模型上下文协议（MCP）SDK
AI集成：Google生成式AI（Gemini）
运行时：Node.js v14+
语言：TypeScript
包管理器：npm

📋 先决条件

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

⚙️ 安装步骤

克隆仓库：

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

安装依赖项：

npm install

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

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

构建项目：

npm run build

🔧 使用MCP服务器配置Claude桌面

要将此组合服务器与Claude桌面集成：

找到配置文件：
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
添加以下配置：

{
  "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桌面：

编辑脚本以更新到您的服务器构建路径和Gemini API密钥
在PowerShell中运行脚本：

powershell -ExecutionPolicy Bypass -File .\fix_claude_config.ps1

这将创建或更新配置文件，带有正确的编码和设置。

🚀 可用工具

1. 图像生成工具

{
  "name": "generate_3d_cartoon",
  "description": "根据给定提示生成适合儿童的3D风格卡通图像",
  "inputSchema": {
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "描述要生成的3D卡通图像的提示"
      },
      "fileName": {
        "type": "string",
        "description": "输出文件名（不带扩展名）"
      }
    },
    "required": ["prompt", "fileName"]
  }
}

2. 文件系统工具

读取文件

{
  "name": "read_file",
  "description": "读取文件的内容",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "要读取的文件路径"
      }
    },
    "required": ["path"]
  }
}

写入文件

{
  "name": "write_file",
  "description": "将内容写入文件",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "要写入的文件路径"
      },
      "content": {
        "type": "string",
        "description": "要写入文件的内容"
      }
    },
    "required": ["path", "content"]
  }
}

列出目录

{
  "name": "list_directory",
  "description": "列出目录的内容",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "要列出的目录路径"
      }
    },
    "required": ["path"]
  }
}

创建目录

{
  "name": "create_directory",
  "description": "创建新目录",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "要创建的目录路径"
      }
    },
    "required": ["path"]
  }
}

搜索文件

{
  "name": "search_files",
  "description": "搜索匹配模式的文件",
  "inputSchema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "从该基础目录开始搜索"
      },
      "pattern": {
        "type": "string",
        "description": "搜索模式（glob格式）"
      },
      "excludePatterns": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "从搜索中排除的模式（glob格式）"
      }
    },
    "required": ["path", "pattern"]
  }
}

📄 示例用法

图像生成示例

// 生成3D卡通
{
  "name": "generate_3d_cartoon",
  "arguments": {
    "prompt": "一只友好的机器人正在和猫玩耍",
    "fileName": "robot_cat_play"
  }
}

文件系统示例

// 读取文件
{
  "name": "read_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/example.txt"
  }
}

// 写入文件
{
  "name": "write_file",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-file.txt",
    "content": "这是文件的内容。"
  }
}

// 列出目录内容
{
  "name": "list_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents"
  }
}

// 创建目录
{
  "name": "create_directory",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents/new-folder"
  }
}

// 搜索文件
{
  "name": "search_files",
  "arguments": {
    "path": "C:/Users/YourUsername/Documents",
    "pattern": "*.txt",
    "excludePatterns": ["temp*", "*.tmp"]
  }
}

🔒 安全特性

服务器实现了多项安全措施：

路径验证：所有文件路径都经过验证，确保它们位于允许的目录内。
允许的目录：只有在ALLOWED_DIRECTORIES环境变量中明确设置的目录才能被访问。
符号链接保护：防止通过符号链接访问超出允许范围的目录。
受控日志记录：默认情况下禁用调试日志，以防止信息泄露。

⚙️ 配置选项

环境变量

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

🛠️ 故障排查

常见问题：

Claude中的JSON解析错误：
- 确保DEBUG设置为"false"，以防止日志干扰JSON通信
- 检查Claude配置中的正确JSON格式
文件访问被拒绝：
- 确认您尝试访问的路径包含在ALLOWED_DIRECTORIES中
- 检查目标文件/目录的文件权限
图像未保存：
- 将SAVE_TO_DESKTOP设置为"true"，确保图像保存到桌面
- 检查服务器日志中的桌面路径检测（临时启用DEBUG）

📄 许可证

MIT许可证

🤝 贡献

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