From 0c181fc385e34cdb82f5861f9d90ecec860d3e3e Mon Sep 17 00:00:00 2001 From: mpmedia Date: Wed, 2 Sep 2026 16:26:19 -0500 Subject: [PATCH] =?UTF-8?q?docs:=20update=20README=20for=20v0.2.1=20?= =?UTF-8?q?=E2=80=94=20mcp<2=20pin,=20hardcoded=20uv=20path,=20new=20Troub?= =?UTF-8?q?leshooting=20rows?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 59efbea..4e87d54 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ Read-only access to MPM's GitLab repositories — Visual Applications, APK Code, RDMC, and Middleware Backend. -**Version:** 0.2.0 +**Version:** 0.2.1 **Author:** Message Point Media **Repo:** https://git.mpm.to/mpm/gitlab-mpm **CoWork Project:** CW-016 — gitlab-mpm @@ -57,7 +57,7 @@ Read-only access to MPM's GitLab repositories — Visual Applications, APK Code, ## Setup Instructions **Prerequisites:** -- CoWork with `uv` available on PATH (standard on MPM macs) +- CoWork with `uv` available (installed via the official `uv` installer, which places it at `~/.local/bin/uv` by default) - A GitLab Personal Access Token with `read_api` scope **Step-by-step:** @@ -74,9 +74,13 @@ GitLab → User Settings → Access Tokens → New token → scope: `read_api` **Token rotation:** Run `setup_credentials("")` in any CoWork session — Keychain overwrites the old value automatically. No reinstall needed. +**Installing on a new machine (important):** +`.mcp.json` hardcodes an absolute path to `uv` (`/Users/bryangilliom/.local/bin/uv`) rather than relying on `uv` resolving via `$PATH`. This is deliberate — see the Troubleshooting entry below — but it means the path is specific to the machine it was configured on. Installing for another team member (e.g. Jason) on a different Mac requires updating the `command` field in `.mcp.json` to that machine's real `uv` path (find it with `command -v uv` in a terminal on that machine) before packaging/installing the plugin there. + ### Setup Checklist - [ ] Plugin installed in CoWork - [ ] CoWork restarted +- [ ] `command` in `.mcp.json` points at `uv`'s real path on this machine - [ ] `setup_credentials` run with valid PAT - [ ] `check_credentials` returns authenticated username - [ ] Test query succeeds (e.g. list group projects for `mpmedia-andriod`) @@ -92,7 +96,7 @@ Run `setup_credentials("")` in any CoWork session — Keychain overwrit | Transport | stdio (bundled Python MCP server) | | Auth method | PAT via macOS Keychain (service: `mpm-gitlab`) | | MCP server name | `gitlab-mpm` | -| Runtime | `uv run --with mcp[cli] --with httpx --with keyring` | +| Runtime | `uv run --with "mcp[cli]<2" --with httpx --with keyring` (see Troubleshooting — `mcp[cli]` must stay pinned below 2.0) | | PAT scope required | `read_api` | --- @@ -112,7 +116,7 @@ Group `mpmedia-andriod` contains APK code. Group `mpmedia-transit-apps` contains ## Requirements - `uv` (Python package runner) — standard on MPM macs -- `mcp[cli]`, `httpx`, `keyring` — fetched automatically by `uv run` on first use +- `mcp[cli]<2`, `httpx`, `keyring` — fetched automatically by `uv run` on first use. **`mcp[cli]` must stay pinned below version 2.0** — see Troubleshooting. - GitLab PAT with `read_api` scope — generated in GitLab user settings --- @@ -121,7 +125,10 @@ Group `mpmedia-andriod` contains APK code. Group `mpmedia-transit-apps` contains | Symptom | Fix | |---|---| -| Tools not appearing after install | Restart CoWork; `uv` must be on PATH | +| Tools never appear after install, no error shown anywhere | The MCP server is crashing silently on launch before the handshake completes. Manually run the exact command from `.mcp.json`'s `command`/`args` in a terminal to see the real traceback — a permission dialog firing does NOT mean the process actually started. | +| Traceback: `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | `mcp` released a breaking v2.x that renamed `FastMCP` to `MCPServer`. `gitlab_mcp.py` is written against the v1 API. Fixed in v0.2.1 by pinning `--with "mcp[cli]<2"` in `.mcp.json`. If this recurs, confirm the pin is still present — `uv run --with` re-resolves on every launch and will happily grab a new v2.x release if unpinned. | +| Permission dialog fires on plugin update/install, but server still never connects | The dialog only grants the *capability* to run local MCP servers — it is not confirmation the process launched successfully. Check the two rows above. | +| `uv` command fails to resolve / server never launches even though `uv --version` works in Terminal | GUI-launched apps on macOS (including Claude Desktop) do not inherit the PATH additions that shell startup files (`.zshrc`/`.zprofile`) make for interactive shells. `.mcp.json` hardcodes `uv`'s absolute path for this reason. If `uv` was reinstalled or moved, update the `command` field to match `command -v uv`'s current output. | | `No GitLab PAT found` error | Run `setup_credentials("")` to store token in Keychain | | `401 Unauthorized` after setup | Token expired or wrong scope — generate new PAT with `read_api`, rotate via `setup_credentials` | | `list_projects` returns wrong repos | Use `list_group_projects("mpmedia-andriod")` etc. to scope to a specific group |