shotlog-mcp 0.1.0__tar.gz

shotlog_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+*.png
+manifest*.json
+report.md

shotlog_mcp-0.1.0/LAUNCH.md

@@ -0,0 +1,76 @@
+# Lanzamiento de shotlog-mcp (notas privadas, no se suben al repo)
+
+Orden: GitHub → PyPI → MCP Registry → Glama + awesome-mcp-servers → LinkedIn.
+
+## 1. GitHub
+
+```bash
+cd ~/shotlog-mcp && gh repo create shotlog-mcp --public --source . --push \
+  --description "MCP server: let your AI assistant capture macOS windows into a numbered, captioned evidence log for lab reports, QA and docs."
+gh repo edit --add-topic mcp,mcp-server,model-context-protocol,screenshot,macos,claude,python
+```
+
+## 2. PyPI (lo haces tú)
+
+1. Crea una cuenta en https://pypi.org/account/register/ y verifica el correo.
+2. Activa la 2FA (es obligatoria para publicar): *Account settings → Two factor authentication*.
+3. Crea un token: *Account settings → API tokens → Add API token*. En el alcance elige **"Entire account"**, porque el proyecto todavía no existe. Copia el token `pypi-…`; solo se muestra una vez.
+4. En **tu propia terminal** (no con `!` en Claude, para que el token no quede en la conversación):
+   ```bash
+   cd ~/shotlog-mcp
+   rm -rf dist && uv build
+   uv publish --token pypi-TU_TOKEN
+   ```
+5. Comprueba que se publicó:
+   - https://pypi.org/project/shotlog-mcp/ debe mostrar el README.
+   - `claude mcp add shotlog -- uvx shotlog-mcp` y luego `/mcp` en Claude Code: debe aparecer *connected*.
+6. Seguridad: borra el token "Entire account" y crea uno limitado al proyecto `shotlog-mcp` para las próximas versiones.
+
+Para cada versión nueva, sube el número en `pyproject.toml`, en `src/shotlog_mcp/__init__.py` y en las 2 entradas de `server.json`. Después ejecuta `uv build && uv publish` y crea un tag `git tag v0.1.1 && git push --tags`.
+
+## 3. MCP Registry oficial (solo cuando ya esté en PyPI)
+
+```bash
+cd ~/shotlog-mcp
+mcp-publisher login github     # te muestra un código; lo pegas en github.com/login/device
+mcp-publisher publish
+```
+Para verificar: `curl "https://registry.modelcontextprotocol.io/v0/servers?search=shotlog"`
+
+## 4. Glama + awesome-mcp-servers
+
+1. Entra en https://glama.ai/mcp/servers con GitHub y usa *Add server* con la URL del repo. Casi todas las entradas de la lista llevan su insignia de Glama.
+2. Agrega un PR a https://github.com/punkpeye/awesome-mcp-servers en la sección **🖥️ OS Automation**, en orden alfabético:
+
+```markdown
+- [Marlon-Trujillo-Jaramillo/shotlog-mcp](https://github.com/Marlon-Trujillo-Jaramillo/shotlog-mcp) [![Marlon-Trujillo-Jaramillo/shotlog-mcp MCP server](https://glama.ai/mcp/servers/Marlon-Trujillo-Jaramillo/shotlog-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Marlon-Trujillo-Jaramillo/shotlog-mcp) 🐍 🏠 🍎 - Captures specific macOS windows into a numbered, captioned screenshot log (activity, command, result), pulls screenshots from other machines over SCP and exports a Markdown report for lab reports, QA evidence and docs. `uvx shotlog-mcp`
+```
+
+Título del PR: `Add shotlog-mcp (OS Automation)`
+
+## 5. Post para LinkedIn (español)
+
+> En mi laboratorio de Sistemas Operativos cada paso necesitaba una captura de pantalla como evidencia, y trabajaba a la vez en un Mac y en un portátil con Windows. Tomarlas, renombrarlas, ordenarlas y describirlas a mano me costaba más que el laboratorio mismo.
+>
+> Así que construí **shotlog-mcp**, un servidor MCP de código abierto que le permite a un asistente de IA (Claude, por ejemplo):
+> 📸 capturar una ventana concreta de macOS, no toda la pantalla
+> 🔢 numerarla y guardarle una ficha: actividad, comando y resultado
+> 💻 traer por SSH las capturas del otro equipo, en la misma serie
+> 📄 generar el informe en Markdown/PDF con todo en orden
+>
+> Ahora solo le digo: "ejecuta ssh -V, toma la captura y regístrala como paso 3".
+>
+> Sirve igual para evidencias de QA, tutoriales y reportes de bugs. Es MIT y se instala con una línea:
+> `claude mcp add shotlog -- uvx shotlog-mcp`
+>
+> 🔗 github.com/Marlon-Trujillo-Jaramillo/shotlog-mcp
+>
+> Se aceptan feedback, estrellas ⭐ y PRs (el siguiente paso es el soporte para Windows y Linux).
+>
+> #MCP #IA #Python #OpenSource #macOS #ClaudeAI
+
+Adjunta `docs/demo.gif`. En LinkedIn, un GIF o video consigue mucho más alcance que un enlace solo.
+
+### Versión corta para X / Reddit (r/ClaudeAI, r/mcp)
+
+> I built shotlog-mcp: an MCP server that lets your AI assistant screenshot a specific macOS window, number it, caption it (activity/command/result) and export a report. It was born from an OS lab where every step needed evidence. MIT, `uvx shotlog-mcp`. github.com/Marlon-Trujillo-Jaramillo/shotlog-mcp

shotlog_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marlon Trujillo Jaramillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shotlog_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.5
+Name: shotlog-mcp
+Version: 0.1.0
+Summary: MCP server that captures macOS windows into a numbered, captioned evidence log for lab reports, QA and docs.
+Project-URL: Repository, https://github.com/Marlon-Trujillo-Jaramillo/shotlog-mcp
+Author: Marlon Trujillo Jaramillo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,documentation,macos,mcp,model-context-protocol,qa,screenshot
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: pyobjc-framework-quartz; sys_platform == 'darwin'
+Description-Content-Type: text/markdown
+
+# shotlog-mcp
+
+**Let your AI assistant take the screenshots for your report.**
+
+An [MCP](https://modelcontextprotocol.io) server for macOS. It captures a specific window, saves it with a sequential number and a caption (activity, command, result), and puts everything together into a Markdown report you can turn into a PDF.
+
+It was built for a university OS lab where every step had to be backed by a screenshot, on a Mac and a Windows laptop at the same time. It works the same way for QA evidence, tutorials, runbooks and bug reports.
+
+[Leer en español](README.es.md)
+
+![shotlog demo: the assistant captures a Terminal window as step 1 and exports the report](https://raw.githubusercontent.com/Marlon-Trujillo-Jaramillo/shotlog-mcp/main/docs/demo.gif)
+
+<!-- mcp-name: io.github.Marlon-Trujillo-Jaramillo/shotlog-mcp -->
+
+## What it does
+
+| Tool | Description |
+|---|---|
+| `list_windows` | Lists the visible windows (app, title, size). |
+| `save_screenshot` | Captures **one** window, picked by app and/or title (front-most by default), and saves it as `001_name.png` together with its caption. |
+| `update_caption` | Fills in or fixes the caption afterwards. |
+| `list_screenshots` | Shows the log in order. |
+| `pull_remote_screenshots` | Fetches new screenshots from another machine (e.g. Windows' `Pictures\Screenshots`) over SCP and numbers them in the same sequence. |
+| `export_report` | Writes `report.md`: every screenshot with its caption, in order. |
+
+Then just ask: *"Run `ssh -V` in the terminal, take a screenshot of it and caption it as step 3."*
+
+## Install
+
+Requires macOS, Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+**Claude Code**
+
+```bash
+claude mcp add shotlog -- uvx shotlog-mcp
+```
+
+**Claude Desktop / other MCP clients**
+
+```json
+{
+  "mcpServers": {
+    "shotlog": { "command": "uvx", "args": ["shotlog-mcp"] }
+  }
+}
+```
+
+The first capture needs the **Screen Recording** permission for the app that runs the server (Terminal, iTerm, VS Code, Claude…): *System Settings → Privacy & Security → Screen Recording*.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `SHOTLOG_DIR` | `~/shotlog` | Where screenshots, `manifest.json` and `report.md` are saved. |
+
+Use one folder per project: `claude mcp add shotlog -e SHOTLOG_DIR=~/lab3/shots -- uvx shotlog-mcp`
+
+### Remote screenshots (optional)
+
+To use `pull_remote_screenshots`, the other machine needs an SSH server (on Windows: *Settings → Optional features → OpenSSH Server*) and key-based login from your Mac, so that no password is asked for.
+
+## Report to PDF
+
+```bash
+cd ~/shotlog && pandoc report.md -o report.pdf
+```
+
+## Development
+
+```bash
+uv run --group dev pytest
+```
+
+## License
+
+MIT

shotlog_mcp-0.1.0/README.es.md

@@ -0,0 +1,42 @@
+# shotlog-mcp
+
+**Que tu asistente de IA tome las capturas de tu informe.**
+
+Es un servidor [MCP](https://modelcontextprotocol.io) para macOS. Captura una ventana concreta, la guarda con un número consecutivo y una ficha (actividad, comando, resultado), y junta todo en un informe Markdown que puedes convertir a PDF.
+
+Nació en un laboratorio de Sistemas Operativos donde cada paso tenía que respaldarse con una captura, trabajando a la vez en un Mac y en un portátil Windows. También sirve para evidencias de QA, tutoriales, runbooks y reportes de bugs.
+
+[Read in English](README.md)
+
+![demo](docs/demo.gif)
+
+## Herramientas
+
+| Herramienta | Qué hace |
+|---|---|
+| `list_windows` | Lista las ventanas visibles. |
+| `save_screenshot` | Captura **una** ventana, elegida por app o título (si no indicas nada, la que está al frente), y la guarda como `001_nombre.png` con su ficha. |
+| `update_caption` | Completa o corrige la ficha después. |
+| `list_screenshots` | Muestra el registro en orden. |
+| `pull_remote_screenshots` | Trae por SCP las capturas nuevas de otro equipo (por ejemplo `Imágenes\Capturas` en Windows) y las numera en la misma serie. |
+| `export_report` | Genera `report.md` con todas las capturas y sus fichas, en orden. |
+
+Luego solo pides: *"Ejecuta `ssh -V` en la terminal, toma una captura y ponle como ficha el paso 3."*
+
+## Instalación
+
+Necesitas macOS, Python 3.11+ y [uv](https://docs.astral.sh/uv/).
+
+```bash
+claude mcp add shotlog -- uvx shotlog-mcp
+```
+
+Para la primera captura hay que dar el permiso de **Grabación de pantalla** a la app que ejecuta el servidor: *Ajustes del Sistema → Privacidad y seguridad → Grabación de pantalla*.
+
+La carpeta de destino se cambia con `SHOTLOG_DIR` (por defecto es `~/shotlog`).
+
+Para pasar el informe a PDF: `pandoc report.md -o report.pdf`
+
+## Licencia
+
+MIT

shotlog_mcp-0.1.0/README.md

@@ -0,0 +1,76 @@
+# shotlog-mcp
+
+**Let your AI assistant take the screenshots for your report.**
+
+An [MCP](https://modelcontextprotocol.io) server for macOS. It captures a specific window, saves it with a sequential number and a caption (activity, command, result), and puts everything together into a Markdown report you can turn into a PDF.
+
+It was built for a university OS lab where every step had to be backed by a screenshot, on a Mac and a Windows laptop at the same time. It works the same way for QA evidence, tutorials, runbooks and bug reports.
+
+[Leer en español](README.es.md)
+
+![shotlog demo: the assistant captures a Terminal window as step 1 and exports the report](https://raw.githubusercontent.com/Marlon-Trujillo-Jaramillo/shotlog-mcp/main/docs/demo.gif)
+
+<!-- mcp-name: io.github.Marlon-Trujillo-Jaramillo/shotlog-mcp -->
+
+## What it does
+
+| Tool | Description |
+|---|---|
+| `list_windows` | Lists the visible windows (app, title, size). |
+| `save_screenshot` | Captures **one** window, picked by app and/or title (front-most by default), and saves it as `001_name.png` together with its caption. |
+| `update_caption` | Fills in or fixes the caption afterwards. |
+| `list_screenshots` | Shows the log in order. |
+| `pull_remote_screenshots` | Fetches new screenshots from another machine (e.g. Windows' `Pictures\Screenshots`) over SCP and numbers them in the same sequence. |
+| `export_report` | Writes `report.md`: every screenshot with its caption, in order. |
+
+Then just ask: *"Run `ssh -V` in the terminal, take a screenshot of it and caption it as step 3."*
+
+## Install
+
+Requires macOS, Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+**Claude Code**
+
+```bash
+claude mcp add shotlog -- uvx shotlog-mcp
+```
+
+**Claude Desktop / other MCP clients**
+
+```json
+{
+  "mcpServers": {
+    "shotlog": { "command": "uvx", "args": ["shotlog-mcp"] }
+  }
+}
+```
+
+The first capture needs the **Screen Recording** permission for the app that runs the server (Terminal, iTerm, VS Code, Claude…): *System Settings → Privacy & Security → Screen Recording*.
+
+## Configuration
+
+| Variable | Default | |
+|---|---|---|
+| `SHOTLOG_DIR` | `~/shotlog` | Where screenshots, `manifest.json` and `report.md` are saved. |
+
+Use one folder per project: `claude mcp add shotlog -e SHOTLOG_DIR=~/lab3/shots -- uvx shotlog-mcp`
+
+### Remote screenshots (optional)
+
+To use `pull_remote_screenshots`, the other machine needs an SSH server (on Windows: *Settings → Optional features → OpenSSH Server*) and key-based login from your Mac, so that no password is asked for.
+
+## Report to PDF
+
+```bash
+cd ~/shotlog && pandoc report.md -o report.pdf
+```
+
+## Development
+
+```bash
+uv run --group dev pytest
+```
+
+## License
+
+MIT

shotlog_mcp-0.1.0/demo/demo.py

@@ -0,0 +1,31 @@
+"""Drives the real shotlog server over MCP, the way an AI client would. Used to record the README GIF."""
+import asyncio, json, os, sys, time
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+C, D, R = "\033[36m", "\033[2m", "\033[0m"
+
+def say(text):
+    print(f"\n{C}> {text}{R}"); time.sleep(0.8)
+
+def show(result, keys=None):
+    data = json.loads(result.content[0].text)
+    if keys:
+        data = {k: data[k] for k in keys if k in data}
+    print(D + json.dumps(data, ensure_ascii=False, indent=2) + R); time.sleep(1.6)
+
+async def main():
+    params = StdioServerParameters(command="uv", args=["run", "-q", "shotlog-mcp"],
+                                   env={**os.environ}, cwd=sys.argv[1])
+    async with stdio_client(params, errlog=open(os.devnull, "w")) as (r, w):
+        async with ClientSession(r, w) as s:
+            await s.initialize()
+            say('save_screenshot(name="step1_ssh_version", app="Terminal", title_contains="shotlog-demo", ...)')
+            show(await s.call_tool("save_screenshot", {
+                "name": "step1_ssh_version", "app": "Terminal", "title_contains": "shotlog-demo",
+                "activity": "Step 1 - Check the SSH client", "command": "ssh -V",
+                "result": "OpenSSH client is installed"}), ["file", "source", "activity", "command", "result"])
+            say("export_report(title=\"OS Lab - SSH\")")
+            show(await s.call_tool("export_report", {"title": "OS Lab - SSH"}))
+
+asyncio.run(main())

shotlog_mcp-0.1.0/demo/demo.tape

@@ -0,0 +1,21 @@
+Output docs/demo-terminal.gif
+# Recreate the README GIF: run demo/window.sh in a separate Terminal window, then `vhs demo/demo.tape`.
+Set Shell zsh
+Set FontSize 15
+Set Width 1100
+Set Height 560
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 35ms
+Hide
+Type "setopt interactivecomments; export SHOTLOG_DIR=~/os-lab PS1='$ ' && cd ~/shotlog-mcp && clear"
+Enter
+Show
+Type "# What your AI assistant does when you ask: 'screenshot the terminal as step 1'"
+Enter
+Sleep 600ms
+Type "uv run -q python demo/demo.py ."
+Enter
+Sleep 12s
+Type "ls $SHOTLOG_DIR"
+Enter
+Sleep 3s

shotlog_mcp-0.1.0/demo/window.sh

@@ -0,0 +1,7 @@
+#!/bin/zsh
+printf '\e]0;shotlog-demo\a'
+sleep 2; clear
+echo '$ ssh -V'; ssh -V 2>&1
+echo; echo '$ uname -sm'; uname -sm
+echo; echo '$ which sshd scp'; which sshd scp
+exec sleep 600

shotlog_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "shotlog-mcp"
+version = "0.1.0"
+description = "MCP server that captures macOS windows into a numbered, captioned evidence log for lab reports, QA and docs."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Marlon Trujillo Jaramillo" }]
+requires-python = ">=3.11"
+keywords = ["mcp", "model-context-protocol", "screenshot", "macos", "claude", "documentation", "qa"]
+classifiers = [
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Graphics :: Capture :: Screen Capture",
+]
+dependencies = [
+  "mcp>=1.2,<2",
+  "pyobjc-framework-Quartz; sys_platform == 'darwin'",
+]
+
+[project.scripts]
+shotlog-mcp = "shotlog_mcp.server:main"
+
+[project.urls]
+Repository = "https://github.com/Marlon-Trujillo-Jaramillo/shotlog-mcp"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"

shotlog_mcp-0.1.0/server.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.Marlon-Trujillo-Jaramillo/shotlog-mcp",
+  "title": "shotlog",
+  "description": "Capture macOS windows into a numbered, captioned screenshot log and export it as a report.",
+  "repository": {
+    "url": "https://github.com/Marlon-Trujillo-Jaramillo/shotlog-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "shotlog-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "SHOTLOG_DIR",
+          "description": "Folder for screenshots, manifest.json and report.md (default: ~/shotlog)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

shotlog_mcp-0.1.0/src/shotlog_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

shotlog_mcp-0.1.0/src/shotlog_mcp/server.py

@@ -0,0 +1,148 @@
+"""shotlog MCP server: capture macOS windows into a numbered, captioned evidence log."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+from .store import Store
+
+mcp = FastMCP("shotlog")
+store = Store()
+
+
+def _windows() -> list[dict]:
+    import Quartz  # macOS only; imported lazily so the store stays portable
+
+    opts = Quartz.kCGWindowListOptionOnScreenOnly | Quartz.kCGWindowListExcludeDesktopElements
+    out = []
+    for w in Quartz.CGWindowListCopyWindowInfo(opts, Quartz.kCGNullWindowID) or []:
+        if w.get("kCGWindowLayer", 1) != 0:
+            continue
+        b = w.get("kCGWindowBounds", {})
+        if b.get("Width", 0) < 200 or b.get("Height", 0) < 150:
+            continue
+        out.append({
+            "id": int(w["kCGWindowNumber"]),
+            "app": w.get("kCGWindowOwnerName", ""),
+            "title": w.get("kCGWindowName", "") or "",
+            "size": f"{int(b['Width'])}x{int(b['Height'])}",
+        })
+    return out  # front-most first
+
+
+@mcp.tool()
+def list_windows() -> list[dict]:
+    """List visible windows (id, app, title, size). The first one is the front-most."""
+    return _windows()
+
+
+@mcp.tool()
+def save_screenshot(
+    name: str,
+    app: str = "",
+    title_contains: str = "",
+    activity: str = "",
+    command: str = "",
+    result: str = "",
+) -> dict:
+    """Capture ONE macOS window and save it numbered in the shotlog folder.
+
+    - name: short slug, e.g. "step1_install".
+    - app / title_contains: pick the window (e.g. app="Terminal"). Empty = front-most window.
+    - activity / command / result: caption stored in the manifest and used by export_report.
+    """
+    wins = _windows()
+    if app:
+        wins = [w for w in wins if app.lower() in w["app"].lower()]
+    if title_contains:
+        wins = [w for w in wins if title_contains.lower() in w["title"].lower()]
+    if not wins:
+        return {"error": "Window not found. Call list_windows to see what is available."}
+    win = wins[0]
+    path = store.next_path(name)
+    r = subprocess.run(
+        ["screencapture", "-x", "-o", f"-l{win['id']}", str(path)],
+        capture_output=True, text=True,
+    )
+    if r.returncode != 0 or not path.exists() or path.stat().st_size == 0:
+        return {
+            "error": "screencapture failed. Grant 'Screen Recording' permission to your terminal/"
+                     "MCP host in System Settings > Privacy & Security.",
+            "detail": r.stderr.strip(),
+        }
+    entry = store.register(path, f"mac:{win['app']} — {win['title']}", activity, command, result)
+    return {"path": str(path), **entry}
+
+
+@mcp.tool()
+def pull_remote_screenshots(
+    host: str,
+    user: str,
+    remote_dir: str = "Pictures/Screenshots",
+    prefix: str = "remote",
+) -> dict:
+    """Fetch new PNG screenshots from another machine over SCP (e.g. a Windows laptop where
+    Win+PrtScn saves to Pictures\\Screenshots) and add them to the log.
+    Requires an SSH server on that machine and key-based auth (no password prompt)."""
+    tmp = store.base / "_remote_tmp"
+    tmp.mkdir(exist_ok=True)
+    r = subprocess.run(
+        ["scp", "-p", "-o", "BatchMode=yes", "-o", "ConnectTimeout=8",
+         f"{user}@{host}:{remote_dir}/*.png", str(tmp)],
+        capture_output=True, text=True,
+    )
+    if r.returncode != 0:
+        for f in tmp.glob("*.png"):
+            f.unlink()
+        if "No such file" in r.stderr or "no matches" in r.stderr.lower():
+            return {"new": [], "total": 0, "note": f"No PNG files in {remote_dir}."}
+        return {"error": "scp failed", "detail": r.stderr.strip()}
+
+    known = {(e.get("source"), e.get("original"), e.get("original_size"))
+             for e in store.load()}
+    source = f"remote:{host}"
+    new = []
+    for f in sorted(tmp.glob("*.png"), key=lambda p: p.stat().st_mtime):
+        size = str(f.stat().st_size)
+        if (source, f.name, size) in known:
+            f.unlink()
+            continue
+        dest = store.next_path(f"{prefix}_{f.stem}")
+        f.rename(dest)
+        store.register(dest, source, original=f.name, original_size=size)
+        new.append(dest.name)
+    return {"new": new, "total": len(new)}
+
+
+@mcp.tool()
+def update_caption(file: str, activity: str = "", command: str = "", result: str = "") -> dict:
+    """Fill in or fix the caption (activity, command, result) of a saved screenshot."""
+    entry = store.update(file, activity=activity, command=command, result=result)
+    return entry or {"error": f"{file} is not in the manifest"}
+
+
+@mcp.tool()
+def list_screenshots() -> list[dict]:
+    """List every logged screenshot with its caption, in order."""
+    return store.load()
+
+
+@mcp.tool()
+def export_report(title: str = "Screenshots") -> dict:
+    """Write report.md in the shotlog folder: every screenshot with its caption, in order.
+    Convert it to PDF/DOCX with any tool (e.g. pandoc)."""
+    return {"path": str(store.export_markdown(title))}
+
+
+def main() -> None:
+    if sys.platform != "darwin":
+        sys.exit("shotlog-mcp captures windows with macOS APIs and only runs on macOS.")
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()