letterbox-buddy 0.1.0__tar.gz

letterbox_buddy-0.1.0/.env.example

@@ -0,0 +1,6 @@
+# Get a free API key at https://www.themoviedb.org/settings/api
+TMDB_API_KEY=your_tmdb_api_key_here
+
+# Optional: override where the SQLite database file lives.
+# Defaults to ~/.local/share/letterbox-buddy/db.sqlite3 if not set.
+# LETTERBOX_DB_PATH=/custom/path/to/db.sqlite3

letterbox_buddy-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.env
+__pycache__/
+*.pyc
+*.db
+*.sqlite3
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.DS_Store

letterbox_buddy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alpondr
+
+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.

letterbox_buddy-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: letterbox-buddy
+Version: 0.1.0
+Summary: An MCP server that turns your rough movie notes into polished reviews and tracks your watch history
+Project-URL: Homepage, https://github.com/alpondr/letterbox-buddy-mcp
+Project-URL: Repository, https://github.com/alpondr/letterbox-buddy-mcp
+Author: alpondr
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,letterboxd,mcp,model-context-protocol,movies
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Description-Content-Type: text/markdown
+
+# letterbox-buddy
+
+An MCP server for people who watch a lot of movies and can never be bothered to write a proper review right after.
+
+The idea is simple: you just tell Claude (through Claude Desktop) something like *"watched Fargo tonight, the dialogue was great but it dragged in the middle"*, and it turns that into an actual review, saves it with a rating, pulls the director/genre/year from TMDB automatically, and can spit out Letterboxd-ready text whenever you want it. It also remembers your whole watch history, so you can ask it things like "what have I watched by the Coen brothers" or "what should I watch next based on what I've been into lately."
+
+This is a personal tool I built mainly to learn the MCP protocol by actually building something with it, not to ship a polished product. It works and I use it, but treat it like a working prototype, not battle-tested software.
+
+## What it actually does
+
+1. You write a rough note about a movie you watched, in your own words, whatever comes to mind.
+2. Claude (the one you're already chatting with in Claude Desktop) turns that into a polished review and asks you for a rating.
+3. The server looks the movie up on TMDB, grabs the director/genres/year, and stores everything in a local SQLite database.
+4. Later, you can ask for your watch history, stats on directors/genres you've been watching a lot, or recommendations based on your habits.
+5. When you're ready to log it on Letterboxd, ask for the formatted text and paste it in yourself.
+
+No accounts, no cloud database, no automatic posting anywhere. It's just you, Claude, and a `.sqlite3` file on your machine.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_movie` | Searches TMDB by title, returns candidates so Claude can ask "which one did you mean?" if there are several. |
+| `log_movie_note` | Saves a movie + your raw note + rating (0.5-5 stars, Letterboxd style). Fetches director/genres/year from TMDB the first time a movie shows up. |
+| `get_watch_history` | Lists what you've logged, filterable by director, genre, or date range. |
+| `get_director_stats` | How many times you've watched each director, average rating, which titles. |
+| `get_recommendations` | Returns raw data only - your most-watched director/genre plus movies of theirs you haven't logged yet. No opinions baked in, that's Claude's job. |
+| `generate_letterboxd_text` | Saves the polished review text and hands back a plain, copy-paste-ready version (no title/year/rating, Letterboxd shows those itself). |
+
+## Setup
+
+### 1. Get a TMDB API key
+
+Free, just needs an account: https://www.themoviedb.org/settings/api
+
+### 2. Clone and install
+
+```bash
+git clone https://github.com/alpondr/letterbox-buddy-mcp.git
+cd letterbox-buddy-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### 3. Add your API key
+
+```bash
+cp .env.example .env
+```
+
+Then open `.env` and paste your TMDB key in.
+
+### 4. Set up the database (optional, happens automatically anyway)
+
+The server creates the SQLite database on first run, at `~/.local/share/letterbox-buddy/db.sqlite3` by default. Want it somewhere else? Set `LETTERBOX_DB_PATH` in your `.env`.
+
+If you want to run the migration manually for whatever reason:
+
+```bash
+python -m letterbox_buddy.db.migrate
+```
+
+### 5. Connect it to Claude Desktop
+
+Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "letterbox-buddy": {
+      "command": "/absolute/path/to/letterbox-buddy-mcp/.venv/bin/python",
+      "args": ["-m", "letterbox_buddy.server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop (fully quit, not just close the window) and you should see the tools show up.
+
+Once this is published to PyPI, this whole setup collapses into just running `uvx letterbox-buddy` - no clone, no venv, nothing to install by hand.
+
+## Notes on design decisions
+
+A few choices here look "wrong" if you're used to bigger projects, so here's the reasoning behind them.
+
+**Why SQLite and no auth.** Single machine, single user, nothing to authenticate against - Postgres and JWT would just be unused infrastructure here.
+
+**Why no separate LLM API.** Claude is already right there doing the conversation, so a second LLM would just duplicate work for no reason. The server stays dumb on purpose - fetch/store/return data, all the thinking happens in the chat.
+
+**Why Letterboxd posting is copy-paste only.** There's no public API for posting on someone's behalf, and I'd rather the last step stay a deliberate human action anyway.
+
+**Why "letterbox" not "letterboxd".** Not affiliated with Letterboxd, didn't want the name to imply a partnership that doesn't exist.
+
+## Known limitations / what this isn't
+
+- Error handling is minimal - happy path only.
+- No TMDB rate-limit handling or caching.
+- Single machine, no sync between devices.
+- No automated tests, everything checked manually.
+- Single-user only, no accounts.
+- Not on PyPI yet, schema may still change.

letterbox_buddy-0.1.0/README.md

@@ -0,0 +1,102 @@
+# letterbox-buddy
+
+An MCP server for people who watch a lot of movies and can never be bothered to write a proper review right after.
+
+The idea is simple: you just tell Claude (through Claude Desktop) something like *"watched Fargo tonight, the dialogue was great but it dragged in the middle"*, and it turns that into an actual review, saves it with a rating, pulls the director/genre/year from TMDB automatically, and can spit out Letterboxd-ready text whenever you want it. It also remembers your whole watch history, so you can ask it things like "what have I watched by the Coen brothers" or "what should I watch next based on what I've been into lately."
+
+This is a personal tool I built mainly to learn the MCP protocol by actually building something with it, not to ship a polished product. It works and I use it, but treat it like a working prototype, not battle-tested software.
+
+## What it actually does
+
+1. You write a rough note about a movie you watched, in your own words, whatever comes to mind.
+2. Claude (the one you're already chatting with in Claude Desktop) turns that into a polished review and asks you for a rating.
+3. The server looks the movie up on TMDB, grabs the director/genres/year, and stores everything in a local SQLite database.
+4. Later, you can ask for your watch history, stats on directors/genres you've been watching a lot, or recommendations based on your habits.
+5. When you're ready to log it on Letterboxd, ask for the formatted text and paste it in yourself.
+
+No accounts, no cloud database, no automatic posting anywhere. It's just you, Claude, and a `.sqlite3` file on your machine.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_movie` | Searches TMDB by title, returns candidates so Claude can ask "which one did you mean?" if there are several. |
+| `log_movie_note` | Saves a movie + your raw note + rating (0.5-5 stars, Letterboxd style). Fetches director/genres/year from TMDB the first time a movie shows up. |
+| `get_watch_history` | Lists what you've logged, filterable by director, genre, or date range. |
+| `get_director_stats` | How many times you've watched each director, average rating, which titles. |
+| `get_recommendations` | Returns raw data only - your most-watched director/genre plus movies of theirs you haven't logged yet. No opinions baked in, that's Claude's job. |
+| `generate_letterboxd_text` | Saves the polished review text and hands back a plain, copy-paste-ready version (no title/year/rating, Letterboxd shows those itself). |
+
+## Setup
+
+### 1. Get a TMDB API key
+
+Free, just needs an account: https://www.themoviedb.org/settings/api
+
+### 2. Clone and install
+
+```bash
+git clone https://github.com/alpondr/letterbox-buddy-mcp.git
+cd letterbox-buddy-mcp
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### 3. Add your API key
+
+```bash
+cp .env.example .env
+```
+
+Then open `.env` and paste your TMDB key in.
+
+### 4. Set up the database (optional, happens automatically anyway)
+
+The server creates the SQLite database on first run, at `~/.local/share/letterbox-buddy/db.sqlite3` by default. Want it somewhere else? Set `LETTERBOX_DB_PATH` in your `.env`.
+
+If you want to run the migration manually for whatever reason:
+
+```bash
+python -m letterbox_buddy.db.migrate
+```
+
+### 5. Connect it to Claude Desktop
+
+Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "letterbox-buddy": {
+      "command": "/absolute/path/to/letterbox-buddy-mcp/.venv/bin/python",
+      "args": ["-m", "letterbox_buddy.server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop (fully quit, not just close the window) and you should see the tools show up.
+
+Once this is published to PyPI, this whole setup collapses into just running `uvx letterbox-buddy` - no clone, no venv, nothing to install by hand.
+
+## Notes on design decisions
+
+A few choices here look "wrong" if you're used to bigger projects, so here's the reasoning behind them.
+
+**Why SQLite and no auth.** Single machine, single user, nothing to authenticate against - Postgres and JWT would just be unused infrastructure here.
+
+**Why no separate LLM API.** Claude is already right there doing the conversation, so a second LLM would just duplicate work for no reason. The server stays dumb on purpose - fetch/store/return data, all the thinking happens in the chat.
+
+**Why Letterboxd posting is copy-paste only.** There's no public API for posting on someone's behalf, and I'd rather the last step stay a deliberate human action anyway.
+
+**Why "letterbox" not "letterboxd".** Not affiliated with Letterboxd, didn't want the name to imply a partnership that doesn't exist.
+
+## Known limitations / what this isn't
+
+- Error handling is minimal - happy path only.
+- No TMDB rate-limit handling or caching.
+- Single machine, no sync between devices.
+- No automated tests, everything checked manually.
+- Single-user only, no accounts.
+- Not on PyPI yet, schema may still change.

letterbox_buddy-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "letterbox-buddy"
+version = "0.1.0"
+description = "An MCP server that turns your rough movie notes into polished reviews and tracks your watch history"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "alpondr" },
+]
+keywords = ["mcp", "model-context-protocol", "letterboxd", "movies", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: End Users/Desktop",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/alpondr/letterbox-buddy-mcp"
+Repository = "https://github.com/alpondr/letterbox-buddy-mcp"
+
+[project.scripts]
+letterbox-buddy = "letterbox_buddy.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/letterbox_buddy"]

letterbox_buddy-0.1.0/src/letterbox_buddy/db/__init__.py

@@ -0,0 +1,18 @@
+from .connection import get_connection, get_db_path
+from .migrate import run_migrations
+from .movies import get_or_create_movie
+from .stats import get_director_stats, get_genre_counts, get_watched_tmdb_ids
+from .watch_logs import add_watch_log, get_watch_history, update_polished_review
+
+__all__ = [
+    "get_connection",
+    "get_db_path",
+    "run_migrations",
+    "get_or_create_movie",
+    "add_watch_log",
+    "get_watch_history",
+    "update_polished_review",
+    "get_director_stats",
+    "get_genre_counts",
+    "get_watched_tmdb_ids",
+]

letterbox_buddy-0.1.0/src/letterbox_buddy/db/connection.py

@@ -0,0 +1,17 @@
+import os
+import sqlite3
+from pathlib import Path
+
+
+def get_db_path() -> Path:
+    override = os.environ.get("LETTERBOX_DB_PATH")
+    path = Path(override).expanduser() if override else Path.home() / ".local" / "share" / "letterbox-buddy" / "db.sqlite3"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_connection() -> sqlite3.Connection:
+    conn = sqlite3.connect(get_db_path())
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.row_factory = sqlite3.Row
+    return conn

letterbox_buddy-0.1.0/src/letterbox_buddy/db/migrate.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from .connection import get_connection, get_db_path
+
+SCHEMA_PATH = Path(__file__).parent / "schema.sql"
+
+
+def run_migrations() -> None:
+    conn = get_connection()
+    try:
+        conn.executescript(SCHEMA_PATH.read_text())
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def main() -> None:
+    run_migrations()
+    print(f"Database ready at {get_db_path()}")
+
+
+if __name__ == "__main__":
+    main()

letterbox_buddy-0.1.0/src/letterbox_buddy/db/movies.py

@@ -0,0 +1,28 @@
+from .connection import get_connection
+
+
+def get_or_create_movie(details: dict) -> int:
+    conn = get_connection()
+    try:
+        row = conn.execute("SELECT id FROM movies WHERE tmdb_id = ?", (details["tmdb_id"],)).fetchone()
+        if row:
+            return row["id"]
+
+        cursor = conn.execute(
+            """
+            INSERT INTO movies (tmdb_id, title, director, year, genres, poster_path)
+            VALUES (?, ?, ?, ?, ?, ?)
+            """,
+            (
+                details["tmdb_id"],
+                details["title"],
+                details.get("director"),
+                details.get("year"),
+                details.get("genres"),
+                details.get("poster_path"),
+            ),
+        )
+        conn.commit()
+        return cursor.lastrowid
+    finally:
+        conn.close()

letterbox_buddy-0.1.0/src/letterbox_buddy/db/schema.sql

@@ -0,0 +1,25 @@
+CREATE TABLE IF NOT EXISTS movies (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tmdb_id INTEGER UNIQUE NOT NULL,
+    title TEXT NOT NULL,
+    director TEXT,
+    year INTEGER,
+    genres TEXT,
+    poster_path TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS watch_logs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    movie_id INTEGER NOT NULL REFERENCES movies(id),
+    watched_date TEXT,
+    raw_note TEXT NOT NULL,
+    polished_review TEXT,
+    rating REAL CHECK (rating IS NULL OR (rating >= 0.5 AND rating <= 5.0)),
+    is_deleted INTEGER NOT NULL DEFAULT 0,
+    deleted_at TEXT,
+    created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_watch_logs_movie_id ON watch_logs(movie_id);
+CREATE INDEX IF NOT EXISTS idx_watch_logs_is_deleted ON watch_logs(is_deleted);

letterbox_buddy-0.1.0/src/letterbox_buddy/db/stats.py

@@ -0,0 +1,66 @@
+from .connection import get_connection
+
+
+def get_director_stats() -> list[dict]:
+    conn = get_connection()
+    try:
+        rows = conn.execute(
+            """
+            SELECT m.director,
+                   COUNT(*) AS watch_count,
+                   AVG(wl.rating) AS avg_rating,
+                   GROUP_CONCAT(m.title, ', ') AS titles
+            FROM watch_logs wl
+            JOIN movies m ON m.id = wl.movie_id
+            WHERE wl.is_deleted = 0 AND m.director IS NOT NULL
+            GROUP BY m.director
+            ORDER BY watch_count DESC
+            """
+        ).fetchall()
+        return [dict(row) for row in rows]
+    finally:
+        conn.close()
+
+
+def get_genre_counts() -> list[dict]:
+    conn = get_connection()
+    try:
+        rows = conn.execute(
+            """
+            SELECT m.genres
+            FROM watch_logs wl
+            JOIN movies m ON m.id = wl.movie_id
+            WHERE wl.is_deleted = 0 AND m.genres IS NOT NULL AND m.genres != ''
+            """
+        ).fetchall()
+    finally:
+        conn.close()
+
+    counts: dict[str, int] = {}
+    for row in rows:
+        for genre in row["genres"].split(", "):
+            genre = genre.strip()
+            if genre:
+                counts[genre] = counts.get(genre, 0) + 1
+
+    return sorted(
+        ({"genre": g, "watch_count": c} for g, c in counts.items()),
+        key=lambda x: x["watch_count"],
+        reverse=True,
+    )
+
+
+def get_watched_tmdb_ids() -> set[int]:
+    conn = get_connection()
+    try:
+        rows = conn.execute(
+            """
+            SELECT DISTINCT m.tmdb_id
+            FROM watch_logs wl
+            JOIN movies m ON m.id = wl.movie_id
+            WHERE wl.is_deleted = 0
+            """
+        ).fetchall()
+        return {row["tmdb_id"] for row in rows}
+    finally:
+        conn.close()

letterbox_buddy-0.1.0/src/letterbox_buddy/db/watch_logs.py

@@ -0,0 +1,65 @@
+from .connection import get_connection
+
+
+def add_watch_log(movie_id: int, raw_note: str, rating: float | None, watched_date: str | None) -> int:
+    conn = get_connection()
+    try:
+        cursor = conn.execute(
+            """
+            INSERT INTO watch_logs (movie_id, watched_date, raw_note, rating)
+            VALUES (?, ?, ?, ?)
+            """,
+            (movie_id, watched_date, raw_note, rating),
+        )
+        conn.commit()
+        return cursor.lastrowid
+    finally:
+        conn.close()
+
+
+def update_polished_review(log_id: int, polished_review: str) -> None:
+    conn = get_connection()
+    try:
+        conn.execute(
+            "UPDATE watch_logs SET polished_review = ? WHERE id = ? AND is_deleted = 0",
+            (polished_review, log_id),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def get_watch_history(
+    director: str | None = None,
+    genre: str | None = None,
+    date_from: str | None = None,
+    date_to: str | None = None,
+) -> list[dict]:
+    conn = get_connection()
+    try:
+        query = """
+            SELECT wl.id, wl.watched_date, wl.raw_note, wl.polished_review, wl.rating,
+                   m.title, m.director, m.year, m.genres
+            FROM watch_logs wl
+            JOIN movies m ON m.id = wl.movie_id
+            WHERE wl.is_deleted = 0
+        """
+        params: list = []
+        if director:
+            query += " AND m.director = ?"
+            params.append(director)
+        if genre:
+            query += " AND m.genres LIKE ?"
+            params.append(f"%{genre}%")
+        if date_from:
+            query += " AND wl.watched_date >= ?"
+            params.append(date_from)
+        if date_to:
+            query += " AND wl.watched_date <= ?"
+            params.append(date_to)
+        query += " ORDER BY wl.watched_date DESC"
+
+        rows = conn.execute(query, params).fetchall()
+        return [dict(row) for row in rows]
+    finally:
+        conn.close()

letterbox_buddy-0.1.0/src/letterbox_buddy/server.py

@@ -0,0 +1,32 @@
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from mcp.server.fastmcp import FastMCP
+
+from letterbox_buddy.db import run_migrations
+from letterbox_buddy.tools import history, letterboxd, movies, recommendations, stats
+
+mcp = FastMCP("letterbox-buddy")
+
+
+@mcp.tool()
+def ping() -> str:
+    """Health check tool. Returns 'pong' if the server is alive."""
+    return "pong"
+
+
+movies.register(mcp)
+history.register(mcp)
+stats.register(mcp)
+recommendations.register(mcp)
+letterboxd.register(mcp)
+
+
+def main() -> None:
+    run_migrations()
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

letterbox_buddy-0.1.0/src/letterbox_buddy/tools/history.py

@@ -0,0 +1,17 @@
+from mcp.server.fastmcp import FastMCP
+
+from letterbox_buddy.db import get_watch_history as query_watch_history
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def get_watch_history(
+        director: str | None = None,
+        genre: str | None = None,
+        date_from: str | None = None,
+        date_to: str | None = None,
+    ) -> list[dict]:
+        """List watch history (soft-deleted entries excluded), optionally
+        filtered by director, genre (substring match), or a watched_date
+        range (YYYY-MM-DD, inclusive on both ends)."""
+        return query_watch_history(director=director, genre=genre, date_from=date_from, date_to=date_to)

letterbox_buddy-0.1.0/src/letterbox_buddy/tools/letterboxd.py

@@ -0,0 +1,15 @@
+from mcp.server.fastmcp import FastMCP
+
+from letterbox_buddy.db import update_polished_review
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def generate_letterboxd_text(log_id: int, polished_review: str) -> str:
+        """Save the polished review for a watch log and return it formatted
+        for pasting straight into Letterboxd's review box. Plain text only
+        - no title, year, or star rating, since Letterboxd already shows
+        those separately when logging a film. Copy-paste, no auto-posting."""
+        text = polished_review.strip()
+        update_polished_review(log_id, text)
+        return text

letterbox_buddy-0.1.0/src/letterbox_buddy/tools/movies.py

@@ -0,0 +1,39 @@
+from mcp.server.fastmcp import FastMCP
+
+from letterbox_buddy.db import add_watch_log, get_or_create_movie
+from letterbox_buddy.utils.tmdb import get_movie_details, search_movies
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    async def search_movie(query: str) -> list[dict]:
+        """Search for a movie on TMDB by title. Returns candidate matches
+        (tmdb_id, title, year, overview, poster_path) so the caller can
+        disambiguate when there's more than one result."""
+        results = await search_movies(query)
+        return [
+            {
+                "tmdb_id": r["id"],
+                "title": r["title"],
+                "year": r["release_date"][:4] if r.get("release_date") else None,
+                "overview": r.get("overview"),
+                "poster_path": r.get("poster_path"),
+            }
+            for r in results[:10]
+        ]
+
+    @mcp.tool()
+    async def log_movie_note(
+        tmdb_id: int,
+        raw_note: str,
+        rating: float | None = None,
+        watched_date: str | None = None,
+    ) -> dict:
+        """Save a watch log entry for a movie identified by its TMDB id.
+        Fetches director/genres/year from TMDB the first time this movie is
+        logged. rating is 0.5-5.0 in Letterboxd star steps. watched_date is
+        an ISO date string (YYYY-MM-DD) if provided."""
+        details = await get_movie_details(tmdb_id)
+        movie_id = get_or_create_movie(details)
+        log_id = add_watch_log(movie_id, raw_note, rating, watched_date)
+        return {"log_id": log_id, "movie": details}

letterbox_buddy-0.1.0/src/letterbox_buddy/tools/recommendations.py

@@ -0,0 +1,38 @@
+from mcp.server.fastmcp import FastMCP
+
+from letterbox_buddy.db import get_director_stats, get_genre_counts, get_watched_tmdb_ids
+from letterbox_buddy.utils.tmdb import discover_by_genre, get_director_filmography, search_person
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    async def get_recommendations() -> dict:
+        """Returns raw data ONLY, no opinions or ranking commentary: the
+        most-watched director and genre from watch history, plus unwatched
+        TMDB movies matching each. The connected assistant is expected to
+        turn this into an actual recommendation."""
+        director_stats = get_director_stats()
+        genre_counts = get_genre_counts()
+        watched_ids = get_watched_tmdb_ids()
+
+        top_director = director_stats[0]["director"] if director_stats else None
+        top_genre = genre_counts[0]["genre"] if genre_counts else None
+
+        unwatched_by_director: list[dict] = []
+        if top_director:
+            person_id = await search_person(top_director)
+            if person_id:
+                filmography = await get_director_filmography(person_id)
+                unwatched_by_director = [m for m in filmography if m["tmdb_id"] not in watched_ids]
+
+        unwatched_by_genre: list[dict] = []
+        if top_genre:
+            candidates = await discover_by_genre(top_genre)
+            unwatched_by_genre = [m for m in candidates if m["tmdb_id"] not in watched_ids]
+
+        return {
+            "top_director": top_director,
+            "top_genre": top_genre,
+            "unwatched_by_director": unwatched_by_director,
+            "unwatched_by_genre": unwatched_by_genre,
+        }

letterbox_buddy-0.1.0/src/letterbox_buddy/tools/stats.py

@@ -0,0 +1,12 @@
+from mcp.server.fastmcp import FastMCP
+
+from letterbox_buddy.db import get_director_stats as query_director_stats
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def get_director_stats() -> list[dict]:
+        """Per-director watch counts, average rating, and watched titles,
+        sorted by watch_count descending. Directors with no logged movies
+        won't appear (soft-deleted entries excluded)."""
+        return query_director_stats()

letterbox_buddy-0.1.0/src/letterbox_buddy/utils/tmdb.py

@@ -0,0 +1,128 @@
+import os
+
+import httpx
+
+TMDB_BASE_URL = "https://api.themoviedb.org/3"
+
+
+class TMDBError(Exception):
+    pass
+
+
+def _get_api_key() -> str:
+    api_key = os.environ.get("TMDB_API_KEY")
+    if not api_key:
+        raise TMDBError("TMDB_API_KEY is not set. Add it to your .env file.")
+    return api_key
+
+
+async def search_movies(query: str) -> list[dict]:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{TMDB_BASE_URL}/search/movie",
+            params={"api_key": _get_api_key(), "query": query, "language": "en-US"},
+        )
+        response.raise_for_status()
+        return response.json()["results"]
+
+
+async def get_movie_details(tmdb_id: int) -> dict:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{TMDB_BASE_URL}/movie/{tmdb_id}",
+            params={
+                "api_key": _get_api_key(),
+                "language": "en-US",
+                "append_to_response": "credits",
+            },
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    director = next(
+        (c["name"] for c in data.get("credits", {}).get("crew", []) if c.get("job") == "Director"),
+        None,
+    )
+    return {
+        "tmdb_id": data["id"],
+        "title": data["title"],
+        "director": director,
+        "year": int(data["release_date"][:4]) if data.get("release_date") else None,
+        "genres": ", ".join(g["name"] for g in data.get("genres", [])),
+        "poster_path": data.get("poster_path"),
+    }
+
+
+async def search_person(name: str) -> int | None:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{TMDB_BASE_URL}/search/person",
+            params={"api_key": _get_api_key(), "query": name},
+        )
+        response.raise_for_status()
+        results = response.json()["results"]
+        return results[0]["id"] if results else None
+
+
+async def get_director_filmography(person_id: int) -> list[dict]:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{TMDB_BASE_URL}/person/{person_id}/movie_credits",
+            params={"api_key": _get_api_key(), "language": "en-US"},
+        )
+        response.raise_for_status()
+        data = response.json()
+
+    return [
+        {
+            "tmdb_id": c["id"],
+            "title": c["title"],
+            "year": c["release_date"][:4] if c.get("release_date") else None,
+        }
+        for c in data.get("crew", [])
+        if c.get("job") == "Director"
+    ]
+
+
+_genre_name_to_id: dict[str, int] | None = None
+
+
+async def _get_genre_id(genre_name: str) -> int | None:
+    global _genre_name_to_id
+    if _genre_name_to_id is None:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                f"{TMDB_BASE_URL}/genre/movie/list",
+                params={"api_key": _get_api_key(), "language": "en-US"},
+            )
+            response.raise_for_status()
+            _genre_name_to_id = {g["name"]: g["id"] for g in response.json()["genres"]}
+    return _genre_name_to_id.get(genre_name)
+
+
+async def discover_by_genre(genre_name: str, limit: int = 10) -> list[dict]:
+    genre_id = await _get_genre_id(genre_name)
+    if genre_id is None:
+        return []
+
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"{TMDB_BASE_URL}/discover/movie",
+            params={
+                "api_key": _get_api_key(),
+                "with_genres": genre_id,
+                "sort_by": "popularity.desc",
+                "language": "en-US",
+            },
+        )
+        response.raise_for_status()
+        results = response.json()["results"]
+
+    return [
+        {
+            "tmdb_id": r["id"],
+            "title": r["title"],
+            "year": r["release_date"][:4] if r.get("release_date") else None,
+        }
+        for r in results[:limit]
+    ]