Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,93 @@
+# Immich photo map MCP pattern
+
+## Use case
+
+Build a read-only Immich MCP that extracts asset metadata and exposes geotagged photos as structured data for maps and summaries.
+
+## Immich endpoints
+
+Useful Immich API endpoints:
+
+```text
+POST /search/metadata
+GET  /assets/{id}/metadata
+```
+
+For asset searches, request EXIF in results:
+
+```json
+{
+  "withExif": true,
+  "size": 500,
+  "takenAfter": "2026-01-01T00:00:00Z",
+  "takenBefore": "2026-12-31T23:59:59Z"
+}
+```
+
+## MCP tool shape
+
+Recommended tools:
+
+- `immich_search_geo_assets(taken_after, taken_before, album_id=None, limit=500)` — returns assets with latitude/longitude, taken date, location labels, camera info, and thumbnail URL.
+- `immich_get_asset_metadata(asset_id)` — returns full metadata for one asset.
+- `immich_geojson(...)` — returns a GeoJSON `FeatureCollection` for Leaflet/OpenStreetMap.
+- `immich_map_summary(...)` — returns top locations, missing-GPS count, and date-range summary.
+
+## Output contracts
+
+Asset record:
+
+```json
+{
+  "id": "asset-uuid",
+  "filename": "IMG_1234.jpeg",
+  "taken_at": "2026-07-14T10:31:00",
+  "latitude": 32.0809,
+  "longitude": -81.0912,
+  "city": "Savannah",
+  "state": "Georgia",
+  "country": "United States",
+  "camera_make": "Apple",
+  "camera_model": "iPhone 15 Pro",
+  "thumb_url": "/api/assets/{id}/thumbnail"
+}
+```
+
+GeoJSON feature:
+
+```json
+{
+  "type": "Feature",
+  "geometry": {"type": "Point", "coordinates": [-81.0912, 32.0809]},
+  "properties": {"asset_id": "uuid", "filename": "IMG_1234.jpeg", "taken_at": "..."}
+}
+```
+
+## Map UI
+
+The MCP provides data; the web UI can be Leaflet.js with OpenStreetMap tiles, marker clustering, album/date filters, and thumbnail popups.
+
+Recommended internal paths:
+
+```text
+ops.itpropartner.com/immich-map.html
+or
+photos.itpropartner.com/map
+```
+
+## Security notes
+
+Photo GPS data is sensitive.
+
+- Keep MCP localhost-only.
+- Store `IMMICH_BASE_URL` and `IMMICH_API_KEY` in a chmod 600 `.env` / systemd `EnvironmentFile`.
+- Put any map UI behind existing auth/Cloudflare Access.
+- Prefer thumbnails over full-resolution images.
+- Count missing GPS as `missing_location`, not as errors.
+
+## Build order
+
+1. Read-only MCP first: search, metadata, GeoJSON, summaries.
+2. Verify against a small date range.
+3. Build map UI.
+4. Only later consider metadata update/fix tools.