# WebinarIgnition — Agent & API guide

Canonical URL on a site: `https://YOUR-SITE/llms.txt`
(served by WebinarIgnition; do not fetch the file from wp-content/plugins/).

WebinarIgnition exposes a small, capability-scoped agent surface so AI
assistants can list, read, create, and (with confirmation) publish webinars.
Every action a machine can take is limited to what a `manage_options` admin
could do by hand. All writes are snapshotted and audited.

AI keys: Inclusive allowance may use a server-side WI Perplexity key
(`WI_PERPLEXITY_API_KEY`). Hosts can extend via WordPress
Settings → Connectors (Anthropic / Claude).

## Connect (MCP) — the default door

Connect any MCP-capable assistant (Claude, ChatGPT, Cursor, …) to:

    POST /wp-json/wi-mcp/v1/mcp

- **JSON-RPC 2.0** over Streamable HTTP, MCP protocol **2025-06-18**.
- **Auth: OAuth 2.0 bearer token**, issued by this same site. The server
  advertises its metadata at:
  - `/.well-known/oauth-protected-resource` (RFC 9728)
  - `/.well-known/oauth-authorization-server` (RFC 8414)
- Methods: `initialize`, `tools/list`, `tools/call`, `ping`.
- No Application Password needed.

## Where the tools come from

1. **WordPress Abilities** (Core 6.9+) named `webinarignition/*` with
   `meta.public === true`, registered on `wp_abilities_api_init`. This is the
   canonical list — one place declares what WebinarIgnition can do, and both
   the official WordPress `mcp-adapter` and this endpoint read it. Abilities
   are therefore also visible through the WordPress/mcp-adapter.
2. On cores without the Abilities API, the **Capability Kernel** registry.

Two locks: the bearer token gets the caller in, and every ability's own
`permission_callback` plus the kernel's `manage_options` and scope checks
decide what may actually run.

## Legacy MCP route (off by default)

The older MCP route speaks protocol **2024-11-05**, authenticates with a
WordPress **Application Password**, and has been **off by default since
4.18.95**. Turn it on deliberately, only when needed (cores older than 6.9):

    POST /wp-json/wi/v1/agent/mcp        // JSON-RPC 2.0 (Streamable HTTP)
    define( 'WI_MCP_LEGACY_ROUTE', true );                    // wp-config.php
    add_filter( 'wi_mcp_legacy_route_enabled', '__return_true' );

## Direct HTTP (Application Password, manage_options) — active

- `GET  /wp-json/wi/v1/agent/tools` — list available tools (name, scope, args).
- `GET  /wp-json/wi/v1/agent/webinars` — list webinars. Optional `?limit=`.
- `GET  /wp-json/wi/v1/agent/webinars/{id}` — get one webinar summary.
- `POST /wp-json/wi/v1/agent/plan` — body `{ "intent": "..." }`.
      Returns a structured plan. Writes nothing.
- `POST /wp-json/wi/v1/agent/apply` — body `{ "plan": {...}, "confirm": true }`.
      Executes a plan. `confirm` must be `true`.
- `POST /wp-json/wi/v1/agent/invoke` — body `{ "tool": "...", "args": {} }`.
      Invoke a single tool directly (canonical HTTP substrate).

## Tool scopes

- `read` — safe, no writes (e.g. `wi_list_webinars`, `wi_get_webinar`).
- `content` — creates/edits content (e.g. `wi_create_webinar`,
  `wi_update_settings`).
- `control` — changes live state (e.g. `wi_master_switch`). Requires explicit
  confirmation; the host can grant this once, permanently, when connecting, and
  it is otherwise demanded on every call. No plan of its own: whatever the host
  may click in wp-admin, an AI acting for them may do. The limits that do apply
  are the ones on the feature itself — the watch-time cap on the built-in room.

## Recommended flow

**MCP hosts (Claude, ChatGPT, Cursor, …):**

1. Authorize via OAuth (metadata above), then call `POST /wp-json/wi-mcp/v1/mcp`.
2. `initialize` → `tools/list` → loop: `tools/call` → read result → next call.
   (On cores older than 6.9 the same endpoint serves the Capability Kernel tools.)

**HTTP / in-plugin:**

1. `POST /agent/invoke` with `wi_preview_plan` `{ "intent": "..." }` (or legacy `/agent/plan`).
2. Show the plan to the user.
3. `POST /agent/invoke` with `wi_apply_plan` `{ "plan": {...}, "confirm": true }` (or legacy `/agent/apply`).

Macro: `wi_quick_create` = preview + apply in one confirmed call.

## Inclusive AI tokens

Each license includes a generous allowance of AI compute units for built-in
generation. When the allowance is exhausted, add your own provider API key
(BYOK) under WebinarIgnition Settings to keep generating.