tf-tools-mcp 0.1.7

Image generation and understanding tools using OpenRouter and Zhipu AI

TF Tools MCP

基于 OpenRouter 和智谱 AI 的 MCP (Model Context Protocol) 图像生成与理解工具集。

功能特性

• 文本生成图像 (Text-to-Image): 使用多种模型通过 OpenRouter Images API 生成图像

  • 支持模型：Gemini 3.1 Flash Image、Gemini 3 Pro Image、GPT Image 2/Mini、Seedream 4.5、FLUX.2 Max/Pro
  • 可选的 AI 提示词增强功能（使用 GLM-4.6V）
  • 多种质量级别和布局选项

• 图像生成图像 (Image-to-Image): 使用文本引导转换参考图像

  • 支持本地文件和 URL
  • 针对不同转换模式的智能提示词增强

• 图像理解 (Image Understanding): 使用 GLM-5V/4.6V 分析图像，标准 OCR 自动路由至 GLM-OCR

  • 单图和批量图像分析
  • 多种分析模板：描述、OCR、物体检测、图表分析
  • 详细的 token 使用统计

• 文件预览 (File Preview): 智能文件预览和摘要生成

  • 支持 PDF、Word、Excel、PPT、图像等多种格式
  • 自动提取元数据
  • AI 驱动的内容摘要

安装

使用 uv（推荐）

# 克隆仓库
git clone https://github.com/A2C-SMCP/tf_tools_mcp.git
cd tf_tools_mcp

# 安装依赖
uv sync

# 开发模式安装
uv pip install -e .

从 PyPI 安装

pip install tf-tools-mcp

配置

1. 环境变量配置

创建 .env 文件并添加 API 密钥：

# 必需：图像生成
OPENROUTER_API_KEY=你的_openrouter_api_key

# 必需：图像理解和提示词增强
ZHIPUAI_API_KEY=你的_智谱ai_api_key

# 可选设置
IMAGE_STORAGE_DIR=./generated_images
ENABLE_PROMPT_ENHANCEMENT=true

2. 获取 API 密钥

• OpenRouter API Key: 访问 https://openrouter.ai/ 注册，在 https://openrouter.ai/keys 获取密钥
• 智谱 AI API Key: 访问 https://open.bigmodel.cn/ 注册，在 https://open.bigmodel.cn/usercenter/apikeys 获取密钥

MCP 客户端配置

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

方法 1：使用 uvx（推荐）

无需手动安装，自动从 PyPI 运行：

{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "uvx",
      "args": ["tf-tools-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "你的_api_key",
        "ZHIPUAI_API_KEY": "你的_api_key"
      }
    }
  }
}

方法 2：使用已安装的包

如果已通过 pip install tf-tools-mcp 安装：

{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "tf-tools-mcp",
      "env": {
        "OPENROUTER_API_KEY": "你的_api_key",
        "ZHIPUAI_API_KEY": "你的_api_key"
      }
    }
  }
}

配置完成后重启 Claude Desktop。

Claude Code (CLI)

方法 1：使用 uvx

claude mcp install uvx tf-tools-mcp \
  -e OPENROUTER_API_KEY=你的_api_key \
  -e ZHIPUAI_API_KEY=你的_api_key

方法 2：手动配置

编辑 ~/.config/claude-code/mcp_config.json：

{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "uvx",
      "args": ["tf-tools-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "你的_api_key",
        "ZHIPUAI_API_KEY": "你的_api_key"
      }
    }
  }
}

其他 MCP 客户端

参考客户端文档，使用以下命令配置：

uvx tf-tools-mcp

确保设置正确的环境变量（OPENROUTER_API_KEY 和 ZHIPUAI_API_KEY）。

可用工具

text_to_image

从文本提示词生成图像。

参数：

• prompt (字符串，必需)：图像生成的文本提示词
• model (字符串，可选)：OpenRouter 模型 ID，默认 google/gemini-3.1-flash-image
  • google/gemini-3.1-flash-image
  • google/gemini-3-pro-image
  • openai/gpt-image-2
  • openai/gpt-image-1-mini
  • bytedance-seed/seedream-4.5
  • black-forest-labs/flux.2-max
  • black-forest-labs/flux.2-pro
• mode (字符串，可选)：提示词增强模式
  • technical_architecture: 技术架构图
  • design_mockup: UI/UX 设计稿
  • promotional_material: 营销宣传材料
  • office_chart: 商业图表
  • custom: 不增强（默认）
• quality (字符串，可选)：图像质量 (low, medium, high) - 默认: medium
• layout (字符串，可选)：图像布局 (square, landscape, portrait) - 默认: square
• save_to_local (布尔值，可选)：是否将图片保存到本地 - 默认: false
• save_dir (字符串，可选)：本地保存目录 - 默认: /tmp/generate_img/

工具通过 OpenRouter 的 /api/v1/images 接口调用模型。quality 和 layout 会按照各模型实际支持的参数自动映射，不支持的参数不会发送给上游。

示例：

使用 Gemini 3.1 Flash Image 模型生成一张夕阳下山脉的图像，
要求色彩鲜艳，高质量，横向布局。

image_to_image

使用参考图像和文本引导生成图像。

参数：

• prompt (字符串，必需)：图像生成的文本提示词
• reference_images (字符串数组，必需)：1-8 张参考图像，可使用 URL，或最大 20MB 的本地 JPEG/PNG/WebP
• model (字符串，可选)：OpenRouter 模型 ID（同 text_to_image，默认 Gemini 3.1 Flash Image）
• mode (字符串，可选)：提示词增强模式
  • content_adjustment: 调整内容但保持风格
  • element_replace: 替换特定元素
  • style_transfer: 艺术风格迁移
  • text_modification: 修改图像中的文字
  • custom: 不增强（默认）
• quality, layout, save_to_local, save_dir: 同 text_to_image

示例：

使用 FLUX.2 Max 模型将参考图像（位于 /path/to/image.jpg）
转换为赛博朋克风格。

image_understanding

使用 GLM 视觉模型分析图像，并使用 GLM-OCR 执行标准文字识别。

参数：

• images (字符串数组，必需)：1-8 个图像路径或 URL
• prompt_template (字符串，可选)：分析模板
  • describe: 通用图像描述（默认）
  • ocr: 文字提取 (OCR)
  • detect_objects: 物体检测
  • analyze_chart: 图表/数据可视化分析
  • custom: 使用自定义提示词
• custom_prompt (字符串，可选)：自定义提示词（当 prompt_template 为 custom 时必需）
• model (字符串，可选)：使用的 GLM 模型
  • glm-5v-turbo: 复杂视觉推理、GUI 理解与视觉编程
  • glm-4.6v: 高性能
  • glm-4.6v-flashx: 快速（默认）
  • glm-4.6v-flash: 免费快速

当 prompt_template="ocr" 且未传入 custom_prompt 时，工具会调用 glm-ocr 的 /api/paas/v4/layout_parsing 专用接口；如果提供自定义 OCR 提示词，则仍使用所选通用视觉模型，以保留自定义指令能力。本地 GLM-OCR 输入会校验真实文件内容，支持最大 10MB 的 JPEG/PNG 和最大 50MB 的 PDF。

示例：

分析图像 /path/to/image.jpg 并描述所有可见的物体。

file_preview

智能文件预览和摘要生成。

参数：

• file_paths (字符串数组，必需)：文件路径列表
• options (对象，可选)：预览选项
  • include_metadata (布尔值): 是否包含元数据 - 默认: true
  • include_summary (布尔值): 是否生成摘要 - 默认: true
  • max_summary_length (整数): 摘要最大长度 - 默认: 500

支持格式：

• PDF 文档 (.pdf)
• Word 文档 (.doc, .docx)
• Excel 表格 (.xls, .xlsx)
• PowerPoint 演示文稿 (.ppt, .pptx)
• 图像文件 (.png, .jpg, .jpeg, .gif, .bmp, .webp)

示例：

预览文件 /path/to/document.pdf 并生成摘要。

开发

运行测试

# 运行所有单元测试（不调用真实 API）
make test

# 运行真实 API 测试（需要配置 API 密钥）
make test-real

# 运行特定测试文件
make test-unit FILE=tests/tools/img_gen_tools/test_text_to_image.py

启动 HTTP 服务器

# 默认端口 8000
make serve-http

# 自定义端口
tf-tools-mcp serve --port 9000

# 自定义主机和端口
tf-tools-mcp serve --host 127.0.0.1 --port 9000

MCP Inspector 调试

make inspector

项目结构

tf_tools_mcp/
├── tf_tools_mcp/
│   ├── server.py              # MCP 服务器入口
│   ├── cli.py                 # CLI 命令行界面
│   ├── transports/            # 传输层实现
│   │   ├── base.py           # 抽象基类
│   │   ├── stdio.py          # 标准输入输出（MCP 默认）
│   │   └── http.py           # HTTP REST API
│   └── tools/
│       ├── img_gen_tools/     # 图像生成工具
│       │   ├── text_to_image.py
│       │   ├── image_to_image.py
│       │   ├── constants.py   # 模型配置
│       │   ├── types.py       # 类型定义
│       │   └── enhancers/     # 提示词增强
│       └── file_preview_tools/ # 文件预览工具
│           ├── file_preview.py
│           ├── image_understanding.py
│           └── handlers/      # 文件类型处理器
├── tests/                     # 测试套件
├── pyproject.toml            # 项目配置
├── Makefile                  # 构建脚本
└── README.md

打包发布

# 构建分发包
make package

# 发布到私有 PyPI
make publish-private

许可证

MIT License - 详见 LICENSE 文件

贡献

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

支持

如有问题和建议，请使用 GitHub Issue Tracker。