Scenario.com MCP 服务器

本项目为 Scenario.com API 提供了一个模型上下文协议 (MCP) 服务器。该服务器允许您使用 Scenario.com 平台 (https://app.scenario.com/) 从文本提示生成图像并从图像中移除背景。

仓库结构

仓库的组织结构如下：

• src/: 核心源代码和配置文件

  • server.py: 主要 MCP 服务器实现
  • requirements.txt: 项目依赖
  • setup.py: 安装脚本
  • .gitignore: Git 忽略规则
  • remove_bg_command.txt: 移除背景的命令参考

• examples/: 演示 API 用法的示例脚本

  • client_example.py: 主要示例客户端
  • Get the details of an asset.py: 获取资产详细信息的示例
  • Trigger a new image generation in Txt2Img mode.py: 生成图像的示例
  • Erase background from image.py: 移除背景的示例
  • Get job data by job ID.py: 检查任务状态的示例
  • download_image.py: 下载生成图像的示例

• scripts/: 用于运行服务器和示例的实用程序脚本

  • start_server.bat/start_server.sh: 使用 mcp dev 命令启动 MCP 服务器的脚本
  • run_client_example.bat/run_client_example.sh: 运行示例客户端的脚本，该客户端演示了如何使用 MCP 服务器
  • run_tests.bat/run_tests.sh: 运行测试套件的脚本，该套件验证 MCP 服务器的功能

• tests/: 测试文件

  • test_server.py: MCP 服务器的测试和文档

• assets/: 示例图像和资源

  • warrior_no_background.png: 移除背景的示例图像
  • warrior_with_background.jpg: 示例原始图像

• docs/: 文档

  • README.md: 项目文档
  • DESIGN_PLAN.md: 设计文档

• scenario-ai/: 项目的虚拟环境

设置

1. 克隆此仓库

2. (推荐) 设置一个虚拟环境：

   # 使用 venv
   python -m venv scenario-ai
   .\scenario-ai\Scripts\activate  # Windows
   source scenario-ai/bin/activate  # Linux/macOS
   
   # 或者使用 conda
   conda create -n scenario-ai python=3.8
   conda activate scenario-ai
   

3. 安装所需的依赖项（以下两种方法均可）：

   # 方法 1：使用 requirements.txt
   pip install -r src/requirements.txt
   
   # 方法 2：使用 setup.py（作为包安装）
   pip install -e .
   

4. 在根目录中创建一个 .env 文件，其中包含您的 Scenario.com API 凭据：

   SCENARIO_API_KEY=your_api_key
   SCENARIO_API_SECRET=your_api_secret
   SCENARIO_MODEL_ID=model_KMeeJU9mpcfHKB7a1hv9vyW9  # 更改为首选模型
   

   重要提示: 服务器直接从这个 .env 文件加载环境变量，所以请确保它已正确配置。

5. 安装 MCP SDK 和 python-dotenv：

   pip install mcp
   

6. 将此 MCP 服务器配置添加到您的 Cline/Roo-Cline/Cursor/VS Code 设置：

   "scenario-ai": {
     "command": "python",
     "args": [
       "path/to/your/local/scenario.com-mcp-server/src/server.py"
     ],
     "disabled": false,
     "autoApprove": [],
     "alwaysAllow": []
   }
   

   注意: 环境变量从 .env 文件加载，因此无需在 MCP 服务器配置中指定它们。

运行服务器

要运行服务器：

# 标准方法
python src/server.py

# 推荐：使用 MCP 开发模式（启动检查器）
mcp dev src/server.py

# 或者使用提供的脚本：
# Windows
scripts/start_server.bat

# Linux/macOS
./scripts/start_server.sh

使用 mcp dev 运行时，您将看到如下输出：

Starting MCP inspector...
⚙️ Proxy server listening on port 6277
🔍 MCP Inspector is up and running at http://127.0.0.1:6274 🚀
New SSE connection

可用的 MCP 工具

Scenario.com MCP 服务器提供了以下可与 Roo-Cline 界面一起使用的工具：

工具

1. generate_image: 从文本提示生成图像

   • 参数：
     • prompt (必需): 描述要生成的图像的文本提示
     • model_id (可选): 要使用的模型 ID（默认为环境变量）
     • negative_prompt (可选): 描述要避免在图像中出现的内容的文本
     • num_samples (可选): 要生成的图像数量

2. remove_background: 从图像中移除背景

   • 参数：
     • asset_id (必需): 要处理的图像的资产 ID

资源

1. status://info: 获取有关服务器状态的信息
2. job://{job_id}: 获取有关任务的信息
3. asset://{asset_id}: 获取有关资产的信息

使用示例

有关如何使用服务器的示例，请参见 examples/client_example.py 文件。

要运行示例客户端：

# Windows
scripts/run_client_example.bat

# Linux/macOS
./scripts/run_client_example.sh

脚本

scripts/ 目录包含实用程序脚本，可帮助您运行服务器、示例和测试：

服务器脚本

• start_server.bat (Windows) / start_server.sh (Linux/macOS): 这些脚本使用 mcp dev 命令启动 MCP 服务器，该命令在开发模式下运行服务器。

  用法:

  # Windows
  scripts/start_server.bat
  
  # Linux/macOS
  ./scripts/start_server.sh
  

示例脚本

• run_client_example.bat (Windows) / run_client_example.sh (Linux/macOS): 这些脚本运行示例客户端，该客户端演示了如何使用 MCP 服务器。

  用法:

  # Windows
  scripts/run_client_example.bat
  
  # Linux/macOS
  ./scripts/run_client_example.sh
  

测试脚本

• run_tests.bat (Windows) / run_tests.sh (Linux/macOS): 这些脚本运行测试套件，该套件验证 MCP 服务器的功能。

  用法:

  # Windows
  scripts/run_tests.bat
  
  # Linux/macOS
  ./scripts/run_tests.sh
  

运行测试和查看文档

要运行测试并查看文档：

# Windows
scripts/run_tests.bat

# Linux/macOS
./scripts/run_tests.sh

test_server.py 文件提供了有关如何使用 Scenario.com MCP 服务器的全面文档，包括：

• 服务器设置说明
• 可用工具及其参数
• 可用资源
• 与 Roo-Cline 界面一起使用的示例
• 用于生成图像和移除背景的完整工作流程

运行测试将显示此文档，该文档可作为使用 MCP 服务器的指南。

故障排除

服务器无法启动

如果您在启动服务器时遇到问题，请检查以下各项：

1. 确保已安装 MCP SDK 和 python-dotenv：

   pip install mcp python-dotenv
   

2. 检查您的 Python 环境是否具有所有必需的依赖项：

   pip install -r src/requirements.txt
   

3. 验证您的根目录中的 .env 文件是否已使用您的 Scenario.com API 凭据正确配置：

   SCENARIO_API_KEY=your_api_key
   SCENARIO_API_SECRET=your_api_secret
   SCENARIO_MODEL_ID=your_model_id
   

4. 如果您使用的是虚拟环境，请确保在运行服务器之前已激活它。

API 错误

如果您在使用 API 时遇到错误：

1. 检查您的 API 凭据是否正确。
2. 验证您使用的模型 ID 是否有效。
3. 检查 Scenario.com API 文档中是否有任何服务中断或更改。

许可证

本项目根据 MIT 许可证获得许可 - 有关详细信息，请参见 LICENSE 文件。