sysadminandClaude Opus 4.8
1301a57de4
Adds docs/architecture/mcp-restart-governance.md, the restart-governance/v1 ADR defining who may restart the MCP control plane and under what conditions. - Recovery ladder (reconnect -> rebind -> scoped restart -> full restart -> host) with restart stated as the last resort. - Authorization matrix across author/reviewer/merger/reconciler/controller/ operator/admin; no LLM worker role may perform or authorize a full or host restart. - v1 authority decision recorded: controller approval + automated safety gates; quorum deferred to a superseding ADR. - Break-glass path with pre-declared incident and mandatory post-hoc audit. - Ambiguous policy state denies restart. - Stable policy IDs RG-01..RG-08 for later enforcement code to bind to. Cross-links the ADR from docs/safety-model.md and docs/webui-deployment.md, and adds tests/test_mcp_restart_governance_docs.py asserting acceptance criteria 1-5. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
63 lines
3.6 KiB
Markdown
63 lines
3.6 KiB
Markdown
# MCP Safety Model
|
||
|
||
This document outlines the safety requirements for all tools within the MCP monorepo.
|
||
|
||
## 1. Audit Logging and Confirmation
|
||
All mutating actions (e.g., triggering builds, creating resources, updating environments) must be recorded in an audit log. These actions require explicit confirmation from the user before execution to prevent accidental state changes.
|
||
|
||
## 2. Production Environment Safety
|
||
Any action that targets a production environment must have a hard confirmation gate. Production actions must never run based on vague or ambiguous prompts. The user must provide explicit, unambiguous consent to proceed with a production deployment or modification.
|
||
|
||
## 3. Secret Redaction
|
||
To maintain a secure environment, all secrets, tokens, passwords, and sensitive keys must be strictly redacted from:
|
||
- System and application logs
|
||
- Tool return values/outputs
|
||
- Any form of persistent storage or console output
|
||
|
||
## 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 gated on a separate write boundary
|
||
(`jenkins-write-mcp` / `jenkins_mcp.write_server`), not on the read-only
|
||
`jenkins-mcp` surface. Triggers require a dedicated profile with
|
||
`jenkins.build.trigger`, exact confirmation, and fail-closed mutation audit.
|
||
No default profile carries trigger capability (#152 / mcp-control-plane #56).
|
||
- **GlitchTip to Gitea issue filing** is a library-only orchestrator in
|
||
mcp-control-plane (not on `glitchtip-mcp`). See #153 / mcp-control-plane #57.
|
||
|
||
## 6. Agent Commit Path (no improvised fallbacks)
|
||
|
||
When an author execution profile allows **`gitea.repo.commit`** and the
|
||
**`gitea_commit_files`** tool is visible, agents must use that MCP path for
|
||
repository commits. Fail closed instead of improvising alternate transports.
|
||
|
||
Forbidden when MCP commit is available:
|
||
|
||
- WebFetch or other HTTP calls to external base64/decode services
|
||
- Playwright or browser automation used to work around MCP commit
|
||
- Manual LLM-generated base64 embedded in throwaway scripts as the primary
|
||
commit transport
|
||
|
||
If shell helpers are unavailable and MCP commit cannot run, stop with a recovery
|
||
report (restart session, clear hung terminals, use MCP-native commit). See
|
||
[`llm-workflow-runbooks.md`](llm-workflow-runbooks.md) § MCP-native commit path
|
||
(#260) and agent temp artifact cleanup (#261).
|
||
|
||
## 7. Process restart governance
|
||
|
||
Restarting the MCP control-plane process is destructive to concurrent multi-role
|
||
work and is governed by a dedicated policy. Restart is a **last resort** behind
|
||
narrower recoveries (reconnect, rebind), full/host restart is reserved to
|
||
operator/admin under **controller approval + automated safety gates**, a
|
||
unilateral LLM or operator full restart with active peers is **forbidden**, and
|
||
ambiguous policy state **denies** restart. Break-glass is a separate,
|
||
incident-backed path with a mandatory audit.
|
||
|
||
See [`architecture/mcp-restart-governance.md`](architecture/mcp-restart-governance.md)
|
||
(#656) for the authorization matrix, the recovery ladder, break-glass
|
||
conditions, and the `RG-01`–`RG-08` policy IDs.
|