# Testing Platform — MCP server

A small Model Context Protocol server that gives Claude Code read+write access
to the Testing Platform's issues. Lets you say things like:

- *"Go to the Panda Eats project and check the critical new issues."*
- *"Show me everything in In Review reported by tanya."*
- *"Create a high-priority bug in Panda Eats titled 'Login throws 500'."*
- *"Move issue 35 back to In Progress and post a comment that it's being reworked."*

Runs on your machine, talks to the production HTTP API
(`https://testing.r-ruiz.com/api`) using a long-lived API token tied to your
developer account.

---

## Setup

1. **Mint an access token** in the app.
   Sign in as a developer → click the **key icon** in the header
   (next to the bell) → **Generate token**. The token is shown exactly once —
   copy it before closing the modal.

2. **Build the package.**
   ```bash
   cd mcp
   npm install
   npm run build
   ```

3. **Register with Claude Code (user scope — available in every session on this machine).**
   ```bash
   claude mcp add \
     -e TP_API_BASE=https://testing.r-ruiz.com/api \
     -e TP_API_TOKEN=<paste-token> \
     -s user testing-platform \
     -- node "<absolute path to mcp/dist/index.js>"
   ```
   The `-s` flag must come after the `-e` env vars so the variadic env parser
   terminates cleanly. `--` separates the server name from the launch command.

   Verify:
   ```bash
   claude mcp list                  # should show ✓ Connected next to testing-platform
   claude mcp get testing-platform  # shows full config + scope
   ```

   Then in any Claude Code session: *"list my testing-platform projects"* — the
   server resolves and returns them.

   **Alternative: project scope.** If you'd rather pin the server to this repo
   only (e.g. to share with a teammate who clones it), commit a `.mcp.json` at
   the repo root pointing at `./mcp/dist/index.js`. Don't do both — Claude Code
   warns about scope conflicts and picks the project one.

4. **`.env` (optional fallback).** If you also run the server outside Claude
   Code (e.g. `node dist/index.js` directly), copy `.env.example` to `.env`
   and paste the token there. Not needed when `-e` is set in the registration.

---

## Tools

All tools take the configured developer token's privileges — i.e., the same
access you have as the user that minted the token in the app.

| Tool | What it does |
|---|---|
| `list_projects` | Every project the token's user can see. |
| `find_project(query)` | Resolve a name (e.g. "panda eats") to its project. Returns an error listing candidates when ambiguous. |
| `list_issues(project, { status?, priority?, type?, reporter?, q?, include_archived?, limit?, offset? })` | Filter the active board or the archive. `project` is name-or-id. |
| `get_issue({ id })` | Full detail including attachments + comment count. |
| `list_comments({ card_id })` | Comments on an issue, oldest first. |
| `create_issue({ project, title, description, type?, priority?, url? })` | New issue, lands in the New column. |
| `add_comment({ card_id, body })` | Post a comment. Visible immediately to anyone on the board. |
| `update_issue({ id, title?, description?, status?, priority?, type?, url? })` | Patch fields. Note: `in_review → done/wont_fix` is blocked server-side without reporter sign-off. |

No `delete_issue` — that lives in the app's UI, on purpose.

## Giving an outside developer access to ONE board

You don't have to hand someone a developer-level token (which reaches every
board you can see) to let them work a single project. Mint a **board-developer
token** scoped to just that board and give them only that — they never get the
keys, the whitelist, or any other board.

1. In the app, open the project's **Tokens** button (developer-only).
2. Pick **Access → Full board access**, give it a **label** that names the
   source (e.g. `Acme Dev (Cursor)`), and **Generate**. Copy the `tp_…` value —
   shown once.
3. Hand that token to the developer. They register it in **their own** Claude
   Code / VS Code session exactly like the setup above, but with your value:

   ```bash
   claude mcp add -e TP_API_BASE=https://testing.r-ruiz.com/api \
     -e TP_API_TOKEN=tp_… -s user testing-platform \
     -- node "<path to mcp/dist/index.js>"
   ```

What that token can do, **on that one board only**: list/read issues, create
issues, comment, and move/update cards (including the same in-review close
bypass the MCP service account has). What it can't: see or touch any other
board, the whitelist, project settings, members, secrets, or mint more tokens —
all of that stays developer-only.

**Provenance.** Everything the token does shows up on the board under its
**label** as a distinct, non-human source (it files and acts as a service
identity named after the label), so it's always clear an action came from that
outside session and not from you. Revoke any time from the same Tokens modal —
the credential and its board access die immediately.

## Notes

- **Rotation.** Lost or leaked? Open the same modal in the app and regenerate;
  the previous token stops working immediately. Update `mcp/.env` with the new
  one and restart Claude Code.
- **Revoke.** The same modal has a Revoke button that clears the token
  entirely. Any MCP request afterwards returns 401.
- **Token scope.** A user token (minted from the header key icon) grants the
  same access as that user in-app — for a developer, every visible project. To
  confine a session to a single board, use a **board-developer token** instead
  (see "Giving an outside developer access to ONE board" above). Neither is yet
  scoped to individual operations within a board.