From 873bcd06e50108645f1329e61e192901ad47c1fe Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Tue, 7 Jul 2026 04:27:02 -0400 Subject: [PATCH] docs: pin GlitchTip filing orchestrator contract (Closes #153) --- .../glitchtip-to-gitea-workflow-design.md | 46 +++++++++++++++---- docs/mcp-client-registration.md | 11 ++++- tests/test_external_mcp_registration_docs.py | 38 +++++++++++++++ 3 files changed, 85 insertions(+), 10 deletions(-) diff --git a/docs/architecture/glitchtip-to-gitea-workflow-design.md b/docs/architecture/glitchtip-to-gitea-workflow-design.md index 08e4571..3106b7d 100644 --- a/docs/architecture/glitchtip-to-gitea-workflow-design.md +++ b/docs/architecture/glitchtip-to-gitea-workflow-design.md @@ -1,21 +1,34 @@ -# GlitchTip-to-Gitea Issue Filing Workflow Design +# GlitchTip-to-Gitea Issue Filing Workflow Contract -- **Status:** Design (no implementation in this repo) -- **Issue:** #74 (parent umbrella: #75) +- **Status:** Contract for the library-only implementation in + `Scaled-Tech-Consulting/mcp-control-plane` (#57) +- **Issue:** #153 (supersedes #74/#78 as the Gitea-Tools tracker) - **Related:** #78 (deduplication design, child of #74) -- **Date:** 2026-07-02 +- **Date:** 2026-07-07 ## 1. Boundary and Orchestration * **GlitchTip-to-Gitea filing is NOT a GlitchTip MCP capability.** The `glitchtip-mcp` boundary remains strictly read-only per ADR-0001. -* The filing capability lives in an **orchestrator / runbook / release workflow**. It **composes** separate GlitchTip **read** tools (from the `glitchtip-mcp` server) and Gitea **issue** tools (from the `gitea-mcp` server). +* The filing capability lives in a **library-only orchestrator** in + `mcp-control-plane` and is not exposed through `glitchtip-mcp`. +* The orchestrator composes the real GlitchTip read path with Gitea + issue-write tools. It must not use mocked GlitchTip issue data in production + filing paths. * The orchestrator **must not centralize credentials** into a single server. The GlitchTip MCP holds only GlitchTip tokens, and the Gitea MCP holds only Gitea tokens. +* If a future MCP surface exposes filing, it must be a separate write-boundary + server/profile with explicit Gitea issue-write permission and the same audit + gates. It must not be added to the read-only `glitchtip-mcp` surface. ## 2. Invocation and Safety * **Explicit invocation only:** There is no automatic, unsupervised filing in phase 1. A human or an explicitly-triggered automation must initiate the workflow. * **Dry-run / Preview required:** The orchestrator must present a preview of the drafted Gitea issue (title, body, labels) and obtain explicit confirmation before calling the Gitea mutation tool to file the issue. -* **Gitea Profile Checks & Audit Logging:** The actual Gitea issue creation relies on `gitea-mcp`, and therefore inherently subjects the mutation to Gitea profile checks and audit logging as standard. +* **Gitea Profile Checks & Audit Logging:** The actual Gitea issue creation + relies on `gitea-mcp`, and therefore must pass Gitea profile checks and + fail-closed mutation audit before create/link/comment actions. +* **Deduplication before create:** The orchestrator must run the + GlitchTip-to-Gitea dedup/linking logic before any Gitea create action. Create, + link, and skip decisions must be represented in tests. ## 3. Gitea Issue Format @@ -51,6 +64,23 @@ To prevent PII or secret leakage into Gitea, the orchestrator and the underlying The principle is: **"Link, don't dump"**. The generated issue acts as an alert/pointer, while the raw context remains protected inside GlitchTip. -## 5. Deduplication and Linking (Deferred) +## 5. Deduplication and Linking -Deduplication logic (e.g. searching existing Gitea issues, managing GlitchTip issue IDs, and race condition handling) is specifically handled by **Issue #78** and will augment this design. +Deduplication logic (e.g. searching existing Gitea issues, managing GlitchTip +issue IDs, and race condition handling) is integrated into the library-only +filing orchestrator in `mcp-control-plane`. The orchestrator must reuse that +dedup/linking path instead of duplicating or bypassing it. + +## 6. Gitea-Tools Acceptance Contract for #153 + +Gitea-Tools does not host the filing implementation. This repository owns the +operator-facing contract: + +* `glitchtip-mcp` remains read-only and exposes only GlitchTip inspection tools. +* Filing is implemented in `mcp-control-plane`, not in this Gitea MCP runtime. +* Filing uses the real GlitchTip read path, not mocked issue data. +* Dedup runs before any Gitea create action. +* Create/link/skip decisions and audit failure are covered by orchestrator tests. +* Mutation audit fails closed before any Gitea create, link, or comment mutation. +* Any future MCP exposure requires a separate write-boundary server/profile and + must not add Gitea write credentials to `glitchtip-mcp`. diff --git a/docs/mcp-client-registration.md b/docs/mcp-client-registration.md index e83d5f3..f0477dd 100644 --- a/docs/mcp-client-registration.md +++ b/docs/mcp-client-registration.md @@ -95,7 +95,14 @@ back to shell commands, raw service APIs, or unrelated MCP servers. - Do not register `jenkins-write-mcp` until an operator approves a trigger profile; no shipped profile carries trigger capability by default. - `glitchtip-mcp` remains read-only. It must not file or mutate Gitea issues. -- GlitchTip-to-Gitea filing is a separate orchestrator that composes GlitchTip - read tools with Gitea issue-write tools. +- GlitchTip-to-Gitea filing is a separate library-only orchestrator in + `mcp-control-plane` that composes the real GlitchTip read path with Gitea + issue-write tools. +- The filing orchestrator must run GlitchTip/Gitea dedup before any Gitea + create action, and its create/link/skip decisions must be covered by tests. +- The filing orchestrator must fail closed on mutation-audit failure before + any Gitea create, link, or comment mutation. +- If filing is ever MCP-exposed, it must use a separate write-boundary + server/profile. It must not be exposed by `glitchtip-mcp`. - Gitea credentials never enter Jenkins or GlitchTip runtimes. - Jenkins and GlitchTip credentials never enter the Gitea MCP runtime. diff --git a/tests/test_external_mcp_registration_docs.py b/tests/test_external_mcp_registration_docs.py index 40c8eba..8225bb6 100644 --- a/tests/test_external_mcp_registration_docs.py +++ b/tests/test_external_mcp_registration_docs.py @@ -59,6 +59,22 @@ def test_registration_doc_preserves_boundaries(): assert phrase in text +def test_registration_doc_pins_glitchtip_filing_boundary(): + text = " ".join(_doc_text().split()) + for phrase in ( + "GlitchTip-to-Gitea filing is a separate library-only orchestrator in " + "`mcp-control-plane`", + "real GlitchTip read path", + "dedup before any Gitea create action", + "create/link/skip decisions", + "fail closed on mutation-audit failure before any Gitea create, link, " + "or comment mutation", + "must use a separate write-boundary server/profile", + "must not be exposed by `glitchtip-mcp`", + ): + assert phrase in text + + def test_registration_doc_separates_jenkins_trigger_from_read_surface(): text = _doc_text() assert "jenkins_trigger_build" in text @@ -100,3 +116,25 @@ def test_related_docs_keep_jenkins_trigger_off_read_surface(): assert "jenkins-write-mcp" in text assert "jenkins_mcp.write_server" in text assert "jenkins-mcp" in text + + +def test_glitchtip_filing_contract_doc_covers_issue_153_acceptance(): + text = ( + REPO_ROOT / "docs" / "architecture" / + "glitchtip-to-gitea-workflow-design.md" + ).read_text(encoding="utf-8") + flattened = " ".join(text.split()) + for phrase in ( + "**Status:** Contract for the library-only implementation in " + "`Scaled-Tech-Consulting/mcp-control-plane` (#57)", + "**Issue:** #153", + "not exposed through `glitchtip-mcp`", + "real GlitchTip read path", + "must not use mocked GlitchTip issue data", + "separate write-boundary server/profile", + "fail-closed mutation audit before create/link/comment actions", + "Deduplication before create", + "Create, link, and skip decisions must be represented in tests", + "Mutation audit fails closed", + ): + assert phrase in flattened -- 2.43.7