photographi-mcp

photographi-mcp

AI アプリケーション向けの、高速でプライベート、根拠に基づいた技術的な写真分析。

photographi-mcp は、AI モデルや LLM を活用したツールが、ローカルの写真ライブラリを技術的に分析できるようにする MCP サーバーです。お使いのハードウェア上でコンピュータービジョンモデルを直接実行し（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	「このケーキの連写写真からベストショットを見つけてください。」	技術的な完成度に基づいてファイルをランキングし、主役となる1枚を見つけます。
cull_photographs	「ぼやけた写真をすべて不要フォルダーに移動してください。」	失敗した写真をサブフォルダーに自動で整理します。
threshold_cull	「0.7 のスコアを使って、残す写真を厳密に選別してください。」	二分方式で分類し、プロ品質の素材を抽出します。
get_color_palette	「この夕焼けに使われている色を、ウェブサイト用に教えてください。」	画像で優勢な色を表す 16 進コードを抽出します。
get_folder_palettes	「『Forest』の撮影写真からムードボードを作成してください。」	フォルダー全体の色を一括抽出します。
get_scene_content	「『猫』や『山』が写っている写真はどれですか？」	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：バグの報告や機能のリクエスト。

---