@playrunner/mcp

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

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

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

// 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.