suppa-mcp 1.0.0__tar.gz

suppa_mcp-1.0.0/.env.example

@@ -0,0 +1,26 @@
+# ── Suppa 2.0 (target platform) ──────────────────────────────────────────────
+# Optional default tenant. A user JWT (full access incl. Tasks) or an API key.
+# For multi-tenant use you can leave SUPPA_API_KEY empty and authenticate per
+# tenant at runtime (suppa_login) — tokens are stored in the OS keychain.
+SUPPA_API_KEY=your-suppa-2.0-token-here
+SUPPA_BASE_URL=https://modern.suppa.me
+SUPPA_LANG=en
+SUPPA_TZ=Europe/Kyiv
+# Entity ID used for file uploads (default 37)
+# SUPPA_TASKS_ENTITY_ID=37
+# Where the tenant registry (tenants.json) is stored (default: ~/.suppa-mcp)
+# SUPPA_MCP_HOME=
+
+# ── Google login (suppa_login) ───────────────────────────────────────────────
+# Shared Google OAuth client for the in-browser login. Defaults to the Suppa
+# web client; override only if your tenants use a different one.
+# SUPPA_GOOGLE_CLIENT_ID=294101885657-…apps.googleusercontent.com
+# Local port for the login page. http://localhost:<port> must be in the Google
+# client's "Authorized JavaScript origins". Default 8765.
+# SUPPA_MCP_LOGIN_PORT=8765
+
+# ── Suppa 1.0 (source platform) — only for the migration connector ───────────
+# Provide one of API key / access token (access token takes priority).
+# SUPPA_V1_BASE_URL=https://sp.modern-expo.com
+# SUPPA_V1_API_KEY=your-suppa-1.0-api-key
+# SUPPA_V1_ACCESS_TOKEN=your-suppa-1.0-access-token

suppa_mcp-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.env
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+*.log

suppa_mcp-1.0.0/CONNECT.md

@@ -0,0 +1,280 @@
+# Connecting the Suppa 2.0 MCP Server to Any Agent
+
+This is a step‑by‑step plan to connect the Suppa 2.0 MCP Server to any
+MCP‑compatible AI agent and use it for day‑to‑day development against the Suppa
+platform.
+
+---
+
+## 1. How it works (architecture)
+
+```mermaid
+flowchart LR
+    A[AI Agent\nClaude / Copilot / Cursor] -- MCP stdio --> B[suppa_mcp server\nruns locally]
+    B -- HTTPS + Bearer token --> C[(Suppa Platform\nmodern.suppa.me)]
+```
+
+- The agent talks to the server over the **MCP stdio transport** — it only sees
+  *tool names and results*, never your credentials.
+- The server reads `SUPPA_API_KEY` from its **local environment** and adds it to
+  the `Authorization` header of each HTTPS request.
+- Because the server runs on your machine, there are no CORS/proxy/sandbox‑domain
+  problems.
+
+**Security boundary:** the API key never leaves your machine and is never placed
+in the model context.
+
+---
+
+## 2. One‑time setup
+
+### 2.1 Prerequisites
+- Python **3.10+** on PATH (`python --version`).
+- A Suppa token. Either:
+  - a **user JWT** (full access incl. Tasks) — copy the `accessToken` cookie from
+    the browser while logged into `modern.suppa.me`, or
+  - an ** API key** (Docs/Entities/Forms/Users).
+
+### 2.2 Install the server
+```bash
+# from a clone of the repo
+cd suppa2.0-mcp-server
+pip install -e .
+
+# …or directly from the repository
+pip install "git+https://git.modern-expo.com/asu/me-development/skills.git#subdirectory=suppa2.0-mcp-server"
+```
+
+### 2.3 Authenticate
+
+There are two ways to provide credentials. **For teams and multiple tenants,
+prefer browser login (A)** — the agent config then holds no secrets and is
+identical for everyone.
+
+#### A. Browser login (recommended, multi-tenant)
+
+Leave `SUPPA_API_KEY` unset. Once connected, ask the agent to **log in**:
+
+- “**Log in to Suppa testing.modern.me**” → runs `suppa_login`, opens a local
+  page, you sign in with Google. Tokens are stored in your **OS keychain** and
+  **refreshed automatically** — you won't log in again until the refresh window
+  lapses (~10 days of inactivity).
+- “**Switch to the prod tenant**” → `suppa_use_tenant`.
+- “**List my Suppa tenants**” → `suppa_list_tenants`.
+
+**One-time admin setup (per Google OAuth client):** add
+`http://localhost:8765` to the client's **Authorized JavaScript origins** in
+Google Cloud (match `SUPPA_MCP_LOGIN_PORT` if you change it). Without this,
+Google Identity Services won't issue a token to the local page.
+
+#### B. Static token (single tenant / CI)
+
+Create a `.env` next to the project (it is git‑ignored), **or** pass the value
+in the agent's `env` block (next section).
+
+```ini
+SUPPA_API_KEY=your-jwt-or-api-key
+SUPPA_BASE_URL=https://modern.suppa.me
+SUPPA_LANG=en
+SUPPA_TZ=Europe/Kyiv
+```
+
+#### Optional: Suppa 1.0 → 2.0 migration connector
+The `suppa_migrate_entities_from_v1` tool reads entity schemas from a **Suppa 1.0**
+backend and recreates them on this Suppa 2.0 platform. Set these extra variables to
+enable it:
+
+```ini
+SUPPA_V1_BASE_URL=https://sp.modern-expo.com
+# provide one of the two (access token takes priority):
+SUPPA_V1_API_KEY=your-suppa-1.0-api-key
+SUPPA_V1_ACCESS_TOKEN=your-suppa-1.0-access-token
+```
+
+The tool is **dry-run by default** — call it with `dry_run=false` only after
+reviewing the printed plan. It migrates custom entities (set `include_builtin=true`
+to include builtin ones) and creates relation fields in a second pass.
+
+**Recommended reviewable workflow** — generate an entity-list file, inspect/edit it,
+then create the entities in 2.0 from that exact file:
+
+1. Export the plan (no writes to 2.0):
+   `suppa_migrate_entities_from_v1(dry_run=true, output_file="migration_plan.json")`
+2. Open `migration_plan.json` and review the `entities` array and `warnings`
+   (unsupported field types, out-of-set relation targets). Edit if needed.
+3. Create everything in 2.0 from the reviewed file:
+   `suppa_migrate_entities_from_v1(dry_run=false, plan_file="migration_plan.json")`
+
+The plan file structure is:
+
+```jsonc
+{
+  "source": "https://sp.modern-expo.com",
+  "target": "https://modern.suppa.me",
+  "entity_count": 2,
+  "warnings": ["Task.weird: unsupported type 'GeoPoint' — skipped"],
+  "entities": [
+    {
+      "name": "Task",
+      "title": "Task",
+      "title_field_name": "subject",          // verified to exist among scalar_fields
+      "scalar_fields":   [{ "name": "subject", "title": "Subject", "type": "text", "required": false }],
+      "enum_fields":     [{ "name": "status", "title": "Status", "type": "enum",
+                            "enum_name": "Task_status", "values": ["Active", "Done"], "required": true }],
+      "relation_fields": [{ "name": "project", "title": "Project", "type": "relation",
+                            "relation_entity": "Project", "required": false }]
+    }
+  ]
+}
+```
+
+
+### 2.4 Smoke test (optional)
+```bash
+python -m suppa_mcp   # should start and wait on stdio (Ctrl+C to exit)
+```
+
+---
+
+## 3. Connect your agent
+
+Every MCP client uses the same launch command:
+`python -m suppa_mcp` with the env var set.
+
+### Claude Desktop
+Edit `claude_desktop_config.json`
+(`%APPDATA%/Claude/` on Windows, `~/Library/Application Support/Claude/` on macOS):
+```json
+{
+  "mcpServers": {
+    "suppa": {
+      "command": "python",
+      "args": ["-m", "suppa_mcp"],
+      "env": { "SUPPA_API_KEY": "your-token-here" }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot agent mode)
+Create `.vscode/mcp.json` in your workspace. Use an **input prompt** so you are
+asked for the token in a **masked modal** — it is stored in VS Code's secret
+storage (OS keychain) and never written to disk or sent to the chat:
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "suppa-token",
+      "description": "Suppa API token (user JWT for full Tasks access)",
+      "password": true
+    }
+  ],
+  "servers": {
+    "suppa": {
+      "command": "python",
+      "args": ["-m", "suppa_mcp"],
+      "env": { "SUPPA_API_KEY": "${input:suppa-token}" }
+    }
+  }
+}
+```
+Start the `suppa` server (or open Copilot Chat **Agent** mode) → VS Code shows the
+masked prompt once → the `suppa_*` tools appear in the tool picker.
+
+### Cursor
+`Settings → MCP → Add new server`:
+```json
+{
+  "suppa": {
+    "command": "python",
+    "args": ["-m", "suppa_mcp"],
+    "env": { "SUPPA_API_KEY": "your-token-here" }
+  }
+}
+```
+
+### Windsurf / any other MCP client
+Add a stdio server with command `python`, args `["-m", "suppa_mcp"]`, and the
+`SUPPA_API_KEY` environment variable. That is all any compliant client needs.
+
+### Claude Code (CLI)
+If this server is delivered as a **plugin**, Claude Code prompts for the token in
+a **masked modal** at enable time (via the plugin's `userConfig`) and stores it
+in your system keychain — no token in chat, no token on disk.
+
+To register the server manually instead, run:
+```bash
+claude mcp add suppa -- python -m suppa_mcp
+```
+Claude Code stores the server config in `~/.claude.json` under your user profile.
+Provide the token via your shell environment (`SUPPA_API_KEY`) so it is not
+written into a shared config file.
+
+Start a new session and verify with `/mcp` — you should see **suppa** with 50 tools listed.
+
+> Never paste real tokens into the chat, into a committed `.env`, or into a
+> shared config. Prefer the masked modal prompt or your own shell environment.
+
+---
+
+## 4. Verify the connection
+
+Ask the agent:
+
+- “**List my Suppa documents.**” → calls `suppa_list_docs`.
+- “**Who am I in Suppa?**” → calls `suppa_get_me` (needs a user JWT).
+- “**List the entities in Suppa.**” → calls `suppa_list_entities`.
+
+If these return data, the connection works.
+
+---
+
+## 5. Using it for development
+
+Typical agent‑driven workflows now available without leaving your editor:
+
+| Goal | Ask the agent… | Tools used |
+|------|----------------|------------|
+| Triage work | “Show my active tasks and overdue ones.” | `suppa_search_tasks` |
+| Create work | “Create a task ‘Fix login bug’ assigned to me, due tomorrow.” | `suppa_create_task` |
+| Collaborate | “Comment on task 931692 and @mention Andrii.” | `suppa_add_comment` |
+| Attach artefacts | “Attach ./build/report.pdf to task 931692.” | `suppa_attach_file` |
+| Write docs | “Add a ‘Release notes’ page to doc 23 and fill it.” | `suppa_create_page`, `suppa_create_blocks` |
+| Inspect schema | “Describe the Tasks entity fields.” | `suppa_describe_entity` |
+| Query data | “Find Applications created this month.” | `suppa_search_records` |
+| Build a form | “Generate a form from the Tasks entity and create it.” | `suppa_generate_form_schema`, `suppa_create_form` |
+
+### Good practices
+- **IDs are explicit.** Tools take numeric IDs; have the agent *search first*
+  (`suppa_search_*` / `suppa_list_*`) then act.
+- **HTML content.** Task/comment descriptions and doc blocks accept HTML; the
+  server wraps plain text automatically.
+- **Dates.** `deadline` accepts `today`, `tomorrow`, `+3d`, `+2h`, `+30m`, or ISO.
+- **Tasks need a user JWT.** Swap `SUPPA_API_KEY` to a user token if task tools
+  return empty.
+- **Reversibility.** Deletes are soft‑deletes; still confirm before bulk changes.
+
+---
+
+## 6. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `SUPPA_API_KEY environment variable is not set` | No token in env/.env | Set it in the agent `env` block |
+| Empty task results | Integrator key, not a user | Use a user JWT |
+| `HTTP 401` | Expired/invalid token | Refresh the token |
+| `HTTP 400 Field … not found` | Wrong field projection | Update the server; report the entity/field |
+| Agent shows no `suppa_*` tools | Server not launched | Check `python -m suppa_mcp` runs and config path is correct |
+
+---
+
+## 7. Updating
+
+```bash
+cd suppa2.0-mcp-server
+git pull
+pip install -e .   # picks up new tools/fixes
+```
+
+Restart the agent (or reload the MCP server) to load changes.

suppa_mcp-1.0.0/LICENSE

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

suppa_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: suppa-mcp
+Version: 1.0.0
+Summary: MCP server for the Suppa platform (modern.suppa.me) — Tasks, Docs, Entities, Forms, with multi-tenant Google auth
+Project-URL: Homepage, https://github.com/Andrii-Herasymchuk/skills
+Project-URL: Repository, https://github.com/Andrii-Herasymchuk/skills
+Author-email: Andrii Herasymchuk <cloud.developers@modern-expo.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-tools,claude,mcp,model-context-protocol,suppa
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: keyring>=24.0.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# Suppa 2.0 MCP Server
+
+MCP (Model Context Protocol) server for the [Suppa platform](https://modern.suppa.me) — provides AI agents with tools to manage Tasks, Docs/Pages, Entities, and Forms.
+
+## Why MCP?
+
+- **API key stays local** — never sent to the AI agent, stored only in `.env`
+- **Works with any MCP client** — Claude Desktop, VS Code Copilot, Cursor, Windsurf, etc.
+- **No CORS/proxy issues** — runs locally, makes direct HTTPS calls to Suppa
+- **50+ tools** covering Tasks, Documents, Entity schema, Forms, and 1.0→2.0 migration
+
+## Quick Start
+
+### 1. Install
+
+**Recommended — zero-install via PyPI.** Point your MCP client at `uvx`
+([uv](https://docs.astral.sh/uv/)); it fetches and runs the latest release on
+demand (the Python equivalent of `npx`), so there's nothing to install or update:
+
+```json
+{ "mcpServers": { "suppa": { "command": "uvx", "args": ["suppa-mcp"] } } }
+```
+
+Or install the command explicitly:
+
+```bash
+uv tool install suppa-mcp       # or: pipx install suppa-mcp  /  pip install suppa-mcp
+```
+
+This provides a `suppa-mcp` command that any MCP client can launch directly.
+
+**From source instead:**
+
+```bash
+# from a local clone
+cd suppa2.0-mcp-server && pip install -e .
+
+# or straight from the repository
+pip install "git+https://git.modern-expo.com/asu/me-development/skills.git#subdirectory=suppa2.0-mcp-server"
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+# Edit .env and set SUPPA_API_KEY
+```
+
+Then verify your token and connectivity without any client:
+
+```bash
+suppa-mcp --check
+# OK: connected to https://modern.suppa.me — 139 entities visible.
+```
+
+### 3. Connect to your AI agent
+
+Ready-to-copy configs are in [`examples/`](examples). Replace `YOUR_TOKEN_HERE`
+with your Suppa token. All clients use the same `suppa-mcp` command.
+
+**Claude Desktop** — merge [`examples/claude_desktop_config.json`](examples/claude_desktop_config.json)
+into `claude_desktop_config.json` (Windows: `%APPDATA%/Claude/`, macOS:
+`~/Library/Application Support/Claude/`):
+```json
+{
+  "mcpServers": {
+    "suppa": {
+      "command": "suppa-mcp",
+      "env": {
+        "SUPPA_API_KEY": "YOUR_TOKEN_HERE",
+        "SUPPA_BASE_URL": "https://modern.suppa.me"
+      }
+    }
+  }
+}
+```
+
+**VS Code Copilot** — already wired in [`.vscode/mcp.json`](../.vscode/mcp.json);
+it prompts for the token in a masked input. Start the `suppa` server from the
+MCP view.
+
+**Cursor / Windsurf / Cline** — use [`examples/cursor_mcp.json`](examples/cursor_mcp.json)
+or [`examples/generic_mcp.json`](examples/generic_mcp.json).
+
+> If a client reports `suppa-mcp` not found, its launcher can't see your Python
+> Scripts dir on PATH. Use the explicit-interpreter fallback
+> [`examples/claude_desktop_config.python-fallback.json`](examples/claude_desktop_config.python-fallback.json)
+> (`command` = full path from `where.exe python`, `args` = `["-m","suppa_mcp"]`,
+> `cwd` = this project).
+
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SUPPA_API_KEY` | (required) | JWT token or API key |
+| `SUPPA_BASE_URL` | `https://modern.suppa.me` | Platform URL |
+| `SUPPA_LANG` | `en` | Language (`en`/`uk`) |
+| `SUPPA_TZ` | `Europe/Kyiv` | Timezone |
+| `SUPPA_TASKS_ENTITY_ID` | `37` | Entity ID for file uploads |
+
+## Available Tools (52 total)
+
+### Tasks (16 tools)
+| Tool | Description |
+|------|-------------|
+| `suppa_get_me` | Current user profile |
+| `suppa_search_tasks` | Search with filters (my, active, overdue, etc.) |
+| `suppa_count_tasks` | Count matching tasks |
+| `suppa_get_task` | Full task details |
+| `suppa_create_task` | Create task |
+| `suppa_update_task` | Update task fields |
+| `suppa_delete_task` | Soft-delete task |
+| `suppa_move_task` | Move to another stage |
+| `suppa_close_task` | Close (completed stage) |
+| `suppa_add_comment` | Comment with @mentions |
+| `suppa_get_comments` | List task comments |
+| `suppa_attach_file` | Upload & attach file |
+| `suppa_list_workflows` | Available workflows |
+| `suppa_list_stages` | Stages in a workflow |
+| `suppa_list_task_types` | Task type options |
+| `suppa_search_users` | Find users by name |
+
+### Docs & Pages (13 tools)
+| Tool | Description |
+|------|-------------|
+| `suppa_list_docs` | List documents |
+| `suppa_get_doc` | Document with page tree |
+| `suppa_create_doc` | Create document |
+| `suppa_update_doc` | Update document |
+| `suppa_delete_doc` | Delete document |
+| `suppa_list_pages` | Pages in a document |
+| `suppa_get_page` | Page metadata |
+| `suppa_create_page` | Create page |
+| `suppa_update_page` | Update page |
+| `suppa_delete_page` | Delete page |
+| `suppa_get_blocks` | Raw block data |
+| `suppa_read_page` | Readable text output |
+| `suppa_create_blocks` | Add blocks to page |
+| `suppa_insert_block` | Insert at position |
+| `suppa_update_block` | Edit block content |
+| `suppa_delete_block` | Remove block |
+| `suppa_reorder_blocks` | Reorder blocks |
+
+### Entity & Schema (8 tools)
+| Tool | Description |
+|------|-------------|
+| `suppa_list_entities` | All entities/tables |
+| `suppa_describe_entity` | Full schema |
+| `suppa_search_records` | Query any entity |
+| `suppa_create_entity` | Create new table |
+| `suppa_add_field` | Add field to entity |
+| `suppa_add_enum_values` | Add enum options |
+| `suppa_list_field_types` | Available types |
+| `suppa_create_record` | Insert record |
+| `suppa_update_record` | Update record |
+| `suppa_delete_record` | Delete record |
+
+### Forms (6 tools)
+| Tool | Description |
+|------|-------------|
+| `suppa_list_forms` | List forms |
+| `suppa_get_form` | Form with schema |
+| `suppa_create_form` | Create form |
+| `suppa_update_form` | Update form |
+| `suppa_generate_form_schema` | Auto-generate from entity |
+| `suppa_add_field_to_form` | Add field to form |
+| `suppa_list_form_field_types` | Field type catalog |
+
+### Migration
+| Tool | Description |
+|------|-------------|
+| `suppa_migrate_entities_from_v1` | Replicate Suppa 1.0 entities/fields into 2.0 (dry-run by default; supports reviewable plan files) |
+
+### System
+| Tool | Description |
+|------|-------------|
+| `suppa_health_check` | Health check for stdio clients (config-only or deep connectivity check) |
+
+## Authentication
+
+The server authenticates with a single bearer token supplied via `SUPPA_API_KEY`:
+
+- **User JWT** (account token, e.g. copied from the browser cookie `accessToken`) —
+  full access to all domains including Tasks and the `$current-user` magic value.
+- **Integrator API key** — works for Docs, Entities, Forms and Users. Task
+  endpoints and `$current-user` may return empty results because they are scoped
+  to a real user. Use a user JWT for Task workflows.
+
+The token is read only from the environment, sent solely in the `Authorization`
+header to `SUPPA_BASE_URL`, and is **never** exposed to the AI agent.
+
+## Development
+
+```bash
+# Run directly (stdio)
+python -m suppa_mcp
+
+# Verify config + connectivity (no client needed)
+python -m suppa_mcp --check
+
+# Test with MCP inspector
+mcp dev src/suppa_mcp/server.py
+```
+
+## Auto-start Claude at login (stdio)
+
+For Claude Desktop / VS Code, stdio is the preferred model: the MCP client
+spawns this server on demand and reconnects automatically.
+
+To make startup reliable, install a login task that runs a preflight health
+check (`suppa-mcp --check`) and then starts Claude if it is not already running.
+
+```powershell
+cd suppa2.0-mcp-server
+./scripts/install-claude-startup.ps1 -Python C:\Python314\python.exe
+```
+
+The installed task (`SuppaClaudeStartup`) runs:
+
+- `scripts/start-claude-with-suppa.ps1` at user logon,
+- connectivity check first (fails fast if token/config is invalid),
+- Claude launch only when check passes.
+
+Manage it:
+
+```powershell
+Start-ScheduledTask -TaskName SuppaClaudeStartup
+Get-ScheduledTask -TaskName SuppaClaudeStartup
+./scripts/uninstall-claude-startup.ps1
+```
+
+## Troubleshooting
+
+**`mcp dev` fails with `spawn uv ENOENT`** — the MCP Inspector launches the server
+with [`uv`](https://github.com/astral-sh/uv). Install it and make sure it is on
+your `PATH`, then **restart VS Code** (so the new `PATH` is picked up):
+
+```powershell
+python -m pip install uv
+# add the user Scripts dir to PATH if `uv --version` is not found, e.g.
+#   %APPDATA%\Python\Python3xx\Scripts
+```
+
+**`ModuleNotFoundError: No module named 'typing_extensions'` (or `suppa_mcp`)
+when running `mcp dev`** — you have **multiple Python versions** and the `mcp`
+launcher belongs to a different interpreter than the one where `pip install -e .`
+ran. Check with:
+
+```powershell
+where.exe python   # interpreter that has suppa_mcp installed
+where.exe mcp      # the CLI's interpreter — must be the same Python
+```
+
+Fix by using one interpreter, ideally a project virtual environment:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -e .
+mcp dev src/suppa_mcp/server.py
+```
+
+> You do **not** need `uv` or `mcp dev` for normal use — MCP clients (VS Code
+> Copilot, Claude, Cursor) launch the server directly via `python -m suppa_mcp`,
+> as configured in `.vscode/mcp.json`. The inspector is only a debugging tool.
+