Chuk MCP Vision

中大企业愿景

通用计算机视觉MCP服务器，具有用于图像分析的原子可组合工具。

CHUK生态系统的一部分-旨在与 chuk-ai-planner 用于视觉图元的智能编排。

哲学

此MCP服务器提供 原子通用视觉工具 -不是特定领域的解决方案。“如何解析数独”或“如何阅读棋盘”的智能存在于规划者/剧本层，而不是工具本身。

每个工具都擅长一件事：

• detect_lines -在图像中查找直线
• detect_contours -找到形状和边界
• detect_grid -查找网格结构（网格、表格）
• extract_grid_cells -从网格中提取单个单元格
• perspective_transform -正确的倾斜/角度
• extract_region -种植感兴趣的地区
• ocr_region -从某个区域读取文本/数字
• ocr_multi_backend -带有投票功能的OCR集成
• verify_cell_multi_llm -多LLM共识验证
• verify_digit_rotation_consensus -基于旋转的消歧
• embed_image -生成向量嵌入
• analyze -高级场景理解（使用LLM视觉）

准确性和结果

完成工作流程：准确率98.8% 关于数独提取，使用：

• 网格检测+OCR（基线93.8%）
• 域验证（数独规则）
• 多LLM共识（OpenAI+Anthropic+谷歌投票）
• 智能旋转测试（6 vs 9消歧）
• 成本优化（只有8.6%的电池需要LLM验证）

看 examples/07_complete_workflows/sudoku_extraction.py 为了全面实施。

主要特点

🎯 多LLM共识

组合多个Vision LLM以获得更高的精度：

• OpenAI GPT-4o：快速，非常适合打印文本
• 克劳德3.5十四行诗：卓越的推理能力
• 谷歌双子座2.0 Flash：成本效益高

使用投票共识来减少模型偏差并提高准确性。

🔄 旋转试验

自动消除方向相关字符的歧义：

• 6对9 （180°旋转）
• b vs q，d vs p （字母）
• 方向符号

🧩 网格处理

基于网格内容的专用工具：

• 自动检测网格结构 （行、列、单元格边界）
• 提取所有细胞 具有自动预处理功能
• 对单元格内容进行分类 （空、数字、文本、复选框）
• 域确认 （数独、填字游戏、表格约束）

📊 多后端OCR

跨OCR引擎的集合投票：

• PaddleOCR：最佳精度，GPU加速
• 立方体：CPU友好型回退

投票通过结合不同引擎的优势来提高准确性。

安装

uv pip install chuk-mcp-vision

或者使用开发工具：

uv pip install chuk-mcp-vision[dev]

用法

使用克劳德桌面

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vision": {
      "command": "uv",
      "args": ["run", "chuk-mcp-vision"]
    }
  }
}

独立

# Run in STDIO mode (default)
uv run chuk-mcp-vision

# Run in HTTP mode for web integration
uv run chuk-mcp-vision http

示例工作流

1.基本网格提取（93.8%准确率）

from chuk_mcp_vision.tools.grid import detect_grid, extract_grid_cells, classify_cell_content

# Detect grid structure
grid = await detect_grid(image_uri)

# Extract all cells
cells = await extract_grid_cells(image_uri, grid, preprocess=True)

# Classify each cell
for cell in cells.cells:
    content = await classify_cell_content(cell.image_uri, expected_type="digit")
    print(f"Cell [{cell.row},{cell.col}]: {content.value}")

2.多后端OCR（准确率95%）

from chuk_mcp_vision.tools.ocr import ocr_multi_backend
from chuk_mcp_vision.models import OCRBackend

# Run multiple OCR engines and vote
result = await ocr_multi_backend(
    image_uri,
    backends=[OCRBackend.PADDLEOCR, OCRBackend.TESSERACT]
)

print(f"Consensus: {result.consensus_text}")
print(f"Confidence: {result.consensus_confidence}")

3.多LLM共识（准确率98.8%）

from chuk_mcp_vision.tools.llm.consensus import verify_cell_multi_llm
from chuk_mcp_vision.models import VisionLLMProvider

# Query multiple Vision LLMs and vote
result = await verify_cell_multi_llm(
    cell_uri,
    providers=[
        VisionLLMProvider.OPENAI,
        VisionLLMProvider.ANTHROPIC,
        VisionLLMProvider.GOOGLE
    ],
    expected_type="digit"
)

print(f"Consensus: {result['consensus_value']}")
print(f"Confidence: {result['consensus_confidence']}")

4.完成旋转工作流程（99%以上精度）

from chuk_mcp_vision.tools.grid import detect_grid, extract_grid_cells
from chuk_mcp_vision.tools.llm.consensus import verify_digit_rotation_consensus

# Detect and extract grid
grid = await detect_grid(image_uri)
cells = await extract_grid_cells(image_uri, grid)

# For suspicious cells, use rotation + multi-LLM consensus
result = await verify_digit_rotation_consensus(
    cell_uri,
    angles=[0, 180],  # Test 6 vs 9
    providers=["openai", "anthropic", "google"]
)

print(f"Value: {result['recommended_value']}")
print(f"Orientation: {result['recommended_angle']}°")
print(f"Confidence: {result['confidence']}")

工具参考

网格工具

detect_grid(image_uri)

• 检测网格结构（行、列、单元格边界）
• 退货： GridStructure 带边界、行/列分隔符

extract_grid_cells(image_uri, grid, margin=5, preprocess=True)

• 从检测到的网格中提取所有单元格
• 退货： ExtractGridCellsResponse 带有细胞图像和位置

classify_cell_content(cell_uri, expected_type="auto")

• 对单元格内容进行分类（空、数字、文本、复选框）
• 退货： CellContent 有类型、价值、信心

OCR工具

ocr_region(image_uri, backend=OCRBackend.PADDLEOCR, language="en")

• 单后端OCR
• 退货： OCRRegionResponse 有文字、线条、单词、自信

ocr_multi_backend(image_uri, backends=None, language="en")

• 具有投票功能的多后端集成OCR
• 退货： MultiBackendOCRResponse 达成共识

视觉LLM工具

verify_cell_multi_llm(cell_uri, providers=None, expected_type="digit")

• 多LLM共识验证
• 回报：共识值、置信度、投票细节

verify_digit_rotation_consensus(cell_uri, angles=[0, 180], providers=None)

• 旋转测试+多LLM共识
• 返回值：推荐值、角度、置信度

变换工具

perspective_transform(image_uri, x1, y1, x2, y2, x3, y3, x4, y4, width, height)

• 纠正倾斜和透视失真
• 返回：转换后的图像URI

extract_region(image_uri, x, y, width, height)

• 感兴趣的作物和提取物区域
• 返回：裁剪图像URI

rotate_and_classify(image_uri, angles=None, classifier_callback=None)

• 多次旋转测试内容
• 返回：按角度、推荐方向显示的结果

检测工具

detect_lines(image_uri, min_line_length=50, threshold=150)

• 使用霍夫变换检测直线
• 返回值：带坐标的线段

detect_contours(image_uri, threshold=127, min_area=100)

• 检测形状和边界
• 返回：带点的轮廓

分析工具

analyze(image_uri, use_vision_model=False)

• 高级场景理解
• 返回：场景类型、结构、内容提示、建议工具

embed_image(image_uri, backend=EmbeddingBackend.EVA02)

• 生成向量嵌入以进行相似性搜索
• 返回：嵌入向量

配置

没有魔术弦

所有型号和后端都使用枚举：

from chuk_mcp_vision.models import (
    VisionLLMProvider,  # OPENAI, ANTHROPIC, GOOGLE
    VisionModel,        # GPT_4O, CLAUDE_3_5_SONNET, GEMINI_2_0_FLASH
    OCRBackend,         # PADDLEOCR, TESSERACT
    EmbeddingBackend    # EVA02, JINA_CLIP
)

# Configurable models
await verify_cell_multi_llm(
    cell_uri,
    providers=[VisionLLMProvider.OPENAI],
    model_config={
        "openai": VisionModel.GPT_4O_MINI.value  # Use cheaper model
    }
)

环境变量

# Vision LLM API Keys
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GOOGLE_API_KEY="..."

例子

综合示例 examples/ 目录：

• 01_basics/：核心视觉图元（线条、轮廓、OCR、嵌入）
• 02_transforms/：图像变换（裁剪、旋转、透视）
• 03_preprocessing/：图像增强管道
• 04_grids/：网格检测和细胞提取（准确率93.8%）
• 05_ocr/：具有投票功能的多后端OCR（准确率95%）
• 06_llm/：视觉LLM共识和轮换测试
• 07_complete_workflows/：完全数独提取（准确率98.8%）

运行示例：

# Basic examples
uv run python examples/01_basics/detect_lines.py
uv run python examples/01_basics/ocr_basic.py

# Grid processing
uv run python examples/04_grids/full_pipeline.py

# Multi-LLM consensus
uv run python examples/06_llm/single_llm.py
uv run python examples/06_llm/multi_llm_consensus.py

# Complete workflow
uv run python examples/07_complete_workflows/sudoku_extraction.py

与CHUK生态系统整合

• chuk mcp服务器：使用@tool装饰器的基本MCP框架
• 楚克文物：存储图像、嵌入和OCR结果
• 楚艾规划师：根据场景分析编排视觉工具
• chuk-mcp求解器：消耗结构化数据（数独网格等）

发展

# Install development dependencies
make dev-install

# Run tests
make test

# Run all checks (lint, typecheck, security, tests)
make check

# Format code
make format

# Build
make build

代码质量

• ✅ 代码检查：Ruff（所有检查均通过）
• ✅ 类型检查：MyPy（所有检查均通过）
• ✅ 安全：Bandit（未发现问题）
• ✅ 测试：Pytest（全部通过）
• ✅ 格式化：黑色/褶边（风格一致）

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

链接

• GitHub: https://github.com/chrishayuk/chuk-mcp-vision
• PyPI: https://pypi.org/project/chuk-mcp-vision/
• 模型上下文协议: https://modelcontextprotocol.io

______________________________________________________________________

专为CHUK生态系统构建-用于复杂工作流程的可组合AI工具