内容
# 视觉工具 MCP
一个 MCP 服务器，为 Claude Code 提供四种图像分析工具，用于检查截图、提取颜色和检查可访问性。
## 工具
| 工具 | 用途 |
|-|-|
| `get_image_coordinates_grid` | 返回图像尺寸和带有标记网格线的坐标参考网格叠加层（.1 至 .9）用于规划裁剪。 |
| `crop_to_magnify_image` | 使用归一化 0-1 坐标裁剪区域。作为放大镜，用于读取文本或验证视觉细节。 |
| `extract_colors` | 使用 k-means 聚类提取主导颜色为精确的十六进制值。可选地分析子区域。 |
| `check_contrast` | 计算两个十六进制颜色之间的 WCAG 2.1 对比度。返回 AA/AAA 通过/失败和 HSL/OKLCH 转换。 |
## 先决条件
- Python 3.9+
- macOS、Linux 或 WSL
### 运行时依赖
| 软件包 | 版本 |
|-|-|
| mcp[cli] | >=1.0, <3 |
| Pillow | >=10, <12 |
| numpy | >=1.24, <3 |
## 设置
```bash
bash setup.sh
```
这会在 `~/.vision-tools-env/` 处创建一个虚拟环境，并安装所有依赖项（运行时和开发环境）。
### 在 Claude Code 中注册
```bash
claude mcp add --transport stdio --scope user vision-tools \
-- ~/.vision-tools-env/bin/python3 /absolute/path/to/server.py
```
### 感知规则
要让 Claude 主动使用这些工具（而不仅仅是在明确要求时），请复制感知规则：
```bash
cp .claude/rules/vision-tools-awareness.md ~/.claude/rules/
```
## 开发
所有命令都假定已运行设置 (`bash setup.sh`)。
| 命令 | 用途 |
|-|-|
| `make check` | 运行完整的质量检查流程（检查 + 格式化 + 类型检查 + 测试 + 文件长度） |
| `make test` | 只运行 pytest 测试套件 |
| `make lint` | 只运行 ruff 检查 |
| `make format` | 自动格式化所有 Python 文件 |
| `make typecheck` | 以严格模式运行 mypy |
| `make smoke-test` | 快速集成测试 |
| `make live-qa` | 为实时 MCP QA 生成图像（参见 `tests/live_qa_checklist.md`） |
| `make clean` | 删除缓存和构建工件 |
### 环境变量
| 变量 | 默认值 | 用途 |
|-|-|-|
| `LOG_LEVEL` | `INFO` | 服务器日志详细程度（`DEBUG`、`INFO`、`WARNING`、`ERROR`） |
或者直接使用底层工具：
```bash
~/.vision-tools-env/bin/pytest -v
~/.vision-tools-env/bin/ruff check .
~/.vision-tools-env/bin/mypy .
bash lint.sh # 以上所有操作的顺序
```
## 架构
```
server.py MCP 服务器入口点 — 工具注册和连接
bootstrap.py 虚拟环境检测、依赖检查、自动设置
tools/
validators.py 共享验证器：validate_image_path、validate_coordinates、cleanup_temp_dir
crop.py crop_image 和 image_info 实现
grid.py 坐标网格叠加层渲染
colors.py 使用 numpy k-means 聚类的 extract_colors
contrast.py WCAG 对比度，HSL/OKLCH 转换（仅标准库）
tests/
conftest.py 共享夹具：synthetic_image、solid_color_image
test_validators.py 路径和坐标验证测试
test_crop.py crop_image 和 image_info 测试
test_grid.py 像素级网格渲染测试
test_colors.py _kmeans 和 extract_colors 测试
test_cleanup.py LRU 临时目录回收测试
test_validate_region.py 可选区域坐标验证测试
test_server.py 服务器包装器契约测试（JSON 序列化、错误处理）
test_integration.py 端到端流程测试（信息 → 裁剪 → 颜色）
generate_live_images.py 为实时 QA 生成确定性图像
live_qa_checklist.md 逐步 MCP QA 程序（13 个测试用例）
live_qa_images/ 生成的图像（gitignored）
```
### 依赖流程
```
bootstrap.py（仅标准库 — 无项目依赖）
server.py → bootstrap.py
→ tools/crop.py → tools/grid.py → tools/validators.py
→ tools/colors.py ─────────────→ tools/validators.py
→ tools/contrast.py（仅标准库 — 无工具/依赖）
```
无循环依赖。所有工具都依赖于 `validators.py` 进行共享验证。网格渲染与裁剪逻辑隔离。
### 坐标系统
所有工具都使用归一化 0-1 坐标：`(0, 0)` = 左上角，`(1, 1)` = 右下角。转换为像素：`px = int(normalized * dimension)`。填充被限制在图像边界内。
### 添加新工具
1. 创建 `tools/{name}.py`，包含一个返回 `dict` 的函数。
2. 从 `tools.validators` 导入共享验证器。
3. 在 `server.py` 中，使用 `@mcp.tool()` 注册 — 包装在 try/except 中，返回 `json.dumps(result)`。
4. 在 `tests/test_{name}.py` 中添加测试。
5. 运行 `make check` 进行验证。
参见 `docs/architecture.md` 获取完整的模式模板。
## 质量标准
- **代码检查工具**：ruff，包含 20+ 个规则组（pyflakes、bugbear、complexity、naming 等）
- **代码格式化工具**：ruff format（双引号，100 个字符行长）
- **类型检查工具**：严格模式下的 mypy
- **测试**：pytest，包含合成图像夹具 — 自动测试中无真实截图
- **复杂度**：最大圈复杂度 10，最大 40 条语句每函数
- **文件长度**：每个 Python 文件最大 750 行
- **CI**：GitHub Actions 在推送和 PR 上运行检查 + 格式化 + 类型检查 + 测试
