Add MCP operator guide tool for Gitea workflow/profile instructions #128

New Issue

2026-07-03T18:37:00-05:00

jcwalker3 commented

2026-07-03 18:37:00 -05:00

Problem

New LLM sessions are being brought into the MCP Control Plane / Gitea-Tools project without enough built-in context. This forces long prompts that repeat the same operational rules: identity verification, profile switching, author/reviewer separation, fail-closed behavior, merge gates, redaction rules, and exact review/merge flow.

This should be exposed directly by the MCP server so an LLM can call one read-only tool and receive the current workflow instructions instead of guessing or relying on verbose handoff prompts.

Proposed Tool

Expose a new read-only MCP tool: gitea_get_operator_guide (or alternative mcp_get_control_plane_guide).

Requirements

Structured Guidance: Add a read-only MCP tool that returns a structured operator guide for the current Gitea MCP session.
Content Coverage: The guide must include:
- Active profile name
- Authenticated username, if resolved
- Remote context
- Allowed operations
- Forbidden operations
- Profile switching instructions
- Identity verification steps
- Author/reviewer/merger separation rules
- Hard stops
- Fail-closed rules
- Head-SHA pinning rules
- Merge confirmation rules
- Redaction/secrets rules
- No force-merge / no tags / no production reminder
- Common workflows for issue creation, implementation, PR review, and PR merge
Profile-Aware Guidance:
- For prgs-author, it must clearly say authoring is allowed but review/approve/merge is forbidden.
- For prgs-reviewer, it must clearly say review/merge may proceed only after eligibility and pinned-head checks pass.
- If identity is unresolved or mismatched, it must instruct the operator to stop.
Safety & Redaction:
- No tokens
- No keychain IDs
- No raw service URLs unless GITEA_MCP_REVEAL_ENDPOINTS=1 is enabled
- No secrets
- No private config paths unless already allowed by existing redaction policy
Testing Coverage: Add tests proving:
- The guide is read-only
- Output changes based on profile/allowed operations
- Author profile warns against review/merge
- Reviewer profile still requires eligibility checks
- Secrets, service URLs, and keychain IDs are redacted
- Unknown/unresolved identity fails closed with stop instructions
Documentation Update: Update documentation to tell future LLM operators to call this guide tool before using Gitea MCP tools in a new session.

Acceptance Criteria

A new read-only MCP tool exists and is documented.
New LLM sessions can call the tool to understand MCP Control Plane / Gitea workflow rules without a long pasted prompt.
Existing Gitea tool security gates remain unchanged.
No author/reviewer/merge permissions are weakened.
Tests cover profile-aware guidance and redaction behavior.

Scope update (2026-07-03): project skills / capability discovery

New LLM sessions need more than basic workflow instructions — they also need to discover what project workflows ("skills") exist and when to use them. This issue's scope now covers three read-only tools:

Required tools

mcp_get_control_plane_guide — the structured operator guide described above (supersedes the gitea_get_operator_guide name; keep naming consistent with the project convention).
mcp_list_project_skills — read-only registry of available project skills/workflows, each with a name, one-line description, when-to-use guidance, required profile/operations, and gating notes.
mcp_get_skill_guide(skill_name) (optional) — returns the detailed step-by-step guide for one named skill from the registry; unknown skill names fail closed with the list of valid names.

Guide/skill tool content requirements

The guide and skill tools must explain:

active profile
authenticated identity
allowed/forbidden operations
profile switching and verification
author/reviewer/merger separation
hard stops
fail-closed behavior
head-SHA pinning
merge confirmation rules
redaction/secrets rules
common workflows
available project skills and when to use them

Skill registry contents

The registry must include workflows such as:

Gitea issue authoring
Gitea PR creation
Gitea PR review
Gitea PR merge
Gitea issue comments
profile switching
redaction/security review
Jenkins read-only workflow
GlitchTip read-only workflow
release/operator workflows

Jenkins/GlitchTip/release entries may be marked as designed-but-not-implemented where the corresponding MCP servers/tools do not exist yet; the registry should say so rather than omit them.

Additional testing coverage

In addition to the tests above:

skill registry output is complete, stable, and profile-aware where relevant
mcp_get_skill_guide fails closed on unknown skill names
all three tools are read-only (no mutating API calls)
redaction rules hold for every tool (no tokens, keychain IDs, or raw service URLs without the reveal opt-in)

## Problem New LLM sessions are being brought into the MCP Control Plane / Gitea-Tools project without enough built-in context. This forces long prompts that repeat the same operational rules: identity verification, profile switching, author/reviewer separation, fail-closed behavior, merge gates, redaction rules, and exact review/merge flow. This should be exposed directly by the MCP server so an LLM can call one read-only tool and receive the current workflow instructions instead of guessing or relying on verbose handoff prompts. ## Proposed Tool Expose a new read-only MCP tool: `gitea_get_operator_guide` (or alternative `mcp_get_control_plane_guide`). ## Requirements 1. **Structured Guidance:** Add a read-only MCP tool that returns a structured operator guide for the current Gitea MCP session. 2. **Content Coverage:** The guide must include: - Active profile name - Authenticated username, if resolved - Remote context - Allowed operations - Forbidden operations - Profile switching instructions - Identity verification steps - Author/reviewer/merger separation rules - Hard stops - Fail-closed rules - Head-SHA pinning rules - Merge confirmation rules - Redaction/secrets rules - No force-merge / no tags / no production reminder - Common workflows for issue creation, implementation, PR review, and PR merge 3. **Profile-Aware Guidance:** - For `prgs-author`, it must clearly say authoring is allowed but review/approve/merge is forbidden. - For `prgs-reviewer`, it must clearly say review/merge may proceed only after eligibility and pinned-head checks pass. - If identity is unresolved or mismatched, it must instruct the operator to stop. 4. **Safety & Redaction:** - No tokens - No keychain IDs - No raw service URLs unless `GITEA_MCP_REVEAL_ENDPOINTS=1` is enabled - No secrets - No private config paths unless already allowed by existing redaction policy 5. **Testing Coverage:** Add tests proving: - The guide is read-only - Output changes based on profile/allowed operations - Author profile warns against review/merge - Reviewer profile still requires eligibility checks - Secrets, service URLs, and keychain IDs are redacted - Unknown/unresolved identity fails closed with stop instructions 6. **Documentation Update:** Update documentation to tell future LLM operators to call this guide tool before using Gitea MCP tools in a new session. ## Acceptance Criteria - A new read-only MCP tool exists and is documented. - New LLM sessions can call the tool to understand MCP Control Plane / Gitea workflow rules without a long pasted prompt. - Existing Gitea tool security gates remain unchanged. - No author/reviewer/merge permissions are weakened. - Tests cover profile-aware guidance and redaction behavior. --- ## Scope update (2026-07-03): project skills / capability discovery New LLM sessions need more than basic workflow instructions — they also need to discover what project workflows ("skills") exist and when to use them. This issue's scope now covers three read-only tools: ### Required tools 1. **`mcp_get_control_plane_guide`** — the structured operator guide described above (supersedes the `gitea_get_operator_guide` name; keep naming consistent with the project convention). 2. **`mcp_list_project_skills`** — read-only registry of available project skills/workflows, each with a name, one-line description, when-to-use guidance, required profile/operations, and gating notes. 3. **`mcp_get_skill_guide(skill_name)`** *(optional)* — returns the detailed step-by-step guide for one named skill from the registry; unknown skill names fail closed with the list of valid names. ### Guide/skill tool content requirements The guide and skill tools must explain: - active profile - authenticated identity - allowed/forbidden operations - profile switching and verification - author/reviewer/merger separation - hard stops - fail-closed behavior - head-SHA pinning - merge confirmation rules - redaction/secrets rules - common workflows - available project skills and when to use them ### Skill registry contents The registry must include workflows such as: - Gitea issue authoring - Gitea PR creation - Gitea PR review - Gitea PR merge - Gitea issue comments - profile switching - redaction/security review - Jenkins read-only workflow - GlitchTip read-only workflow - release/operator workflows Jenkins/GlitchTip/release entries may be marked as designed-but-not-implemented where the corresponding MCP servers/tools do not exist yet; the registry should say so rather than omit them. ### Additional testing coverage In addition to the tests above: - skill registry output is complete, stable, and profile-aware where relevant - `mcp_get_skill_guide` fails closed on unknown skill names - all three tools are read-only (no mutating API calls) - redaction rules hold for every tool (no tokens, keychain IDs, or raw service URLs without the reveal opt-in)

jcwalker3 added the status:in-progress label 2026-07-03 18:42:38 -05:00

jcwalker3 referenced this issue from a commit

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

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

jcwalker3 referenced a pull request that will close this issue

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

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

jcwalker3 referenced this issue

2026-07-04 00:04:12 -05:00

Make Gitea MCP profile activation and runtime identity state explicit #131

sysadmin closed this issue

2026-07-04 00:06:05 -05:00