photographi-mcp

photographi-mcp

为 AI 应用提供快速、私密且基于事实的技术照片分析。

photographi-mcp 是一款 MCP 服务，可让 AI 模型和由大模型驱动的工具对本地照片库进行技术分析。它会直接在你的硬件上运行计算机视觉模型（由 photo-quality-analyzer-core 提供支持），评估清晰度、对焦和曝光，从而支持自动筛选、连拍排序和元数据索引等功能，无需上传到云端。

⚡ 为什么选择 photographi？

• 技术优先：专为客观指标（清晰度、光线、对焦）打造，为评估图像质量提供技术数据。
• 节省令牌：在本地预先筛选技术元数据，节省模型上下文。仅将最相关的信息发送给 AI 应用，让会话保持快速、精简。
• 隐私优先：所有分析都 100% 在你的设备本地完成。
• 低延迟：专为高效处理打造，可快速对本地照片文件夹进行排序并提供技术反馈。

---

👁️ 分析内容

• 智能对焦：检测主体并确认其清晰锐利
• 曝光：发现高光过曝和阴影死黑
• 适配器材：了解镜头的最佳成像区间，实现最佳清晰度
• 构图：评估取景和主体位置
• 质量提醒：标记运动模糊、衍射和高 ISO 噪点

说明

技术与艺术：此工具严格遵循客观标准。它根据技术指标和计算机视觉（清晰度、曝光、噪点等）评估照片。它不会理解艺术意图、美感或“氛围”。一张模糊、曝光不足的照片可能是艺术杰作，但 photographi 会准确地将其标记为技术质量较差。

关于背后的科学原理和数学，请参阅**技术文档**。

---

📸 实际效果

以下是实际照片分析的真实示例：

示例 1：优秀照片

{
  "overallConfidence": 0.89,
  "judgement": "Excellent",
  "keyMetrics": {
    "sharpness": 0.94,
    "exposure": 0.87,
    "composition": 0.85
  }
}

**结论：**主体清晰锐利，曝光良好，构图出色。

---

示例 2：较差照片

{
  "overallConfidence": 0.20,
  "judgement": "Very Poor",
  "keyMetrics": {
    "sharpness": 0.30,
    "focus": 0.07,
    "exposure": 0.0
  }
}

**结论：**主体对焦失败，严重曝光不足／黑位溢出，且头顶留白过多。

---

🛠️ 工具（MCP）

photographi-mcp 通过以下标准化工具，让 AI 模型能够进行深入的技术审查：

工具	AI“意图”示例	提供的操作／洞见
analyze_photo	“这张狗狗照片够清晰，可以打印吗？”	全面审查清晰度、对焦和光线。
analyze_folder	“我的‘Vacation’文件夹整体质量怎么样？”	提供统计摘要，识别最佳／最差的图像组。
rank_photographs	“找出这组蛋糕连拍中最好的一张。”	按技术完美度为文件排序，找出“主打”画面。
cull_photographs	“把所有模糊的照片移到垃圾文件夹。”	自动将失败的照片整理到子文件夹中。
threshold_cull	“使用 0.7 的分数严格筛选值得保留的照片。”	通过二元分类筛选出专业级素材。
get_color_palette	“这张日落照片里有哪些颜色适合我的网站？”	提取代表主要图像美感的十六进制颜色代码。
get_folder_palettes	“为我的‘Forest’拍摄生成一份情绪板。”	批量提取整个文件夹的颜色。
get_scene_content	“哪些照片里有‘cat’或‘mountain’？”	根据 80+ 种物体类别快速建立内容索引。

完整 API 参考

---

🚀 开始使用

Claude CLI（最快）

claude mcp add --scope user photographi uvx photographi-mcp

Claude Desktop（macOS）

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

{
  "mcpServers": {
    "photographi": {
      "command": "uvx",
      "args": ["photographi-mcp"]
    }
  }
}

GitHub Copilot CLI

添加到 ~/.config/github-copilot/config.json：

{
  "mcp_servers": {
    "photographi": {
      "command": "uvx",
      "args": ["photographi-mcp"]
    }
  }
}

---

🔒 隐私与遥测

photographi 秉持隐私优先的理念。

• 仅收集匿名汇总数据：我们绝不会收集文件名、路径或 EXIF 数据。
• 完全透明：可直接在 analytics.py 中审查我们的数据收集逻辑。
• 选择退出：设置环境变量 PHOTOGRAPHI_TELEMETRY_DISABLED=1，或使用 --disable-telemetry 标志。

---

📖 文档

• 安装与配置指南：详细的配置和故障排除说明。
• 科学原理：质量评分背后的数学原理和理论。
• 参与贡献：了解如何帮助改进项目。
• GitHub Issues：报告错误或请求新功能。

---