Gitea-Tools/docs/architecture/glitchtip-readonly-tools-design.md

GlitchTip Read-Only Error/Event Tools — Design Notes

• Status: Design (implementation-ready notes; no implementation in this repo)
• Issue: #73 (umbrella: #75; boundary decision: ADR-0001, #71)
• Related: #74 (GlitchTip→Gitea filing workflow — composes these read tools), #78 (dedup/linking, child of #74), #76 (per-service profile schema)
• Date: 2026-07-02

1. Purpose and scope

Define the minimum read-only GlitchTip MCP tool set that lets an LLM answer: "What unresolved errors does project X have (by environment/release), and what is this specific error?" — with privacy-safe output suitable for LLM context, issue bodies, and audit logs.

Strictly read-only, per ADR-0001:

• No mutation tools — no resolving/ignoring/assigning issues, no comment posting, no project/team/key administration, no deletes.
• No automatic GlitchTip→Gitea filing (that is #74's orchestrated, explicitly-invoked workflow; it composes these read tools and Gitea write tools — never one dual-credential server).
• This server never holds Gitea write credentials.

2. Boundary placement (namespace pending)

These tools belong to the GlitchTip observability boundary of the MCP Control Plane — glitchtip-mcp (ADR-0001's recommendation), observability-mcp, or folded into ops-mcp. ADR-0001 open owner decision #2 picks the name; this design does not assume it. Tool names below use the glitchtip_ prefix for readability and rename mechanically with the decision.

Fixed regardless of the name (per tool-boundaries.md, credential-isolation.md):

• Own server process, own .env, GlitchTip credentials only.
• No Gitea, Jenkins, or Ops tokens in this runtime; no GlitchTip token anywhere else.

3. API surface note (Sentry compatibility)

GlitchTip implements a Sentry-compatible REST API (/api/0/... — organizations, projects, issues, events). The design targets GlitchTip's documented subset only; Sentry-only endpoints must not be assumed. The implementation should pin against a tested GlitchTip version and treat missing endpoints/fields as degraded-but-safe (omit field, never crash).

4. Minimum read-only tool set

Tool	Purpose
glitchtip_whoami	Verify authenticated identity + active profile (mirror of gitea_whoami; fail-closed identity proof)
glitchtip_list_projects	Projects visible to the token (org-scoped), with pagination bounds
glitchtip_list_unresolved	Unresolved issues for a project, filterable (§6), sorted by last-seen
glitchtip_get_issue	Safe detail of one issue (fields §5)
glitchtip_recent_events	Recent events for an issue (summaries only, §5)
glitchtip_search	Issue search within a project (query + filters §6)

All tools are GET-only. No tool issues PUT/POST/DELETE.

5. Privacy: field-level allowlist (the core rule)

Error events routinely contain PII and secrets (request bodies, cookies, headers, tokens, user emails/IPs, local variables). Therefore: allowlist projection only — raw event/issue payloads are never passed through.

Issue-level safe fields (glitchtip_list_unresolved, glitchtip_get_issue, glitchtip_search)

Field	Notes
issue_id	GlitchTip issue ID (dedup key for #78)
fingerprint	When available (dedup key for #78)
title / culprit	Error type + short message/transaction — redactor-passed
project	Slug
level	error/warning/…
status	unresolved/…
environment	When filtered/available
release	Version string
first_seen / last_seen	ISO-8601 UTC
event_count / user_count	Numbers only — never user identities
permalink	GlitchTip web URL (the "link, not dump" principle)

Event-level safe fields (glitchtip_recent_events)

event_id, timestamp, level, environment, release, redactor-passed message, and a stack summary only: top N (default 5) frames as module/filename:function:line — in-app frames preferred.

Redact / omit — never returned

Request headers; cookies; auth/session fields; user emails, usernames, IPs; request/form bodies; query strings; local variables; full raw stack frames (source context lines); SDK/device metadata beyond platform name; breadcrumbs; any extra/context blobs.

Full raw frames or request context require a separate, explicitly approved operation (glitchtip.event.read_raw) that is absent from default profiles — same pattern as jenkins.console.read in the #72 design. Even then, output passes the shared secret redactor; redaction failure ⇒ error, never raw text.

Default output = fingerprint / release / summary + permalink. The permalink carries the human to the full data in GlitchTip's own UI, where its access control applies — the MCP layer does not re-serve raw payloads.

6. Filtering and pagination

Filters (all optional, combinable): project (required for issue/event queries), environment, release, fingerprint, free-text query (GlitchTip search syntax, e.g. is:unresolved).

Pagination: cursor-based per the API. Bounds: per-page cap 50; default overall cap 100 items; hard cap max_pages (default 10) against runaway loops — mirroring gitea_auth.api_get_all. Truncation is explicit in the return ("truncated": true) — never silent.

7. Credentials and profile requirements

Per-service profile model (gitea-execution-profiles.md, extended by #76):

• Env/config: GLITCHTIP_URL, GLITCHTIP_ORG, GLITCHTIP_TOKEN_SOURCE_NAME (secret name only; value resolved at runtime, never logged/committed).
• Profile: e.g. glitchtip-readonly with namespaced allowed_operations: ["glitchtip.read", "glitchtip.event.read"] (+ glitchtip.event.read_raw only with explicit approval); forbidden_operations: ["glitchtip.issue.mutate", "glitchtip.admin"] belt-and-braces though no mutating tool exists.
• Missing URL/org/token/profile ⇒ fail closed before any network call.
• Read-only ⇒ no confirmation gates; identity (glitchtip_whoami) must work so workflows can prove which account they read as.

8. Failure behavior (fail closed, clear, safe)

Condition	Behavior
Unknown project/issue	Explicit {"found": false, ...} — no fuzzy matching
GlitchTip unreachable (DNS/timeout)	"network error contacting GlitchTip: <redacted reason>" — mirror gitea_auth.api_request conversion
502/503/504	"GlitchTip upstream unavailable"
401/403	"GlitchTip auth failed / insufficient permissions" — no credential echo
429	Honor Retry-After with capped jittered backoff (as gitea_auth)
Malformed JSON	"malformed JSON response from GlitchTip" — no raw-body dump
Missing profile/creds	Fail closed before any network call (§7)

All error text passes the shared secret redactor.

9. Testing strategy (mocked; for the implementing package)

Mocked-GlitchTip unit tests only, per docs/developer-testing-guidelines.md:

• Assert method is always GET; URL/filter/cursor shape correct.
• Projection tests: response fixtures containing emails, IPs, cookies, headers, request bodies, locals, full frames ⇒ none appear in output (explicit negative assertions per §5's redact list).
• Stack summary: top-N frame cap enforced; source-context lines absent.
• Pagination: per-page/overall/max-pages caps; explicit truncated flag.
• Filters: environment/release/fingerprint/query passed through correctly.
• Failure matrix of §8 incl. no-token-in-error assertions.
• Profile gate: missing/insufficient profile ⇒ no network call (mock_api.assert_not_called() pattern).
• read_raw op absent ⇒ raw-frame request refused without an API call.

10. Implementation-readiness checklist

Ready to implement once:

1. ADR-0001 owner decision #2 (namespace/placement) is made — mechanical rename of the glitchtip_ prefix if needed.
2. ADR-0001 owner decision #1 (repo home) is made.
3. #76 profile schema exists (or a minimal glitchtip-readonly profile is hand-rolled to the same rules).
4. A pinned GlitchTip version is chosen for API-subset testing (§3).

Explicitly not unlocked by this document: any GlitchTip mutation, any automatic Gitea filing (#74 designs that as a gated, explicitly-invoked orchestrated workflow), any Gitea credentials in this boundary.