feat: add operator guide and project skills discovery MCP tools (#128) #130

2026-07-03T18:49:41-05:00

jcwalker3 commented

2026-07-03 18:49:41 -05:00

Summary

Implements #128 (including the 2026-07-03 scope update): three read-only capability-discovery MCP tools so new LLM sessions get workflow/profile instructions and skill discovery from the server instead of long pasted operator prompts.

New tools

mcp_get_control_plane_guide(remote, host) — structured operator guide: active profile (name, allowed/forbidden operations, inferred role kind), authenticated identity (fail-soft; unresolved identity yields explicit STOP instructions), profile-aware guidance, and standing rules covering hard stops, fail-closed behavior, head-SHA pinning, merge confirmation (MERGE PR <n>), redaction/secrets, author/reviewer/merger separation, profile switching, and identity verification, plus common workflows and a pointer to the skills registry.
- prgs-author-style profiles: told authoring is allowed and review/approve/merge is forbidden.
- prgs-reviewer-style profiles: told review/merge proceeds only after eligibility checks pass and the head SHA is pinned, plus operator authorization for merge.
- Profiles allowing both: explicit misconfiguration WARNING + STOP.
mcp_list_project_skills() — registry of ten workflows: gitea-issue-authoring, gitea-pr-creation, gitea-pr-review, gitea-pr-merge, gitea-issue-comments, profile-switching, redaction-security-review, jenkins-readonly, glitchtip-readonly, release-operator. Each has description, when-to-use, required operations, status, per-profile availability. Jenkins/GlitchTip are listed as designed-not-implemented (report SKIPPED, never substitute shell/API); release workflows are operator-only.
mcp_get_skill_guide(skill_name) — step-by-step guide per skill (case-insensitive); unknown names fail closed with the valid-name list.

Safety

All three tools are read-only; the guide makes at most a GET identity lookup; the skills tools make no API calls. No existing gate or permission changed.
Normal output: no endpoint URLs, keychain IDs, or token values; the server host appears in the guide only under GITEA_MCP_REVEAL_ENDPOINTS=1.

Tests

tests/test_operator_guide.py — 17 new tests: author/reviewer profile-aware guidance, unresolved-identity STOP (fail closed), read-only proofs, redaction defaults + reveal opt-in, rules topic coverage, registry completeness/stability/profile-awareness, unimplemented-service marking, unknown-skill fail-closed, no-URL sweeps across all skill guides.

Full suite: 498 passed, 6 skipped. py_compile clean; git diff --check clean; secret sweep clean (only guidance prose mentions the words token/keychain).

Docs

docs/llm-workflow-runbooks.md: new-session callout — call mcp_get_control_plane_guide first, then mcp_list_project_skills / mcp_get_skill_guide.

Closes #128

## Summary Implements #128 (including the 2026-07-03 scope update): three read-only capability-discovery MCP tools so new LLM sessions get workflow/profile instructions and skill discovery from the server instead of long pasted operator prompts. ## New tools - **`mcp_get_control_plane_guide(remote, host)`** — structured operator guide: active profile (name, allowed/forbidden operations, inferred role kind), authenticated identity (fail-soft; unresolved identity yields explicit STOP instructions), profile-aware guidance, and standing rules covering hard stops, fail-closed behavior, head-SHA pinning, merge confirmation (`MERGE PR <n>`), redaction/secrets, author/reviewer/merger separation, profile switching, and identity verification, plus common workflows and a pointer to the skills registry. - `prgs-author`-style profiles: told authoring is allowed and review/approve/merge is forbidden. - `prgs-reviewer`-style profiles: told review/merge proceeds only after eligibility checks pass and the head SHA is pinned, plus operator authorization for merge. - Profiles allowing both: explicit misconfiguration WARNING + STOP. - **`mcp_list_project_skills()`** — registry of ten workflows: gitea-issue-authoring, gitea-pr-creation, gitea-pr-review, gitea-pr-merge, gitea-issue-comments, profile-switching, redaction-security-review, jenkins-readonly, glitchtip-readonly, release-operator. Each has description, when-to-use, required operations, status, per-profile availability. Jenkins/GlitchTip are listed as `designed-not-implemented` (report SKIPPED, never substitute shell/API); release workflows are `operator-only`. - **`mcp_get_skill_guide(skill_name)`** — step-by-step guide per skill (case-insensitive); unknown names fail closed with the valid-name list. ## Safety - All three tools are read-only; the guide makes at most a GET identity lookup; the skills tools make no API calls. No existing gate or permission changed. - Normal output: no endpoint URLs, keychain IDs, or token values; the server host appears in the guide only under `GITEA_MCP_REVEAL_ENDPOINTS=1`. ## Tests `tests/test_operator_guide.py` — 17 new tests: author/reviewer profile-aware guidance, unresolved-identity STOP (fail closed), read-only proofs, redaction defaults + reveal opt-in, rules topic coverage, registry completeness/stability/profile-awareness, unimplemented-service marking, unknown-skill fail-closed, no-URL sweeps across all skill guides. Full suite: **498 passed, 6 skipped**. `py_compile` clean; `git diff --check` clean; secret sweep clean (only guidance prose mentions the words token/keychain). ## Docs `docs/llm-workflow-runbooks.md`: new-session callout — call `mcp_get_control_plane_guide` first, then `mcp_list_project_skills` / `mcp_get_skill_guide`. Closes #128

jcwalker3 added 1 commit 2026-07-03 18:49:41 -05:00

feat: add operator guide and project skills discovery MCP tools (#128 ) 6a8a9d99b7

Add three read-only capability-discovery tools so new LLM sessions can
learn the workflow rules and available project skills from the MCP
server instead of long pasted operator prompts:

- mcp_get_control_plane_guide: active profile, authenticated identity
  (fail-soft; unresolved identity returns STOP instructions),
  allowed/forbidden operations, profile-aware guidance (author profiles
  are told review/approve/merge is forbidden; reviewer profiles are told
  review/merge requires eligibility checks and a pinned head SHA; mixed
  profiles get a misconfiguration warning), and the standing rules: hard
  stops, fail-closed behavior, head-SHA pinning, merge confirmation,
  redaction, author/reviewer/merger separation, profile switching, and
  identity verification.
- mcp_list_project_skills: registry of ten project workflows (issue
  authoring, PR creation, PR review, PR merge, issue comments, profile
  switching, redaction/security review, Jenkins read-only, GlitchTip
  read-only, release/operator) with description, when-to-use, required
  operations, status, and per-profile availability. Unimplemented
  services are listed as designed-not-implemented rather than omitted.
- mcp_get_skill_guide: step-by-step guide per skill; unknown names fail
  closed with the list of valid names.

All three are read-only and change no existing gate or permission.
Normal output contains no endpoint URLs or keychain IDs; the guide
includes the server host only under GITEA_MCP_REVEAL_ENDPOINTS=1.

Tests (tests/test_operator_guide.py, 17 new): profile-aware guidance
for author/reviewer, unresolved-identity STOP, read-only behavior,
redaction defaults and reveal opt-in, rules coverage, registry
completeness and profile awareness, unimplemented-service marking,
fail-closed unknown skill names.

Docs: llm-workflow-runbooks.md now tells new sessions to call the guide
tools first.

Closes #128

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feat/issue-128-operator-guide-skills:feat/issue-128-operator-guide-skills

git checkout feat/issue-128-operator-guide-skills

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#130