API, CLI and MCP

Developer preview — live acceptance pending

One authenticated API serves every client. The PowerShell script and the MCP server are thin clients over it: they never evaluate policy and never decide clearance. They read the decision The Warden already recorded for the exact build.

• Transport: Forge App REST APIs with Atlassian OAuth 2.0 (3LO) and the custom scopes below. A site administrator opts in to App REST APIs first.
• Identity: the signed-in Jira user. Reads need a current Jira role of tester or higher and an active repository grant for that user.
• Targeting: repository and commit are inferred from your Git workspace. Without a commit, the latest indexed change for the repository is used and the response is marked inferredTarget. An explicit commit that matches several builds is refused rather than guessed.
• Access, the base URL and tokens are provisioned during pilot onboarding. See Onboarding and Permissions.

GET query parameters for the four decision reads: repositoryRef (owner/repo), optional 40-character commitSha and optional environmentRef. The plan read takes repositoryRef, targetType (branch, jira_issue or change_set), targetId, and optionally contractName and expectedCommitSha. The plan never generates policy and never returns clearance. Responses are capped at 64 KiB.

Requires Windows PowerShell 5.1 or PowerShell 7, and Node.js 24 on the path. Configure the base URL (the exact HTTPS Forge App REST URL listed in Atlassian Connected apps; webtrigger URLs are not accepted) and the token:

$env:TESTWARDEN_API_BASE_URL = "<exact HTTPS base URL from Connected apps>"
$env:TESTWARDEN_OAUTH_ACCESS_TOKEN = "<short-lived user access token>"   # or use -SecretName

# From inside your Git checkout; repository and commit are inferred
.\scripts\testwarden.ps1 status
.\scripts\testwarden.ps1 obligations
.\scripts\testwarden.ps1 evidence
.\scripts\testwarden.ps1 explain

# Canonical JSON, unaltered
.\scripts\testwarden.ps1 explain -Format json

# Token from a PowerShell SecretManagement vault instead of the environment
.\scripts\testwarden.ps1 status -SecretName TestWardenOAuth

# Before coding: the configured obligations for your branch
.\scripts\testwarden.ps1 plan

Commands: status, obligations, evidence, explain and plan. Parameters: -Repository, -Commit, -Environment, -TargetType, -TargetId, -ContractName, -Format (compact or json) and -SecretName. Optional environment overrides: TESTWARDEN_REPOSITORY, TESTWARDEN_COMMIT_SHA, TESTWARDEN_ENVIRONMENT, TESTWARDEN_BRANCH and TESTWARDEN_FORMAT=json. The script restores your original environment on exit.

Expected output

In compact mode a fresh CLEARED status prints nothing, so a clean state is silent. HELD prints the failure, the CI assertion link when one is available, the next action and what to verify:

HELD: JUnit completed run: 4 test observations; 1 failed, 0 error, 0 skipped. Not passed: failed: payment > declines an expired card.
CI assertion: https://github.com/acme/checkout-service/actions/runs/1000000002/attempts/1
Next: resolve_failing_evidence
Verification: Run fresh CI for this exact new commit; the Warden evaluates independent evidence.

A standard MCP stdio server for VS Code, Claude Code, Codex and other MCP clients. It speaks newline-delimited JSON-RPC, negotiates protocol versions 2025-06-18 and 2025-11-25, and supports initialize, ping, tools/list and tools/call. All stdout is protocol JSON.

{
  "mcpServers": {
    "testwarden": {
      "command": "node",
      "args": ["/path/to/testwarden/scripts/testwarden-mcp.mjs"],
      "cwd": "/path/to/your/git/checkout"
    }
  }
}

1. Point args at scripts/testwarden-mcp.mjs and set cwd to your Git checkout so the repository and commit are inferred.
2. Supply TESTWARDEN_API_BASE_URL and TESTWARDEN_OAUTH_ACCESS_TOKEN through your launcher's secured process environment, never in the config text and never in tool arguments.
3. Ask the agent to call warden.status or quality.explain.

The tools are typed and bounded: warden.status, verification.obligations, verification.plan.get, evidence.list, quality.explain and verification.run.request. Five are read-only. There is no shell, SQL, clearance or approval tool, and tool arguments are limited to 4 KiB. A tool call that is refused returns an error result with a short code instead of remote text.

Download the entry: mcp-config.json.

Every successful result carries schemaVersion: 1, a source of canonical_warden (or the plan source), the exact target (repository, commit, build, environment) and the canonical decision id. States use the API spelling CLEARED, VERIFYING, HELD, NEEDS_APPROVAL and INCOMPLETE.

quality.explain returns mode: "deterministic" and modelInvoked: false: the summary, failed requirement, assertion link and suggested remedies come from recorded evidence and fixed next actions. For a CLEARED change it is quiet (quiet: true, empty summary). Managers can also receive a decision-pinned diagnosis. See AI and data handling for the optional AI explanation.

Full HELD example: explain-response.json.

The PowerShell client prints TestWarden: <code> and exits non-zero. Common codes:

• Approved rerun requests. verification.run.request and rerun exist in the clients but no dispatcher is installed, so the service answers 503 (rerun_unavailable). When enabled it requires the manager role, entitlement and a separately human-approved run, and it returns REQUESTED with progressionAllowed: false, never CLEARED.
• Repair adapters, autonomous repair, customer-authored contracts and live provider connectors are not part of this surface.

Related tasks

• Onboarding

  Choose a path, enable access, confirm the first change appears.

• CI evidence

  Submit JUnit, SARIF or JSON and gate on the exact build.

• Decisions and approvals

  States, reason codes, next actions and preserved history.

• Permissions

  Roles, custom scopes and who can read, write or request.

• AI and data handling

  What is optional, what is consented and what never changes a decision.