# MCP operator shell menu

## Purpose

`./mcp-menu.sh` is a repository-root terminal menu for onboarding and operating
the Gitea-Tools MCP/Gitea workflow without memorizing every prompt, script path,
or runbook section.

It is intentionally **safe by default**: status checks and copy-paste workflow
prompts. It does not delete branches, force-push, edit lock files, or bypass
sanctioned MCP tools.

## How to run

From the repository root:

```bash
./mcp-menu.sh
```

The script must be executable (`chmod +x mcp-menu.sh`). It uses bash with
`set -euo pipefail`.

## Safety rules

- **Read-only by default** — root checkout health is inspection only.
- **No destructive git** — no `git push --force`, branch deletion, or
  `--delete` refspecs.
- **No lock-file editing** — issue locks are acquired only through
  `gitea_lock_issue`.
- **No raw API bypass** — prompts direct operators to sanctioned MCP tools.
- **Remote mutations require confirmation** — any future menu action that would
  mutate remote or server state must be clearly labeled and require explicit
  operator confirmation before running.
- **Author work stays under `branches/`** — the root checkout is a stable
  control checkout on `master` / `prgs/master`.

## Menu options

| Option | Description |
|--------|-------------|
| Project status / root checkout health | Shows cwd, branch, `git status --short --branch`, HEAD SHA, `prgs/master` SHA, and warnings when the root checkout is dirty or off `master`. |
| Workflow dashboard (queue, leases, next safe action) | Documents the read-only `gitea_workflow_dashboard` MCP tool (#605): live PR/issue queues, leases by role, terminal review lock, blocked items, and exact next-safe prompts. **Does not assign work** — assignment still uses `gitea_allocate_next_work`. Never presents blocked/terminal-locked items as safe. The shell entry is documentation only (no Gitea mutation). |
| Author workflow prompts | Ready-to-copy prompts for issue work, conflict-fix sessions, and root checkout recovery. |
| Reviewer workflow prompts | Standard PR review prompt, and a skip-already-reviewed-stale-`REQUEST_CHANGES` prompt that hands off to the author without a duplicate terminal mutation (review-only; no merge). |
| Merger workflow prompts | PR merge prompt (merge gates and explicit approval). |
| Reconciler workflow prompts | Already-landed / closed PR reconciliation prompt. |
| Onboarding new project | Checklist prompt for adding a repository to the MCP workflow. |
| Proxmox deployment placeholder | **Not implemented** — informational message only. |
| Create Proxmox LXC placeholder | **Not implemented** — informational message only. |
| Run tests | Runs `./run-tests.sh` when present; otherwise `venv/bin/python -m pytest`; otherwise fails closed with a clear error. |
| Exit | Quit the menu. |

### Workflow dashboard MCP tool (#605)

From any healthy Gitea MCP namespace with `gitea.read`:

```text
gitea_workflow_dashboard(
    remote="prgs",
    org="Scaled-Tech-Consulting",
    repo="Gitea-Tools",
)
```

Response includes `human_summary` plus structured queues, `active_leases_by_role`,
`terminal_review_lock`, `blocked_items`, `next_safe_by_role`, and
`primary_next_safe_action`. Incomplete inventory fails closed.

## Placeholder-only entries

**Proxmox deployment** and **Create Proxmox LXC** are placeholders until
dedicated issues implement sanctioned automation. The menu prints a clear
message and does not invoke deploy scripts.

## Related documentation

- [`docs/llm-workflow-runbooks.md`](llm-workflow-runbooks.md) — Gitea-specific workflow runbooks
- [`skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) — portable workflow skill
- [`skills/llm-project-workflow/workflows/`](../skills/llm-project-workflow/workflows/) — canonical task workflows

## Tests

Hermetic coverage lives in `tests/test_mcp_menu_script.py`.