Photo-Filter MCP Server

Subagent für AI Reporter Backend zur 3D-Rekonstruktion aus Bildserien.

Platform: macOS M-Serie (native)
Type: MCP Server (Model Context Protocol)
Version: 0.2.0

---

Features

• ✅ CLIP-basierte Filterung – Schnelle semantische Konsistenzprüfung
• ✅ SuperPoint Geometrie – Robuste Feature-Extraktion und epipolare Validierung
• ✅ Hybrid-Strategie – Kombination beider Methoden für optimale Ergebnisse
• ✅ Metal Performance Shaders – Native M-Serie GPU-Optimierung
• ✅ MCP-Integration – Direkte Einbindung in AI Reporter
• ✅ Session Management – State-Tracking für asynchrone Verarbeitung

---

Installation

Schnellstart

cd /Volumes/mac-studio/development/photo-filter-mcp-server

# Installation
make install

# Test
make start

# Production (launchd)
make install-service

Manuelle Installation

# Virtual Environment
python3 -m venv venv
source venv/bin/activate

# Dependencies
pip install -r requirements.txt

# PyTorch mit MPS
pip install --pre torch torchvision torchaudio \
    --index-url https://download.pytorch.org/whl/nightly/cpu

---

Verwendung

Vom Bildordner zum 3D-Modell

photo3d model filtert einen Ordner und rekonstruiert ihn anschließend mit COLMAP. Ein ai-reporter-Report wird dafür nicht gebraucht – gedacht für Fotos, die einfach in einem Ordner liegen.

photo3d model ~/photos_for_3d/2026-07-30_Kusams

Das Ergebnis landet in <ordner>/photo3d_model/: sparse_points.ply (Punktwolke), sparse/0/ (COLMAP-Modell mit Kameraposen) und reconstruction.json (Kennzahlen). Mit --no-filter läuft die Rekonstruktion ohne Vorauswahl, mit --splat schließt sich Gaussian Splatting an.

Verlangt werden mindestens drei Aufnahmen, und zwar aus verschiedenen Positionen: zwei Bilder derselben Stelle enthalten keine Parallaxe, aus der sich Tiefe ableiten ließe. Wer die Kette ohne eigene Fotos prüfen will, erzeugt sich mit photo3d scene eine Testserie mit bekannter Grundwahrheit:

photo3d scene /tmp/szene
photo3d model /tmp/szene

Als Entwickler (Dev-Mode)

source venv/bin/activate
python src/server/mcp_server.py

Als Service (Production)

# Installieren
make install-service

# Befehle
launchctl start com.photofilter.mcp      # Starten
launchctl stop com.photofilter.mcp       # Stoppen
launchctl list com.photofilter.mcp       # Status
tail -f ~/.photo-filter-mcp/logs/*.log   # Logs

---

API Tools

1. filter_photos

Filtert Fotos aus einem Verzeichnis für 3D-Rekonstruktion.

{
    "image_folder": "/path/to/images",
    "strategy": "hybrid",  # clip, superpoint, hybrid
    "session_id": "session-123",
    "clip_similarity_threshold": 0.75,
    "superpoint_min_keypoints": 250
}

Response:

{
    "selected_paths": ["image1.jpg", "image2.jpg", ...],
    "n_selected": 42,
    "strategy": "hybrid",
    "processing_time_sec": 125.3,
    "confidence_scores": {"image1.jpg": 0.95, ...},
    "rejection_summary": {
        "quality_fail": 10,
        "similarity_fail": 8,
        "error": 0
    }
}

2. analyze_photo_geometry

Analysiert geometrische Konsistenz einer Bildgruppe.

{
    "image_paths": ["/path/image1.jpg", "/path/image2.jpg", ...],
    "reference_image_idx": 0,
    "session_id": "session-123"
}

3. generate_reconstruction_manifest

Generiert Manifest für nachgelagerte 3D-Rekonstruktion.

{
    "filtered_image_paths": ["/path/image1.jpg", ...],
    "output_dir": "/output/manifests",
    "reconstruction_type": "sfm",  # sfm, gaussian-splatting, nerf
    "camera_intrinsics": {"fx": 1000, "fy": 1000, "cx": 512, "cy": 512}
}

4. get_session_state

Ruft aktuellen Session-State ab.

{
    "session_id": "session-123"
}

---

Filterungs-Strategien

CLIP (Schnell)

• Laplacian-Varianz für Schärfe
• Beleuchtungsstabilität
• Kontrast-Metriken
• CLIP-Embeddings für Redundanzentfernung
• Zeit: ~10-50ms pro Bild

SuperPoint (Robust)

• SuperPoint Feature Detection
• Epipolare Geometrie (RANSAC-F)
• Keypoint-Dichte-Validierung
• Zeit: ~100-200ms pro Bild

Hybrid (Empfohlen)

• Stufe 1: CLIP (schnelle Vorfilterung)
• Stufe 2: SuperPoint (präzise Validierung)
• Zeit: ~110-250ms pro Bild insgesamt

---

Konfiguration

MPS-Fallback

Falls Metal Performance Shaders nicht verfügbar:

export PYTORCH_ENABLE_MPS_FALLBACK=1
python src/server/mcp_server.py

State Management

Sessions werden persistiert in:

~/.photo-filter-mcp/sessions/

Logs

Alle Logs landen in:

~/.photo-filter-mcp/server.log

Bei launchd:

~/.photo-filter-mcp/logs/stdout.log
~/.photo-filter-mcp/logs/stderr.log

---

AI Reporter Integration

Konfiguriere den Subagent in AI Reporter:

subagent:
  id: "photo-filter-3d"
  type: "mcp"

  mcp_config:
    server: "python"
    command: "photo-filter-mcp"

  tools:
    - name: "filter_photos"
      auto_invoke_for_goals: ["reconstruct_3d_model"]

    - name: "analyze_photo_geometry"
      depends_on: ["filter_photos"]

    - name: "generate_reconstruction_manifest"
      depends_on: ["analyze_photo_geometry"]

---

Troubleshooting

MPS verfügbar?

python -c "import torch; print(torch.backends.mps.is_available())"

Service startet nicht?

# plist validieren
plutil -lint ~/Library/LaunchAgents/com.photofilter.mcp.plist

# Logs prüfen
log stream --level debug --predicate 'process=="com.photofilter.mcp"'

# Manuell testen
python src/server/mcp_server.py

Memory-Probleme?

Reduziere Batch-Größe oder nutze nur CLIP-Filter bei großen Bildmengen.

---

Verzeichnisstruktur

photo-filter-mcp-server/
├── src/
│   ├── server/
│   │   └── mcp_server.py
│   ├── models/
│   │   ├── base_filter.py
│   │   ├── clip_filter.py
│   │   └── superpoint_filter.py
│   ├── config/
│   │   └── tool_schemas.py
│   └── utils/
│       ├── state_manager.py
│       └── result_serializer.py
├── scripts/
│   ├── install.sh
│   └── setup-launchd.sh
├── pyproject.toml
├── requirements.txt
└── Makefile

---

Development

Test-Server starten

make start

Code-Stil

# Mit Black und Ruff formatieren
black src/
ruff check src/ --fix

Tests ausführen

make test

---

Lizenz

MIT

---

Support: Siehe Logs in ~/.photo-filter-mcp/