pal-e-docs

Review: gcal-mcp-remote — Add Woodpecker CI pipeline and k8s manifests

review-63-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

Compared against template-issue-feature:
  • [ ] ### Type — missing (defaults to Feature, acceptable)
  • [ ] ### Lineage — missing. References plan-2026-02-25-mcp-gateway-migration Phase 3, but uses non-standard "### Plan" header
  • [x] ### Repo — present: gcal-mcp-remote
  • [x] ### User Story — present and well-formed
  • [ ] ### Context — missing. "Additional Information" exists but doesn't explain WHY this work exists to a zero-knowledge reader
  • [ ] ### File Targets — missing entirely. No file paths listed for what the agent should create or modify
  • [x] ### Acceptance Criteria — present (2 criteria)
  • [ ] ### Test Expectations — missing. No test commands or expectations
  • [ ] ### Constraints — missing. Critical for this ticket because the repo layout differs from the reference pattern
  • [x] ### Checklist — present
  • [x] ### Related — present

Traceability

  • [x] story:superuser-onboard — present on board item
  • [x] arch:ci-pipeline — present on board item
  • [x] Forgejo issue — forgejo_admin/gcal-mcp-remote#3, open
  • [x] type:feature — present on board item

File Targets

No file targets listed in the issue. Based on the acceptance criteria and the notion-mcp-remote reference pattern, the following files would need to be created or modified:
  • [ ] .woodpecker.yaml — does NOT exist, needs creation
  • [ ] Dockerfile.k8s — does NOT exist, needs creation. ISSUE: current repo uses src package layout (src/gcal_mcp_remote/) not flat layout. Dockerfile.k8s from notion-mcp-remote uses requirements.txt + flat server.py — will NOT work as-is
  • [ ] requirements.txt — does NOT exist. Current repo uses pyproject.toml with src/ layout
  • [ ] k8s/deployment.yaml — does NOT exist, needs creation
  • [ ] k8s/service.yaml — does NOT exist, needs creation
  • [ ] k8s/pvc.yaml — does NOT exist, needs creation
  • [ ] k8s/servicemonitor.yaml — does NOT exist, needs creation
  • [ ] k8s/kustomization.yaml — does NOT exist, needs creation
  • [ ] src/gcal_mcp_remote/server.py — exists, needs /metrics endpoint added. Currently has PORT default 8001, needs change to 8000
  • [ ] pyproject.toml — exists, needs dev deps (ruff) added

Repo Placement

Correct — issue is filed on gcal-mcp-remote and work happens there. However, pal-e-deployments may also need an ArgoCD Application manifest for this service (not mentioned in scope). The sibling gcal-scheduler (board item #64, done) can be checked for how it was wired into ArgoCD.

Dependencies

  • Board item #64 (gcal-scheduler CI+k8s) is in done — no blocker
  • notion-mcp-remote (the reference pattern) is merged — no blocker
  • Harbor project for gcal-mcp-remote image must exist (not mentioned in scope)
  • Woodpecker repo secrets (harbor_username, harbor_password) must be configured (not mentioned)
  • ArgoCD Application pointing at k8s/ directory must exist or be created (not mentioned)

Acceptance Criteria

Two criteria exist but are incomplete:
  • CI criterion: "Woodpecker runs lint checks and builds a container image to Harbor" — testable via Woodpecker pipeline run, but missing: what lint tool? (ruff implied by pattern). No mention of ruff version pinning.
  • Deploy criterion: "deploys on port 8000 with health checks, PVC, and ServiceMonitor" — testable via kubectl, but missing: what health check path? What PVC size? What ServiceMonitor interval?
  • Missing criterion: No verification that /metrics endpoint actually returns Prometheus-compatible output

Blast Radius

CRITICAL: gcal-mcp-remote has a fundamentally different repo layout than notion-mcp-remote. The issue says "follows the proven pattern from notion-mcp-remote" but:
  • notion-mcp-remote: flat layout (server.py, requirements.txt, Dockerfile.k8s)
  • gcal-mcp-remote: src package layout (src/gcal_mcp_remote/server.py, pyproject.toml, no requirements.txt)
An agent blindly copying the notion-mcp-remote pattern will produce a broken Dockerfile. The Dockerfile.k8s must be adapted for the src layout, or the repo must be restructured to flat layout first.
The issue also references port change 8001 to 8000, but this is buried in "Additional Information" — an agent may miss it.

Decomposition

10 file targets across 1 repo, plus structural layout decisions. The layout mismatch alone makes this more than a 5-minute agent pass. However, if the scope is clarified (especially the layout question), it could be a single agent pass. Verdict: refine first, then single agent is acceptable.

Recommendation

Before moving to next_up:
  • Add File Targets section — list all files to create/modify with expected content summary
  • Add Constraints section — explicitly state whether to restructure to flat layout (like notion-mcp-remote) or adapt the Dockerfile for src layout
  • Add Context section — explain the layout difference from the reference pattern
  • Add Test Expectations — at minimum: ruff check passes, Docker build succeeds, k8s manifests apply cleanly
  • Clarify deployment dependencies — Harbor project, Woodpecker secrets, ArgoCD Application. Are these already in place or does the agent need to create them?
  • Specify /metrics endpoint details — what library? What format? Can reference notion-mcp-remote's implementation if it exists