Developer Resources — LIYANS MCP

Talk to the endpoint

Initialise, list the tools your credential may see, then call one:

POST /wp-json/liyans-mcp/v1/mcp
Authorization: Bearer lym_…

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
  "protocolVersion":"2025-11-25","capabilities":{},
  "clientInfo":{"name":"my-client","version":"1.0"}}}

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"liyans_site_inspect","arguments":{}}}

Batch arrays are processed item by item in order; notifications inside a batch are skipped; a batch of only notifications answers HTTP 202 with no body. Unknown methods answer -32601, malformed JSON answers -32700 with HTTP 400, and invalid parameters answer -32602 — behaviour verified against a real WordPress REST layer.

Clients speaking the 2026-07-28 revision skip the handshake entirely: they call server/discover and negotiate per request through params._meta, under SEP-2243 header validation, and receive resultType envelopes. The legacy flow above is unchanged, and the modern profile can be switched off in Settings.

The error contract

Tool execution failures are MCP tool results with isError: true and a machine-readable code from a closed catalogue of 27. The catalogue only grows by release, never ad hoc, and every code carries a safe human-readable detail pattern. Highlights:

not_foundinsufficient_scopeaccess_denieddependency_missingvalidation_failedinvalid_paramssession_not_foundsession_closedinvalid_clientinvalid_grantunsupported_grant_typeinvalid_scope

Shown: a selection. The full catalogue lives in includes/class-errors.php in the source archive.

Extension points

Point	What it does
`liyans_mcp_render_check_provider` filter	Lets a site inject its own visual data into `liyans_render_check` results — the supported way to extend verification without forking the core.
Adapters	Elementor, HTML conversion, WooCommerce and SEO each live behind an adapter class in `includes/adapters/`; tool handlers in `includes/tools/` never talk to third-party APIs directly.
Tool registry	`tools/list` is generated from the registry and filtered by the caller’s scopes — new tools declare their schema, their scopes and their capability checks in one place.
Settings sub-keys	Devices, OAuth records and build sessions persist inside the settings option by design, so the uninstall inventory stays small and provable: two tables, four options.

Source layout

liyans-mcp.php            plugin header, constants, activation hooks
uninstall.php             removes plugin options and tables only
includes/
  class-mcp-server.php    JSON-RPC / MCP protocol dispatcher
  class-rest-controller.php  REST transport, OAuth routes, discovery
  class-tool-registry.php catalogue, scope filtering, capability checks
  class-errors.php        the closed error catalogue
  class-auth.php          tokens, identity, capability intersection
  class-oauth.php         OAuth 2.1 authorisation server
  class-client-registry.php  known-client registry behind the AI Clients screen
  class-rate-limit.php    abuse-protection rate limiting
  class-snapshots.php     snapshot / restore
  class-logger.php        local audit log
  adapters/               Elementor, HTML converter, WooCommerce, SEO
  tools/                  the 61 tool definitions and handlers
  admin/                  the eight wp-admin screens

How the project tests

Two tiers, both shipped with the source: a pure-PHP harness that stubs the WordPress API and exercises the protocol dispatcher, the OAuth state machine and the storage inventory; and integration and acceptance runs against a real WordPress driving the endpoint over real HTTP — the 1.3.0 run used WordPress 7.1.4 with Elementor, WooCommerce, Yoast SEO, Contact Form 7 and WPForms Lite installed, and the 1.4.0 acceptance run repeated the identical 61-tool matrix against 1.3.1 and 1.4.0, added an upgrade-preservation test (the exact pre-upgrade token, device, session and settings carried across), and ran dedicated protocol, OAuth and rate-limit suites. What a run did not cover is listed in its report under NOT VERIFIED — see documents 05 and 11 and the Stage 2 acceptance report in the documentation archive. Contributions that claim a test must show it ran.

Licence