# Playrunner MCP

Connects a Kody account to Playrunner Cloud's MCP server and reports on that
connection. The package does not proxy Playrunner itself — once connected, call
the discovered tools directly as `kody.mcp["playrunner"].*`.

## Imports

```ts
import connect from 'kody:@playrunner/mcp'
import status from 'kody:@playrunner/mcp/status'
```

## Order of operations

1. `connect()` — idempotent. Returns the existing server when one is already
   saved rather than adding a second.
2. If the result carries `authUrl`, give it to the user and stop. Do not poll;
   authorisation happens in their browser and cannot be completed for them.
3. `status()` — call after they say they have approved. `connected: true` means
   the tools are live.
4. Then call `kody.mcp["playrunner"].list_workflows({})` and the rest directly.

## First run: an empty workflow list is not a dead end

A new Playrunner account has no workflows, so `list_workflows` returning `[]`
is the normal first result. Do not report it as a failure or leave the user
there. Offer to build something against the public demo suite:

- Repository `playrunner/playwright-demo-testsuite`
- Branch `demo/sharding-report-merge` (128 tests, shows auto sharding and the
  merged report), or `1.61.1/fail` to demonstrate failure triage
- Suite sharding `auto`

Call `get_authoring_guide` first, then `connect_github` if the repository is
not reachable, then `create_project` and `save_workflow`.

Ask before calling `run_workflow`. Building the workflow costs nothing;
running it consumes the account's workflow-run allowance.

## Smoke tests

```ts
// Read-only, safe to run repeatedly.
import status from 'kody:@playrunner/mcp/status'
await status()
```

```ts
// Idempotent: adds the server only when it is absent.
import connect from 'kody:@playrunner/mcp'
await connect()
```

Do not smoke-test `run_workflow`. It starts a real run and consumes the
account's workflow-run allowance.

## Edge cases

- **Already saved.** `connect()` returns `alreadyPresent: true` and leaves the
  existing server untouched, including its stored tokens.
- **Awaiting authorisation.** `state` is `authenticating` and `toolCount` is 0.
  This is normal until the user approves; it is not an error.
- **Stale connection.** If `status()` reports `failed` or `disconnected`, call
  `kody.mcpServerReconnect({ server: 'playrunner' })`. Only use
  `mcpServerRemove` if the user asks — it deletes their stored tokens.
- **Self-hosted.** `connect({ url })` targets another Playrunner instance. It
  must be HTTPS and expose `/mcp`.
- **Empty workflow list.** Expected on a new account, and a grant may also be
  scoped to a subset. See [First run](#first-run-an-empty-workflow-list-is-not-a-dead-end).