mcp-loom 1.2.0__tar.gz

mcp_loom-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: jdx/mise-action@v2
+
+      - name: Install dependencies
+        run: mise run install
+
+      - name: Lint
+        run: mise run lint
+
+      - name: Format check
+        run: mise run format-check
+
+      - name: Test
+        run: mise run test
+        env:
+          LOOM_COOKIE: test=dummy

mcp_loom-1.2.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: jdx/mise-action@v2
+
+      - name: Install dependencies
+        run: mise run install
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mcp_loom-1.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+.venv/
+auth.json
+.env
+*.har
+.temp/

mcp_loom-1.2.0/.mise.toml

@@ -0,0 +1,46 @@
+[tools]
+python = "3.13"
+uv = "latest"
+
+[env]
+UV_PROJECT_ENVIRONMENT = "{{cwd}}/.venv"
+
+[tasks.install]
+description = "Install dependencies"
+run = "uv sync --all-extras"
+
+[tasks.test]
+description = "Run tests"
+run = "uv run --with pytest pytest tests/ -v"
+
+[tasks.lint]
+description = "Run ruff linter"
+run = "uv run --with ruff ruff check ."
+
+[tasks.format]
+description = "Run ruff formatter"
+run = "uv run --with ruff ruff format ."
+
+[tasks.format-check]
+description = "Check formatting without writing"
+run = "uv run --with ruff ruff format --check ."
+
+[tasks.check]
+description = "Run lint and format check"
+depends = ["lint", "format-check"]
+
+[tasks.install-hooks]
+description = "Install git pre-commit hook"
+run = """
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/sh
+mise run format
+git add -u
+mise run lint && mise run test
+EOF
+chmod +x .git/hooks/pre-commit
+echo "pre-commit hook installed"
+"""
+
+[hooks]
+enter = "[ -f .git/hooks/pre-commit ] || mise run install-hooks"

mcp_loom-1.2.0/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.2.0] - 2026-03-17
+
+### Added
+
+- GitHub Actions CI workflow (lint, format, test) triggered on push and PRs
+- PyPI publish workflow using OIDC trusted publishing, triggered on version tags
+- mise tasks: `install`, `lint`, `format`, `test`, `build`
+- `install-hooks` mise task and `mise enter` hook for automatic pre-commit setup
+
+### Changed
+
+- Renamed PyPI package from `loom-mcp` to `mcp-loom`
+- Pre-commit hook now auto-formats and re-stages files
+
+### Fixed
+
+- Publish workflow permissions include `contents: read` so `actions/checkout` works alongside `id-token: write`
+
+## [1.1.0] - 2026-02-17
+
+### Added
+
+- Optional `save_dir` parameter on all per-video read tools (`get_video`, `get_transcript`, `get_captions`, `get_summary`, `get_chapters`, `get_description`, `get_key_takeaways`, `get_comments`, `get_tasks`, `get_reactions`, `get_tags`, `get_backlinks`, `get_video_details`)
+- When `save_dir` is provided, tool output is saved to `{save_dir}/{video_id}/` with appropriate filenames (e.g. `transcript.txt`, `captions.vtt`, `metadata.json`)
+- `get_video_details` saves each piece individually plus a combined `details.md`
+- Saved file path is returned alongside the content
+
+## [1.0.2] - 2026-02-10
+
+### Added
+
+- `get_space` tool — get details of a space by ID (parallels `get_folder`)
+- `limit` parameter on `search_videos` (default 50, max 200)
+
+### Changed
+
+- `search_videos` now uses the paginated `SearchVideos` endpoint instead of the semantic `Search` endpoint — faster and no longer capped at 10 results
+- Remove unused `fetch_videos_by_id` and `get_all_videos` from client
+
+## [1.0.1] - 2026-02-10
+
+### Fixed
+
+- 401 error message now says to refresh the browser cookie instead of referencing removed `login.js`
+- `.env` and `auth.json` path resolution no longer breaks when installed via `uvx` (gracefully skipped when no local `pyproject.toml` is found)
+- Clear error message when neither `LOOM_COOKIE` nor `LOOM_AUTH_FILE` is set
+
+### Changed
+
+- `get_video_details` now fetches transcript, chapters, summary, comments, and tasks concurrently via `asyncio.gather` instead of sequentially
+- Rewrite README with per-client install instructions, badges, and improved auth docs
+- Add MIT license, CONTRIBUTING.md
+
+## [1.0.0] - 2026-02-10
+
+### Changed
+
+- Restructure to `src/` layout (`src/loom_mcp/server.py`, `src/loom_mcp/client.py`)
+- Move tests to `tests/` directory
+- Add hatchling build-system for proper packaging
+- Resolve `.env`/`auth.json` paths by walking up to `pyproject.toml`
+- Lower `requires-python` from 3.14 to 3.11
+- Remove `.python-version` (redundant with `requires-python`)
+- Simplify README auth docs, drop parent repo references
+- Rename package to `loom-mcp` with console script entry point
+- Switch to `@lifespan` decorator
+- Add `read`/`write` tags and `timeout=30.0` to all tools
+- Use `uvx` entry point in `fastmcp.json`
+
+## [0.1.0] - 2026-02-08
+
+### Added
+
+- FastMCP server exposing 58 tools (29 read, 29 write) for Loom's internal GraphQL API
+- Async Python client using httpx with concurrency limiter (5 concurrent requests)
+- Auth via `LOOM_COOKIE` env var, `LOOM_AUTH_FILE` path, or `auth.json`
+- Auto-load `.env` file for auth config
+- Tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) on all tools
+- Input ID validation via `_id()`/`_ids()` helpers to reject injection-style inputs
+- `LoomAPIError` and `ToolError` for actionable error messages (401, 403, connection errors)
+- Lifespan-managed httpx client with proper cleanup
+- 31 tests covering tool registration, annotations, ID validation, happy paths, and error paths
+- `fastmcp.json` for FastMCP run support
+- Ruff T20 lint rule to ban `print()` in stdio server code

mcp_loom-1.2.0/CLAUDE.md

@@ -0,0 +1,13 @@
+# Project Instructions
+
+## Testing
+
+```sh
+uv run --with pytest pytest tests/ -v
+```
+
+## Releasing
+
+- Tag versions with annotated tags: `git tag -a v1.2.3 -m "v1.2.3"`
+- Do NOT create GitHub releases — tags + CHANGELOG.md is sufficient
+- Bump version in both `pyproject.toml` and `src/loom_mcp/server.py`

mcp_loom-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for your interest in contributing to loom-mcp!
+
+## Getting started
+
+```sh
+git clone git@github.com:karbassi/loom-mcp.git
+cd loom-mcp
+uv sync
+```
+
+## Running tests
+
+```sh
+uv run --with pytest --with anyio pytest tests/ -q
+```
+
+## Linting and formatting
+
+```sh
+uv run --with ruff ruff check src tests
+uv run --with ruff ruff format src tests
+```
+
+## Submitting changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Ensure tests pass and code is formatted
+4. Open a pull request

mcp_loom-1.2.0/LICENSE

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

mcp_loom-1.2.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: mcp-loom
+Version: 1.2.0
+Summary: MCP server for Loom's internal GraphQL API
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastmcp>=3.0.0b2
+Requires-Dist: httpx>=0.28.1

mcp_loom-1.2.0/README.md

@@ -0,0 +1,253 @@
+# Loom MCP Server
+
+[![PyPI](https://img.shields.io/pypi/v/mcp-loom.svg)](https://pypi.org/project/mcp-loom/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+[MCP](https://modelcontextprotocol.io) server exposing 59 tools for Loom's internal GraphQL API. Works with Claude, Cursor, or any MCP-compatible client.
+
+## Features
+
+- List, search, and get detailed metadata for Loom videos
+- Read transcripts, captions, AI summaries, chapters, and key takeaways
+- Save any fetched content to disk on demand via `save_dir` parameter
+- Manage comments, tasks, reactions, and tags
+- Organize with folders, spaces, and watch lists
+- Update video settings, share to spaces, and more
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) package manager
+
+## Setup
+
+### Authentication
+
+> [!IMPORTANT]
+> This server uses Loom's internal GraphQL API via a browser session cookie. There is no official API key — you must grab the cookie from your browser.
+
+1. Open [loom.com](https://www.loom.com) in your browser
+2. Open DevTools (F12) → Application → Cookies → `https://www.loom.com`
+3. Copy the **value** of the `connect.sid` cookie (starts with `s%3A...`)
+4. Paste it as `LOOM_COOKIE` in your MCP client config below, prefixed with `connect.sid=`
+
+The cookie lasts about 30 days. See [Troubleshooting](#troubleshooting) if you get auth errors.
+
+### Installation
+
+Pick your MCP client below for the appropriate config. Each uses `uvx` to install and run from PyPI — no clone needed.
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "loom": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/karbassi/loom-mcp.git", "loom-mcp"],
+      "env": {
+        "LOOM_COOKIE": "connect.sid=s%3A..."
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```sh
+claude mcp add loom -- uvx --from mcp-loom loom-mcp
+```
+
+Then set the env var in your shell or `.env`:
+
+```sh
+export LOOM_COOKIE="connect.sid=s%3A..."
+```
+
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "loom": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/karbassi/loom-mcp.git", "loom-mcp"],
+      "env": {
+        "LOOM_COOKIE": "connect.sid=s%3A..."
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>VS Code</b></summary>
+
+Add to your VS Code settings (`.vscode/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "loom": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/karbassi/loom-mcp.git", "loom-mcp"],
+      "env": {
+        "LOOM_COOKIE": "connect.sid=s%3A..."
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Local clone</b></summary>
+
+```sh
+git clone git@github.com:karbassi/loom-mcp.git
+cd loom-mcp
+uv sync
+uv run loom-mcp
+```
+
+Or reference it from any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "loom": {
+      "type": "stdio",
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/loom-mcp", "loom-mcp"],
+      "env": {
+        "LOOM_COOKIE": "connect.sid=s%3A..."
+      }
+    }
+  }
+}
+```
+
+</details>
+
+## Tools
+
+### Read (30 tools)
+
+Tools marked with **Save** accept an optional `save_dir` parameter — see [Saving to disk](#saving-to-disk).
+
+| Tool | Description | Save |
+|---|---|:---:|
+| `list_videos` | List your videos, sorted by most recent | |
+| `search_videos` | AI-powered semantic search | |
+| `get_video` | Video metadata (name, duration, owner, views) | `metadata.json` |
+| `get_transcript` | Full transcript with timestamps and speakers | `transcript.txt` |
+| `get_captions` | WebVTT captions with start+end timestamps per cue | `captions.vtt` |
+| `get_summary` | AI-generated summary | `summary.txt` |
+| `get_chapters` | AI-generated chapters | `chapters.txt` |
+| `get_description` | AI-generated detailed description with timestamped sections | `description.txt` |
+| `get_key_takeaways` | AI-generated key takeaways | `takeaways.txt` |
+| `get_comments` | Comments and replies | `comments.txt` |
+| `get_tasks` | AI-generated action items | `tasks.txt` |
+| `get_reactions` | Emoji reactions | `reactions.txt` |
+| `get_tags` | Video tags | `tags.txt` |
+| `get_backlinks` | External references (where the video is shared/embedded) | `backlinks.txt` |
+| `get_meeting_notes` | Confluence meeting notes URL | |
+| `get_confluence_pages` | Linked Confluence pages | |
+| `get_download_url` | Signed MP4 download URL | |
+| `get_video_details` | All-in-one: metadata + transcript + chapters + summary + comments + tasks | `details.md` + all above |
+| `list_folders` | List your folders | |
+| `list_spaces` | List your workspaces | |
+| `get_space` | Space details (name, privacy, primary) | |
+| `search_folders` | Search folders by name | |
+| `get_folder` | Folder details | |
+| `get_last_watch_time` | Last timestamp where you stopped watching | |
+| `get_watch_later_count` | Number of videos in your Watch Later list | |
+| `get_total_videos_count` | Total videos created by a user | |
+| `get_frequent_reactions` | Your most-used emoji reaction types | |
+| `get_comment_reactions` | Emoji reactions on a specific comment | |
+| `get_user` | User profile by ID (name, email, company, avatar) | |
+| `search_workspace_tags` | Search tags in your workspace | |
+
+### Write (29 tools)
+
+> [!NOTE]
+> Write tools modify your Loom data. Destructive actions (delete, archive, move) cannot always be undone.
+
+| Tool | Description |
+|---|---|
+| `update_video_name` | Rename a video |
+| `update_video_description` | Update video description |
+| `update_video_settings` | Update video settings (downloads, comments, etc.) |
+| `create_comment` | Post a comment (with optional timestamp) |
+| `edit_comment` | Edit an existing comment |
+| `delete_comment` | Delete a comment |
+| `create_task` | Create an action item on a video |
+| `update_task` | Update the content of an action item |
+| `delete_task` | Delete an action item |
+| `approve_task` | Mark a task as approved |
+| `respond_to_task` | Respond to a task |
+| `add_reaction` | Add an emoji reaction at a timestamp |
+| `delete_reaction` | Delete a reaction |
+| `add_comment_reaction` | React to a comment with an emoji |
+| `toggle_following` | Follow/unfollow a video |
+| `toggle_following_tag` | Follow/unfollow a workspace tag |
+| `archive_videos` | Archive or unarchive videos |
+| `duplicate_video` | Duplicate a video |
+| `delete_video` | Permanently delete a video |
+| `recover_video` | Recover a deleted video from trash |
+| `pin_video` | Pin or unpin a video in your library |
+| `add_to_watch_later` | Add to Watch Later list |
+| `remove_from_watch_later` | Remove from Watch Later list |
+| `create_folder` | Create a new folder |
+| `rename_folder` | Rename a folder |
+| `delete_folders` | Delete folders |
+| `move_videos` | Move videos to a different folder |
+| `move_folders` | Move folders into a different parent folder |
+| `share_videos_to_spaces` | Share videos to one or more spaces |
+
+## Saving to disk
+
+Most per-video read tools accept an optional `save_dir` parameter. When provided, the tool saves its output to `{save_dir}/{video_id}/` and returns the file path alongside the content. When omitted, nothing is saved.
+
+Just ask naturally — *"get the details from my last meeting and save them to the `ask` directory"* — and the LLM will pass `save_dir="ask"` to the tool.
+
+`get_video_details` saves each piece individually (`metadata.json`, `transcript.txt`, `summary.txt`, etc.) plus a combined `details.md`.
+
+## Troubleshooting
+
+### Auth errors
+
+If you get auth errors, your `connect.sid` cookie has expired (~30 days). Grab a fresh one from your browser using the steps in [Authentication](#authentication).
+
+### Debugging with MCP Inspector
+
+```sh
+npx @modelcontextprotocol/inspector uvx --from mcp-loom loom-mcp
+```
+
+## Contributing
+
+Issues and pull requests are welcome on [GitHub](https://github.com/karbassi/loom-mcp).
+
+## License
+
+[MIT](LICENSE)

mcp_loom-1.2.0/fastmcp.json

@@ -0,0 +1,11 @@
+{
+  "name": "Loom",
+  "description": "Access Loom videos, transcripts, summaries, and comments via Loom's internal GraphQL API.",
+  "mcpServers": {
+    "loom": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/karbassi/loom-mcp.git", "loom-mcp"]
+    }
+  }
+}

mcp_loom-1.2.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "mcp-loom"
+version = "1.2.0"
+description = "MCP server for Loom's internal GraphQL API"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "fastmcp>=3.0.0b2",
+    "httpx>=0.28.1",
+]
+
+[project.scripts]
+loom-mcp = "loom_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loom_mcp"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.ruff.lint]
+select = ["T20"]