sysadmin
7f2b9f36de
Read-only MCP tool gitea_workflow_dashboard plus mcp-menu entry so operators and LLMs can see PR/issue queues, leases, terminal locks, blockers, and exact next-safe prompts without reconstructing state from comments. Never assigns work or presents blocked/terminal-locked items as safe.
84 lines
3.8 KiB
Markdown
84 lines
3.8 KiB
Markdown
# 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`. |