Skip to main content

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 密钥

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。

Metadata

Release files for tf-tools-mcp 0.1.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tf-tools-mcp 0.1.7
File Size Uploaded Provenance Actions
tf_tools_mcp-0.1.7.tar.gz 47.9 kB With provenance Details for tf_tools_mcp-0.1.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tf-tools-mcp 0.1.7
File Interpreter ABI Platform Actions
tf_tools_mcp-0.1.7-py3-none-any.whl Python 3 none any Details for tf_tools_mcp-0.1.7-py3-none-any.whl

Total release size: 112.1 kB

Release files / tf_tools_mcp-0.1.7.tar.gz

Download URL tf_tools_mcp-0.1.7.tar.gz
Size 47.9 kB
Tags Source
SHA-256 checksum
How to use checksums
a7b880bf9efd3e673090aa045db42f36b151adf46821e85fac60eee7ed945429
BLAKE2b-256 checksum
How to use checksums
e17842091db3118a8607a37068dcbfa9a3cc75c5819697a1d2fb6d141e797512
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Release files / tf_tools_mcp-0.1.7-py3-none-any.whl

Download URL tf_tools_mcp-0.1.7-py3-none-any.whl
Size 64.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f008794a089c2addbed4a22bb8ffb618883bfecc59f44acd513b339f765173c4
BLAKE2b-256 checksum
How to use checksums
1639da48a3d704f7af1e438f6aaff55cebd3c92f33d3ff9a9ed6bef306e3401a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

Security for tf-tools-mcp 0.1.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tf_tools_mcp-0.1.7.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page