Gitea-Tools/docs/mcp-menu.md

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:

./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:

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 — Gitea-specific workflow runbooks
• skills/llm-project-workflow/SKILL.md — portable workflow skill
• skills/llm-project-workflow/workflows/ — canonical task workflows

Tests

Hermetic coverage lives in tests/test_mcp_menu_script.py.