From 7102f27d20c5599582182e2605efeee98dd96cdb Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Sun, 5 Jul 2026 10:59:50 -0400 Subject: [PATCH] docs: update operator runbooks and roadmap docs for Jenkins/GlitchTip MCP status (#154) - Updated jenkins-readonly and glitchtip-readonly skills in _PROJECT_SKILLS: - Descriptions and notes now use actual server names (jenkins-mcp, glitchtip-mcp) - Explain historical -readonly skill names vs registration in mcp-control-plane #55 - Note gated trigger in jenkins-mcp (see #56), partial filing in glitchtip (see #57) - Updated docs/safety-model.md: naming note, corrected mutation gating claims for trigger/filing - Updated docs/architecture/jenkins-readonly-build-status-design.md: naming note, updated Phase 1 to account for gated trigger - No behavior change to skill status/availability; no secrets exposed - AC: stale naming explained, actual names documented, Jenkins claims corrected, GlitchTip filing as partial, no over-claiming Closes #154 --- .../jenkins-readonly-build-status-design.md | 8 ++++--- docs/safety-model.md | 6 ++++-- mcp_server.py | 21 +++++++------------ 3 files changed, 17 insertions(+), 18 deletions(-) diff --git a/docs/architecture/jenkins-readonly-build-status-design.md b/docs/architecture/jenkins-readonly-build-status-design.md index 7e231e5..27dbaaf 100644 --- a/docs/architecture/jenkins-readonly-build-status-design.md +++ b/docs/architecture/jenkins-readonly-build-status-design.md @@ -5,20 +5,22 @@ - **Related:** #77 (repo/branch/PR → job mapping, designed separately) - **Date:** 2026-07-02 +Note on naming: This design used historical `jenkins-readonly` skill name in Gitea-Tools. Actual package/server is `jenkins-mcp` (see mcp-control-plane registration in #55). The server boundary now contains gated trigger (see #56), but read tools remain as designed. + ## 1. Purpose and scope Define the minimum **read-only** Jenkins MCP tool set that lets an LLM answer: *"Did the latest build for this project/branch succeed or fail?"* — plus enough detail (build URL, number, timing, result) to report or investigate. -Phase 1 is **strictly read-only**, per ADR-0001 +Phase 1 is **primarily read-only**, per ADR-0001 ([`adr-0001-mcp-control-plane-boundaries.md`](adr-0001-mcp-control-plane-boundaries.md)): -- **Excluded: build triggers.** +- Build triggers are gated behind dedicated profile + exact confirmation (landed in #4, boundary correction in #56). - **Excluded: deploy triggers.** - **Excluded: parameterized job launches.** - Excluded: job creation/deletion/config changes, queue manipulation, node - management — any Jenkins mutation whatsoever. + management — any Jenkins mutation whatsoever unless explicitly configured. ## 2. Boundary placement diff --git a/docs/safety-model.md b/docs/safety-model.md index fd2549c..fb9b92b 100644 --- a/docs/safety-model.md +++ b/docs/safety-model.md @@ -17,7 +17,9 @@ To maintain a secure environment, all secrets, tokens, passwords, and sensitive ## 4. Read-Only First Policy By default, MCP servers (such as `jenkins-mcp` and `ops-mcp`) operate in a **read-only** mode. Mutation capabilities are deny-by-default and fail-closed. +Note on naming: Historical design docs used `jenkins-readonly` / `glitchtip-readonly` skill names. Actual server packages are `jenkins-mcp` / `glitchtip-mcp` (registered via entry points in mcp-control-plane). See Gitea-Tools skills and mcp-control-plane #55 for registration. + ## 5. Mutation Gating Any mutating action (e.g., Gitea issue creation from GlitchTip, or Jenkins builds) must be explicitly allowed by the execution profile. -- **Jenkins build triggers** are explicitly deferred for phase 1. -- **GlitchTip to Gitea issue filing** is documented as a gated, orchestrated workflow, not a direct unprompted automatic action. +- **Jenkins build triggers** exist in jenkins-mcp (landed #4) but require dedicated profile/identity and exact confirmation; not on standard reader profiles. See #56 for boundary correction. +- **GlitchTip to Gitea issue filing** is documented as a gated, orchestrated workflow (not in glitchtip-mcp), currently partial (mocked, dedup not wired, audit missing). See #57. diff --git a/mcp_server.py b/mcp_server.py index 6c8ede6..48a0a3f 100644 --- a/mcp_server.py +++ b/mcp_server.py @@ -1820,34 +1820,29 @@ _PROJECT_SKILLS = { }, "jenkins-readonly": { "description": "Read-only Jenkins CI inspection (jobs, builds, " - "logs).", + "logs). Actual server name: jenkins-mcp (see mcp-control-plane).", "when_to_use": "Checking CI state once Jenkins MCP tools exist.", "required_operations": ["jenkins.read"], "status": "designed-not-implemented", - "notes": "Design exists (issues #72/#77); no Jenkins MCP server is " - "connected yet. Report SKIPPED rather than substituting " - "shell or direct API calls.", + "notes": "Server code exists in mcp-control-plane as jenkins-mcp (read tools + gated trigger); registration pending (#55); docs in Gitea-Tools use historical name. Report SKIPPED if not connected. Do not substitute shell/API. Trigger requires dedicated profile (see #56).", "steps": [ - "Confirm a Jenkins MCP server is connected; if not, report " + "Confirm a Jenkins MCP server is connected (jenkins-mcp); if not, report " "SKIPPED.", - "Use read-only operations only; never trigger, cancel, or " - "configure builds.", + "Use read-only operations only; never trigger unless using dedicated profile + confirmation.", ], }, "glitchtip-readonly": { - "description": "Read-only GlitchTip error/event inspection.", + "description": "Read-only GlitchTip error/event inspection. Actual server name: glitchtip-mcp (see mcp-control-plane).", "when_to_use": "Investigating reported errors once GlitchTip MCP " "tools exist.", "required_operations": ["glitchtip.read"], "status": "designed-not-implemented", - "notes": "Design exists (issue #73); no GlitchTip MCP server is " - "connected yet. Report SKIPPED rather than substituting " - "shell or direct API calls.", + "notes": "Server code exists in mcp-control-plane as glitchtip-mcp (read-only tools); registration pending (#55); filing orchestrator is partial in mcp-control-plane (see #57). Report SKIPPED if not connected. Filing to Gitea is separate orchestrator, not in this server.", "steps": [ - "Confirm a GlitchTip MCP server is connected; if not, report " + "Confirm a GlitchTip MCP server is connected (glitchtip-mcp); if not, report " "SKIPPED.", "Use read-only operations only; never mutate issues or " - "settings.", + "settings. Filing tracked in #57.", ], }, "release-operator": { -- 2.43.7