docs: update README to v0.2.0
This commit is contained in:
@@ -1,3 +1,129 @@
|
|||||||
# gitlab-mpm
|
# gitlab-mpm
|
||||||
|
|
||||||
Read-only access to MPM's GitLab repositories — Visual Applications, APK Code, RDMC, and Middleware Backend.
|
Read-only access to MPM's GitLab repositories — Visual Applications, APK Code, RDMC, and Middleware Backend.
|
||||||
|
|
||||||
|
**Version:** 0.2.0
|
||||||
|
**Author:** Message Point Media
|
||||||
|
**Repo:** https://git.alwisp.com/jason/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 on PATH (standard on MPM macs)
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
### Setup Checklist
|
||||||
|
- [ ] Plugin installed in CoWork
|
||||||
|
- [ ] CoWork restarted
|
||||||
|
- [ ] `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] --with httpx --with keyring` |
|
||||||
|
| 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]`, `httpx`, `keyring` — fetched automatically by `uv run` on first use
|
||||||
|
- GitLab PAT with `read_api` scope — generated in GitLab user settings
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Symptom | Fix |
|
||||||
|
|---|---|
|
||||||
|
| Tools not appearing after install | Restart CoWork; `uv` must be on PATH |
|
||||||
|
| `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
Block a user