docs: GlitchTip read-only error/event tools design (#73) #93

2026-07-02T14:23:49-05:00

jcwalker3 commented

2026-07-02 14:23:49 -05:00

Implements #73. Design documentation only — no implementation, no mutation tools, no code changes.

Adds docs/architecture/glitchtip-readonly-tools-design.md (alongside ADR-0001 and the Jenkins design docs).

What it covers (per #73 acceptance criteria)

Minimum read-only tool set: glitchtip_whoami, glitchtip_list_projects, glitchtip_list_unresolved, glitchtip_get_issue, glitchtip_recent_events, glitchtip_search. All GET-only.
Privacy — field-level allowlist (core rule): allowlist projection only, never raw payload passthrough. Explicit never-returned list: request headers, cookies, auth/session fields, emails/usernames/IPs, request/form bodies, query strings, locals, full raw stack frames, breadcrumbs, extra/context blobs.
Default output = fingerprint / release / error summary + permalink — link, not dump. Raw frames gated behind a distinct, approval-only glitchtip.event.read_raw operation (mirrors jenkins.console.read pattern), still redactor-passed.
Filtering: environment, release, fingerprint, project, free-text query. Pagination bounds: per-page 50, overall 100 default, max-pages cap, explicit truncated flag — never silent.
Normalized return fields defined per tool (issue-level + event-level tables; stack summary = top-N module:function:line).
Credentials/profile: own boundary + .env, token by reference (GLITCHTIP_TOKEN_SOURCE_NAME), namespaced allowed_operations, fail closed; no Gitea write credentials in this server.
Failure behavior: not-found (no fuzzy match), unreachable, 5xx, 401/403, 429 backoff, malformed JSON — all safe + redacted.
Namespace: deliberately left to ADR-0001 open owner decision #2 (glitchtip-mcp / observability-mcp / ops-mcp); mechanical rename.
Sentry-compat note, mocked testing strategy with explicit negative-PII assertions, and an implementation-readiness checklist.

Checks

py_compile mcp_server.py / manage_labels.py / gitea_auth.py — OK
bash -n scripts/clear-provenance — OK
git diff --check — clean
pytest tests/ -q — 355 passed
Secret sweep (staged diff; no repo scanner) — clean

Scope

One new Markdown file. Untouched: PR #89/#79 and PR #90/#80 (other LLM), PR #64/#63 release, #65/#66, all code.

🤖 Generated with Claude Code

Implements #73. Design documentation only — **no implementation**, no mutation tools, no code changes. Adds `docs/architecture/glitchtip-readonly-tools-design.md` (alongside ADR-0001 and the Jenkins design docs). ## What it covers (per #73 acceptance criteria) - **Minimum read-only tool set:** `glitchtip_whoami`, `glitchtip_list_projects`, `glitchtip_list_unresolved`, `glitchtip_get_issue`, `glitchtip_recent_events`, `glitchtip_search`. All `GET`-only. - **Privacy — field-level allowlist (core rule):** allowlist projection only, never raw payload passthrough. Explicit never-returned list: request headers, cookies, auth/session fields, emails/usernames/IPs, request/form bodies, query strings, locals, full raw stack frames, breadcrumbs, extra/context blobs. - **Default output = fingerprint / release / error summary + permalink** — link, not dump. Raw frames gated behind a distinct, approval-only `glitchtip.event.read_raw` operation (mirrors `jenkins.console.read` pattern), still redactor-passed. - **Filtering:** environment, release, fingerprint, project, free-text query. **Pagination bounds:** per-page 50, overall 100 default, max-pages cap, explicit `truncated` flag — never silent. - **Normalized return fields** defined per tool (issue-level + event-level tables; stack summary = top-N `module:function:line`). - **Credentials/profile:** own boundary + `.env`, token by reference (`GLITCHTIP_TOKEN_SOURCE_NAME`), namespaced `allowed_operations`, fail closed; **no Gitea write credentials in this server**. - **Failure behavior:** not-found (no fuzzy match), unreachable, 5xx, 401/403, 429 backoff, malformed JSON — all safe + redacted. - **Namespace:** deliberately left to ADR-0001 open owner decision #2 (`glitchtip-mcp` / `observability-mcp` / `ops-mcp`); mechanical rename. - **Sentry-compat note**, mocked testing strategy with explicit negative-PII assertions, and an implementation-readiness checklist. ## Checks - `py_compile mcp_server.py` / `manage_labels.py` / `gitea_auth.py` — OK - `bash -n scripts/clear-provenance` — OK - `git diff --check` — clean - `pytest tests/ -q` — 355 passed - Secret sweep (staged diff; no repo scanner) — clean ## Scope One new Markdown file. Untouched: PR #89/#79 and PR #90/#80 (other LLM), PR #64/#63 release, #65/#66, all code. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jcwalker3 added 1 commit 2026-07-02 14:23:49 -05:00

docs: GlitchTip read-only error/event tools design (#73 ) 079eb60e30

Add docs/architecture/glitchtip-readonly-tools-design.md: implementation-
ready design for the GlitchTip observability boundary's read-only tool set —
minimum tools (whoami, list_projects, list_unresolved, get_issue,
recent_events, search; GET-only), field-level allowlist projection with an
explicit never-returned list (headers, cookies, auth fields, emails, IPs,
bodies, locals, raw frames), default fingerprint/release/summary+permalink
output, raw access gated behind a distinct approval-only
glitchtip.event.read_raw operation, cursor pagination with explicit
truncation flags, per-service credential/profile requirements (token by
reference, fail closed), Sentry-compat API subset note, fail-closed failure
matrix, mocked testing strategy with negative PII assertions, and a
readiness checklist. Namespace left to ADR-0001 owner decision #2.

Design only; no implementation, no mutation tools, no code behavior changed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sysadmin merged commit fac10dd6cc into master

2026-07-02 14:27:09 -05:00

jcwalker3 referenced this issue from a commit

2026-07-02 14:47:34 -05:00

chore: add #73/#76/#79/#80 docs merges to v1.1.0 release notes (#63)

jcwalker3 referenced this pull request

2026-07-02 16:01:42 -05:00

MCP Control Plane umbrella: Jenkins + GlitchTip integrations #75

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#93