seedream-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SeeDream MCP Server - 让 Claude 直接生成图片的 MCP 服务器，基于 BytePlus SeeDream 4.5 模型。

部署地址: https://seedream-mcp-server-production.up.railway.app

可用工具 (6 个):

工具	用途	Claude Code	Claude.ai
seedream_generate	文本生成图片	✅	❌ 超时
seedream_edit	编辑现有图片	✅	❌ 超时
seedream_blend	多图融合 (2-14 张)	✅	❌ 超时
seedream_variations	批量变体 (2-15 张)	✅	❌ 超时
seedream_submit	提交任务，Web App 查看	✅	✅
seedream_status	服务状态检查	✅	✅

Commands

npm run dev      # 开发模式（tsx watch）
npm run build    # TypeScript 编译到 dist/
npm start        # 运行编译后的服务器

# 环境变量（必需）
ARK_API_KEY="your-key"           # SeeDream API 密钥

# 环境变量（传输模式）
TRANSPORT="stdio"                 # stdio（默认）或 http
PORT=3000                         # HTTP 模式端口

# 环境变量（Firebase 同步）
FIREBASE_SERVICE_ACCOUNT='{"type":"service_account",...}'
FIREBASE_USER_ID="your-uid"
FIREBASE_USER_NAME="Your Name"

Architecture

src/
├── index.ts              # 入口点（stdio + http 双模式）
├── services/
│   ├── seedream.ts       # SeeDream API 客户端（流式响应、并行下载）
│   └── firebase.ts       # Firebase Admin SDK（Storage + Firestore）
├── schemas/
│   └── index.ts          # Zod 验证 schema（输入 + 输出）
└── tools/
    ├── generate.ts       # 文本生成图片（Claude Code 专用）
    ├── edit.ts           # 图片编辑
    ├── blend.ts          # 多图融合
    ├── variations.ts     # 批量变体
    ├── submit.ts         # 异步提交（Claude.ai 专用）
    └── status.ts         # 健康检查

两种使用模式

Claude Code (本地):

seedream_generate → 同步返回图片 URL → 自动同步到 Firebase

Claude.ai / MCP Submit:

seedream_submit → 创建任务到 Firestore (status='pending')
                           ↓
        Cloud Function (processGenerationTask) 处理
                           ↓
        生成图片 → 上传 Storage → 更新任务状态
                           ↓
        前端通过 Firestore 实时订阅获取更新
                           ↓
        https://seedream-gallery.firebaseapp.com