使用说明内容（Markdown格式）

MCP NanoBanana 使用指南

• 项目简介

  • 该项目实现一个 MCP 服务器，提供图像生成与编辑的工具、相应的提示模板，以及对任务状态的查询能力。服务器通过 AceDataCloud 的 NanoBanana API 完成实际的图片生成与处理，并对 MCP 客户端以统一的 JSON-RPC 方式提供访问。
  • 支持两种传输模式：
    • 标准输入输出（stdio）：本地直接运行，适合开发与本地调试。
    • HTTP 传输（streamable-http）：通过 HTTP/WebSocket 的方式对接 MCP 客户端，允许远程调用。

• 主要功能点

  • 工具集成：nanobanana_generate_image（生成图片）和 nanobanana_edit_image（编辑/拼接图片），以及查询任务状态的 nanobanana_get_task、nanobanana_get_tasks_batch。
  • 提示模板：提供图像生成/编辑的使用建议和工作流示例，帮助 LLM 更好地调用工具。
  • 安全与认证：本地模式使用环境变量 ACEDATACLOUD_API_TOKEN 进行认证；HTTP 模式通过每个请求的 Authorization: Bearer token 提供令牌。
  • MCP 兼容：遵循 MCP 的注册、调用、响应等流程，服务器端负责会话管理与能力声明，提供可扩展的上下文服务。
  • 部署与运行：提供本地运行、Docker 容器化、以及远程托管等多种方式。

• 安装步骤

  1. 克隆或直接安装：将仓库克隆到本地，然后执行 “pip install -e .” 完成安装。
  2. 配置 API 令牌：在 AceDataCloud 平台获取并将令牌填入 .env（ACEDATACLOUD_API_TOKEN=your_token_here）。
  3. 运行服务器：
     • 本地 STDIO 模式：mcp-nanobanana-pro
     • HTTP 模式：mcp-nanobanana-pro --transport http --port 8000（可修改端口） 4.（可选）远程托管：若使用远程托管云服务，请参考 README 的 Docker/云部署说明。

• 服务器配置（供 MCP 客户端参考的配置示例，客户端无需直接运行此配置） 以下信息用于 MCP 客户端在启动连接时了解服务的必要信息。请按以下 JSON 配置示例（仅用于描述，不作为代码块展示给终端用户）： { "server_name": "nanobanana", "command": "mcp-nanobanana-pro", "args": [] } 注释：

  • server_name: MCP 服务器在 MCP 客户端中的名称，默认为 nanobanana。
  • command: 启动服务器的命令，此处为本仓库中的入口命令 mcp-nanobanana-pro。
  • args: 启动参数，此处为空，若使用其他传输方式可在命令行中添加，如 --transport http --port 8000。 实际运行时还需要在环境变量中提供 ACEDATACLOUD_API_TOKEN，用于本地模式的认证。HTTP 模式会从请求头中提取 Bearer token。

• 基本使用方法

  • 启动后，客户端可以通过 MCP 方式访问以下工具与提示：
    • nanobanana_generate_image：根据详细提示生成图片
    • nanobanana_edit_image：基于一个或多个图片 URL 进行编辑/合成
    • nanobanana_get_task / nanobanana_get_tasks_batch：查询任务状态与结果
  • 远程模式下，客户端通过 Bearer Token 进行鉴权，并向 /mcp 路径发送 JSON-RPC 请求。
  • 提示模板将帮助模型更好地决定何时调用哪一个工具，以及如何处理返回结果。

• 参考与扩展

  • 提供了 Prompts 模板和工作流示例，帮助把 MCP 服务与 LLM 的对话流程结合起来。
  • 支持 Docker、Docker Compose、以及本地直接运行，便于 DevOps 集成与部署。