mcp-nextcloud/docs/ADR-029-pact-contract-testing.md

ADR-029: Pact contract testing with astrolabe

Status

Accepted — 2026-06-10

Context

nextcloud-mcp-server (Python/FastMCP) and the astrolabe Nextcloud app (PHP) integrate over HTTP in both directions:

• MCP server → astrolabe (one call): the background vector-sync reads a user's provisioning status via GET /apps/astrolabe/api/v1/background-sync/credentials/{user_id} (nextcloud_mcp_server/auth/astrolabe_client.py). This returns status only — {success, user_id, has_background_access, sync_type, provisioned_at}, always HTTP 200, and never the password. The app password itself flows the other way: astrolabe pushes it to the MCP server's /api/v1/users/{uid}/app-password.
• astrolabe → MCP server (~10 calls): astrolabe's McpServerClient consumes this server's /api/v1/* HTTP API — status, vector-sync/status, search, vector-viz/search, webhooks (GET/POST/DELETE), apps, chunk-context, pdf-preview (nextcloud_mcp_server/app.py route table, api/webhooks.py).

Today nothing guarantees the two stay wire-compatible. A renamed JSON field or a changed status code on either side is only caught — if at all — by the heavy integration matrix (docker-compose, real Nextcloud, minutes per run). We want a fast, focused signal that fails the moment the contract drifts, runnable in unit-style CI on either repo independently.

Decision

Adopt consumer-driven contract testing with Pact, with a self-hosted Pact Broker in the homelab as the system of record. GitHub Actions reach the broker over Tailscale (the broker is not publicly exposed).

Because the integration is bidirectional, each repo plays both Pact roles:

Contract	Consumer	Provider	Consumer tooling	Provider tooling
credentials API	nextcloud-mcp-server	astrolabe	pact-python	pact-php verifier
/api/v1/* API	astrolabe	nextcloud-mcp-server	pact-php	pact-python Verifier

This repo (Python side)

• pact-python (v3 API, from pact import Pact, Verifier, match) is a dev dependency.
• Contract tests live under tests/contract/ behind a contract pytest marker, kept out of the default unit run.
  • Consumer (test_astrolabe_credentials_consumer.py): drives the real AstrolabeClient against a Pact mock server, pinning the request shape and the two status responses it branches on — provisioned (has_background_access: true, sync_type: "app_password", integer provisioned_at) and unprovisioned (has_background_access: false). The OAuth token fetch is stubbed so only the credentials call is exercised. Interactions merge into tests/contract/pacts/ (git-ignored — pacts are published to the broker, not committed).
  • Provider (test_mcp_provider_verification.py): a Verifier harness that replays astrolabe's published pacts against a running MCP server. It is environment-gated (PACT_PROVIDER_URL + a pact source) so it skips in the consumer-only job and in local runs. Provider-state handlers are registered by given(...) string in _PROVIDER_STATES and filled in as astrolabe publishes its consumer pacts; unknown states no-op so state-less interactions (/api/v1/status, /api/v1/vector-sync/status) verify immediately.

CI (.github/workflows/pact.yml)

Three jobs, each joining the tailnet with the shared tag:github-runner OAuth client before touching the broker:

1. consumer — generate pacts, publish to the broker tagged with the branch and commit SHA.
2. provider — stand up the MCP server (single-user compose profile), verify astrolabe's pacts against it, publish verification results (master only).
3. can-i-deploy — gate master on pact-broker can-i-deploy … --pacticipant nextcloud-mcp-server --to-environment production.

Broker-dependent steps are skipped when PACT_BROKER is unset (forks).

Infrastructure (other repos / sessions)

• Broker: pactfoundation/pact-broker deployed via ArgoCD (homelab-argocd), backed by the shared Zalando Postgres, reachable at pact-broker.internal.coutinho.io. Single basic-auth credential from AWS Secrets Manager via external-secrets.
• CI access: jobs join the tailnet (tag:github-runner) and reach the broker via the PACT_BROKER secret (its Tailscale host). No new Terraform is required.

Required secrets (this repo)

TS_OAUTH_CLIENT_ID, TS_OAUTH_SECRET (Tailscale github-runner OAuth client), PACT_BROKER (base URL), PACT_USERNAME, PACT_PASSWORD (broker basic auth).

Consequences

• Fast, independent signal: either side detects an incompatible change in a ~seconds-long job instead of waiting on the integration matrix.
• Participant names are load-bearing: the consumer/provider names (nextcloud-mcp-server, astrolabe) must match exactly across both repos and the broker. They live in tests/contract/conftest.py here and must mirror the astrolabe pact tests.
• Provider states are deferred work: the /api/v1/* provider verification is only as complete as the state handlers that seed its backends (webhooks DB, Qdrant). These land incrementally as astrolabe publishes its consumer pacts.
• Broker is a homelab dependency: contract publication/verification needs the tailnet and the broker up. Steps degrade to skipped (not failed) when the broker is unreachable from a fork; on master an outage will fail can-i-deploy.