pal-e-docs

Plan: Woodpecker SDK & MCP

plan-2026-02-28-woodpecker-sdk-mcp Plan

plan completed
Project

Vision

Professional, stable MCP tooling for every platform service, built on swagger-generated SDKs with pytest integration tests and PyPI pipelines. Eliminate raw API calls from agent sessions.

Projects & Repos Touched

Project/Repo Platform Role in this plan
woodpecker-sdk Forgejo Python SDK generated from swagger.json — 117 endpoints
woodpecker-mcp (new) Forgejo MCP server with workflow-level tools built on SDK (promoted to own plan)

Context

We currently make raw HTTP calls to Woodpecker CI in every session that touches CI/CD. This wastes 500-1000 tokens per interaction, has no type safety, no error handling, and no retry logic. The SDK-first pattern (swagger.json → SDK → MCP) is proven across 5+ services (notion, gmail, gcal, linkedin, forgejo). Woodpecker is the most-used platform service without an SDK.
What's already done:
  • [x] Swagger spec retrieved (117 endpoints, 22 tags)
  • [x] forgejo-sdk pattern documented and understood
  • [x] woodpecker-sdk repo created
  • [x] SDK generated — 117 endpoints, 18 mixin files (PR #2 merged)
  • [x] Integration tests — 70 tests with full response shape validation (PR #4 merged, 3 QA rounds)
  • [x] Forgejo PyPI registry configured for publishing
  • [x] Woodpecker CI pipeline for woodpecker-sdk (PR #6 merged, 3 QA rounds)

Previous Plan

None — originated from todo-woodpecker-mcp

Depends On

None

Decisions Made

Decision Rationale
Token auth (Bearer PAT), not basic auth Woodpecker uses personal access tokens, not username/password
Mixin-per-tag pattern Matches forgejo-sdk, keeps files manageable
SDK first, MCP second (separate plan) SDK must be stable and tested before building MCP on top
Project: Claude Config All SDK/MCP tooling lives under Claude Config, consistent with forgejo-sdk
Shared test schemas module Deduplicated Secret/Registry/User schemas into tests/schemas.py across 6 test files
Dual httpx clients Root-level endpoints (/version, /healthz) served outside /api — SDK uses _root_client
Publish to Forgejo package registry, not Harbor or public pypi.org Harbor does NOT support PyPI registries (OCI artifacts only, confirmed via <a href="https://github.com/goharbor/harbor/discussions/19381">goharbor/harbor#19381</a>). Forgejo has a <a href="https://forgejo.org/docs/latest/user/packages/pypi/">built-in PyPI registry</a> — already enabled on our instance, zero new infrastructure, publish via twine, install via pip, all within Tailnet. 22 packages already leaked to public PyPI (can't delete, PEP 763). Going forward, all packages self-hosted on Forgejo. See <code>todo-forgejo-pypi</code> for migration of existing packages.
Ruff config in pyproject.toml Keep all config colocated. No standalone ruff.toml.
Manual version bumping (for now) Edit version in pyproject.toml by hand. Automate later (tag-based release) once the pipeline pattern is proven across multiple repos.
Integration tests run in CI The SDK has 70 integration tests against live Woodpecker — run them in CI via secrets. Catches regressions against the real API. Worth the CI time.
Reuse Forgejo admin PAT for publishing No need for a dedicated publishing token. Admin PAT already exists in secrets, works for twine upload.

Phases

Phase 1 — Generate SDK from swagger.json ✅ COMPLETED

Slug: phase-2026-02-28-1-generate-sdk
Goal: Create woodpecker-sdk repo with full 117-endpoint coverage generated from swagger.json, following the forgejo-sdk mixin pattern.
Owner: Agent
Issue: issue-woodpecker-sdk-initial (resolved), issue-woodpecker-sdk-integration-tests (resolved)
Deliverables:
  • PR #2 — Initial SDK: 117 endpoints, 18 mixin files, 33 smoke tests (merged)
  • PR #4 — Comprehensive integration tests: 70 tests with response shape validation against swagger schemas, shared schemas module (merged, 3 QA rounds)
  • Woodpecker PAT saved to ~/secrets/woodpecker/credentials.env

Phase 2 — Forgejo PyPI registry + Woodpecker CI pipeline ✅ COMPLETED

Slug: phase-2026-02-28-2-pypi-pipeline
Goal: Configure Forgejo's built-in PyPI registry for package publishing, then create a Woodpecker CI pipeline for woodpecker-sdk that lints, tests, builds, and publishes to Forgejo. This establishes the reusable pipeline pattern for all future SDK/MCP repos.
Owner: Agent
Issue: issue-woodpecker-sdk-pypi-pipeline (resolved)
Deliverables:
  • PR #6 — Woodpecker CI pipeline + Forgejo PyPI publishing (merged, 3 QA rounds)
  • .woodpecker.yml — 3-step pipeline: lint (ruff==0.15.2), test (pytest with live Woodpecker), publish (build + twine upload to Forgejo, main-only)
  • pyproject.toml — ruff config added (py310, line-length 120, E/F/W/I rules)
  • ~/.pypirc configured with Forgejo registry
  • Woodpecker secrets configured: repo-level (woodpecker_url, woodpecker_token), global (forgejo_publish_user, forgejo_publish_token, forgejo_pypi_url)
  • v0.1.0 published to Forgejo PyPI and installable via pip install
  • Ruff format fixes applied across 15 source/test files (mechanical, no logic changes)

Phase 3 — Woodpecker MCP ➔ Promoted to own plan

Slug: phase-2026-02-28-3-mcp
Goal: MCP server with curated workflow-level tools built on SDK.
Promoted to: plan-2026-02-28-woodpecker-mcp
Depends on: Phase 2 ✅ (SDK is now on Forgejo PyPI)
Phase 3 was promoted to its own plan because the research and design work produced enough detail for a full plan: three-tier tool coverage model, 12 compound workflow tools designed, forgejo-mcp reference pattern studied, key architectural decisions made. See the new plan for full detail.

Key Files

Phase File Repo Change
1 swagger.json woodpecker-sdk Source spec
1 src/woodpecker_sdk/client.py woodpecker-sdk BaseClient + WoodpeckerClient (dual httpx clients)
1 src/woodpecker_sdk/*.py woodpecker-sdk 18 mixin files
1 tests/schemas.py woodpecker-sdk Shared schema constants (Secret, Registry, User)
1 tests/test_*.py woodpecker-sdk 18 test files, 70 tests with response shape validation
1 pyproject.toml woodpecker-sdk Package config
2 .woodpecker.yml woodpecker-sdk CI pipeline: lint, test, publish to Forgejo
2 pyproject.toml woodpecker-sdk Add ruff config section
2 ~/.pypirc local machine Forgejo PyPI registry config for twine
2 Woodpecker secrets Woodpecker UI/API Forgejo publish creds (global), Woodpecker PAT (repo-level for tests)

Verification

  • [x] pytest tests/ passes against live Woodpecker instance (65 pass, 5 skip)
  • [x] All 18 tag groups have corresponding mixin + test file
  • [x] pip install -e . works
  • [x] Can instantiate WoodpeckerClient and list repos
  • [x] Forgejo package registry accepts twine upload
  • [x] pip install ldraney-woodpecker-sdk resolves from Forgejo
  • [x] Push to branch triggers lint + test in Woodpecker CI
  • [x] Merge to main triggers build + publish to Forgejo
  • [ ] Pipeline is reusable template for other SDK/MCP repos

Next Plan Seeds

  • woodpecker-mcp — promoted to plan-2026-02-28-woodpecker-mcp
  • forgejo-mcp audit — compare existing forgejo-sdk/mcp against this pattern
  • Forgejo PyPI migration — move existing 22 public PyPI packages to Forgejo (todo-forgejo-pypi)
  • Reusable .woodpecker.yml template — extract pipeline pattern for all Python repos
  • plan-2026-02-28-woodpecker-mcp — child plan (Phase 3 promoted, dependency now satisfied)
  • todo-woodpecker-mcp — originating TODO
  • todo-forgejo-mcp-audit — companion audit
  • todo-forgejo-pypi — migrate all 22 public packages to Forgejo
  • todo-ruff-standardization — ruff config across all Python repos
  • forgejo-sdk — reference implementation
  • service-onboarding-sop — container images still go to Harbor, Python packages go to Forgejo