mpm/gitlab-mpm
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c181fc385e34cdb82f5861f9d90ecec860d3e3e
gitlab-mpm/README.md
T

8.3 KiB
Raw Blame History

gitlab-mpm

Read-only access to MPM's GitLab repositories — Visual Applications, APK Code, RDMC, and Middleware Backend.

Version: 0.2.1 Author: Message Point Media Repo: https://git.mpm.to/mpm/gitlab-mpm CoWork Project: CW-016 — gitlab-mpm

Overview

gitlab-mpm is a CoWork plugin that connects Claude to MPM's private GitLab account at gitlab.com, providing read-only code research capability across all MPM repositories. The plugin bundles a Python MCP server that wraps the GitLab REST API, using uv for zero-install execution. Authentication uses a Personal Access Token (PAT) stored securely in macOS Keychain — no credentials are embedded in the plugin files. The plugin scopes all project listings to MPM-member repositories only, and supports browsing, searching, and reading code across five GitLab groups covering APK, Visual Applications, RDMC backend, middleware, and web/GTFS projects.

Skills

Skill What It Does
gitlab Instructs Claude to use GitLab tools when the user asks about code in the MPM codebase. Triggers on: "the codebase", "the repo", "RDMC code", "middleware code", "APK code", "Visual Applications", "how does X work in the code", "find where Y is defined", "search the repo for", "look at the source", "what does this function do", "show me the code for", "check the backend", "how is X implemented", "GitLab", "the repository", "our codebase", "the source". Also triggers on credential setup: "setup gitlab credentials", "store my token", "update my PAT", "rotate my gitlab token".

MPM Repository Groups

Group Contents
mpmedia-andriod APK code: launchers, TDM apps, ITxPT, RDMC monitoring, IoT
mpmedia-transit-apps Visual Applications (HTML): wayside and on-vehicle display apps, plugins
MPMedia Middleware, agency GTFS projects, backend tools
mpm-backend-refactors RDMC-Mono, shared backend services
mpmprojects Web apps, GTFS integrations, customer-specific projects

Tools Reference

Tool Purpose
setup_credentials Store GitLab PAT in macOS Keychain (run once after install or on token rotation)
check_credentials Verify that a PAT is stored and that it successfully authenticates
clear_credentials Remove the stored PAT from Keychain
list_projects List all repos the token has membership access to (MPM private repos)
list_group_projects List all repos in a specific GitLab group (e.g. mpmedia-andriod)
get_project Get details for a specific project by ID or path
list_repository_tree Browse files and directories in a repo
get_file_contents Read a specific file from a repo
search_code Full-text search for code within a specific project
list_branches List branches for a project
list_commits List recent commits, optionally filtered by branch or file path
get_commit Get details for a specific commit including diff stats

Setup Instructions

Prerequisites:

  • 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:

  1. Install the gitlab-mpm.plugin file via CoWork → Plugins → Install Plugin
  2. Restart CoWork to load the MCP server
  3. In a CoWork session, ask Claude: "set up my GitLab credentials"
  4. Claude will call setup_credentials — provide your PAT when prompted
  5. Verify with check_credentials — should return your authenticated GitLab username
  6. Test with: "list the repos in the mpmedia-andriod group"

Generating a new PAT: GitLab → User Settings → Access Tokens → New token → scope: read_api → set expiry

Token rotation: Run setup_credentials("<new-pat>") 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)

Connection Details

Field Value
GitLab instance https://gitlab.com
API base URL https://gitlab.com/api/v4
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]<2" --with httpx --with keyring (see Troubleshooting — mcp[cli] must stay pinned below 2.0)
PAT scope required read_api

Workflow Notes

Claude follows a 4-step approach for all code research:

  1. Project discovery first — use list_group_projects or list_projects before reading files
  2. Search before reading — use search_code to locate symbols/functions rather than reading entire files
  3. Follow the thread — trace imports and call chains to understand the full context
  4. Cite precisely — report file paths, line numbers, and function names; don't paraphrase without citing

Group mpmedia-andriod contains APK code. Group mpmedia-transit-apps contains HTML Visual Applications. Group MPMedia contains middleware and GTFS backend work. Group mpm-backend-refactors contains RDMC-Mono. Group mpmprojects contains web apps and customer-specific integrations.

Requirements

  • uv (Python package runner) — standard on MPM macs
  • 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

Troubleshooting

Symptom Fix
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("<your-pat>") 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
search_code returns nothing Confirm correct project ID — search is per-project, not global
Deploy token (gldt- prefix) rejected Deploy tokens lack API scope — use a personal access token (glpat- prefix)
Reference in New Issue View Git Blame Copy Permalink