Metadata-Version: 2.4
Name: tf-tools-mcp
Version: 0.1.7
Summary: Image generation and understanding tools using OpenRouter and Zhipu AI
Author: huruize
License: MIT
Project-URL: Homepage, https://github.com/A2C-SMCP/tf_tools_mcp
Project-URL: Repository, https://github.com/A2C-SMCP/tf_tools_mcp
Project-URL: Issues, https://github.com/A2C-SMCP/tf_tools_mcp/issues
Keywords: mcp,image-generation,image-understanding,openrouter,zhipuai,glm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: Pillow>=10.0.0
Requires-Dist: zhipuai>=2.0.0
Requires-Dist: mcp>=0.1.0
Requires-Dist: fastmcp>=0.4.0
Requires-Dist: anyio>=4.0.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-docx>=1.0.0
Requires-Dist: python-pptx>=1.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: xlrd>=2.0.0
Requires-Dist: pdf2image>=1.17.0
Requires-Dist: pytest-xdist>=3.8.0
Requires-Dist: sniffio>=1.3.1
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: click>=8.1.0
Dynamic: license-file

# 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（推荐）

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

# 安装依赖
uv sync

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

### 从 PyPI 安装

```bash
pip install tf-tools-mcp
```

## 配置

### 1. 环境变量配置

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

```bash
# 必需：图像生成
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/) 注册，在 [https://openrouter.ai/keys](https://openrouter.ai/keys) 获取密钥
- **智谱 AI API Key**: 访问 [https://open.bigmodel.cn/](https://open.bigmodel.cn/) 注册，在 [https://open.bigmodel.cn/usercenter/apikeys](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 运行：

```json
{
  "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` 安装：

```json
{
  "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

```bash
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`：

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

### 其他 MCP 客户端

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

```bash
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 并生成摘要。
```

## 开发

### 运行测试

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

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

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

### 启动 HTTP 服务器

```bash
# 默认端口 8000
make serve-http

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

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

### MCP Inspector 调试

```bash
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
```

## 打包发布

```bash
# 构建分发包
make package

# 发布到私有 PyPI
make publish-private
```

## 许可证

MIT License - 详见 LICENSE 文件

## 贡献

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

## 支持

如有问题和建议，请使用 [GitHub Issue Tracker](https://github.com/A2C-SMCP/tf_tools_mcp/issues)。
