WP Copilot
Search… /
Wrap-up

Course Recap: A Debugging Checklist for MCP Adapter Issues

⏱ 11 min

Seven lessons, one workflow, and a handful of real, citable bugs later, this last lesson is a single reference you can come back to the next time something doesn’t register, doesn’t validate, or doesn’t show up where you expected. Nothing new is introduced here, it’s the checklist form of everything already covered, in the order you should actually run through it.

What you'll learn in this lesson
The full checklist, in run order
From first reproduction to confirmed fix, one list.
Every real issue cited in this course, in one place
For quick lookup the next time a symptom matches one of them.
What to do when none of this explains your specific failure
How to file a useful report instead of a vague one.
Where this course fits in the wider track
What to go build or secure next.
Prerequisites

All seven previous lessons in this course. This lesson doesn’t introduce new mechanisms, it’s a reference built entirely from what came before.

Step 1: The checklist, in run order

1. Reproduce with wp eval, not through an AI client
Removes the client and the model from the loop (Lesson 1).
2. Turn on WP_DEBUG and WP_DEBUG_LOG, check debug.log
_doing_it_wrong() notices are invisible without it (Lessons 1 and 2).
3. Confirm the ability is registered at all
wp_has_ability() / wp_get_ability(), before touching permission or execution (Lesson 1).
4. Check hook and timing
wp_abilities_api_init, attached early enough, not nested behind a late hook (Lessons 2 and 4).
5. Check for a duplicate name
wp_get_abilities() for an existing key under the same name (Lesson 2).
6. Check every required argument is present, category especially
And that the category itself was actually registered (Lessons 2 and 3).
7. If another large plugin is involved, check the boring cause first
Issue #135 looked like a WooCommerce conflict and was a missing category (Lesson 3).
8. Check input_schema is explicitly typed, not a bare array()
Issue #35's exact failure mode (Lesson 5).
9. Check your adapter version if empty {} arguments fail validation
Issue #116, fixed in v0.5.0 (Lesson 5).
10. Confirm with MCP Inspector, not just one client
Rule out a client-specific quirk before blaming your WordPress code (Lesson 6).
11. Read the adapter's error handler output
ErrorLogMcpErrorHandler by default, a custom one for a queryable record (Lesson 7).

Step 2: Every real issue cited in this course

Keep these numbers, they’re the fastest way to check whether your exact symptom has already been diagnosed by someone else:

Issue #135
wp_register_ability returns NULL, reported as a suspected WooCommerce registry conflict, actually a missing category argument. Resolved via PR #224 (documentation).
Issue #35
Abilities with a bare, untyped empty input_schema behave inconsistently across clients, failing tool registration in Cursor. Resolved via PR #36.
Issue #116
Empty object {} call arguments fail the input validator with "input is not of type object," due to PHP decoding {} as an empty array. Resolved in v0.5.0 via AbilityArgumentNormalizer.
Search the mcp-adapter issue tracker directly before assuming your bug is novel

All three of these were found, diagnosed, and fixed by real people hitting the same wall you might be hitting. Before spending an afternoon on a workaround, search github.com/WordPress/mcp-adapter/issues for your specific error message, there’s a reasonable chance it’s already a closed issue with a real answer, exactly like the three cited throughout this course.

Step 3: When none of this explains your failure

If you’ve worked through the full checklist and you’re still stuck, the most useful thing you can do next is turn your reproduction from Lesson 1 into a report someone else can act on immediately. A good report includes, at minimum: the exact wp_register_ability() call (or a minimal version reproducing the same shape), your WordPress, MCP Adapter, and any relevant plugin (like WooCommerce) versions, the exact wp eval output showing registration succeeded or failed, and the exact wp-content/debug.log lines from a request with WP_DEBUG_LOG on. That’s precisely the shape of information that made issue #135 solvable in a handful of comments instead of staying open indefinitely, several separate people confirmed the same fix against the same reproduction steps.

A vague report gets a vague answer

“It doesn’t work” with no version numbers, no reproduction, and no log output is functionally undebuggable by anyone else, including future you in six months. The minute you spend capturing the exact command and its exact output is the same minute that turns a multi-day back-and-forth into a same-day fix.

Recap

The workflow underneath this entire course is small: reproduce directly, check the log with debugging on, confirm registration before permission before execution, and verify with a real tool instead of trusting a single client’s rendering of a failure. Layered on top of that workflow are three specific, real, citable bugs, a missing category argument mistaken for a WooCommerce conflict (#135), a bare untyped input_schema breaking registration in Cursor (#35), and an empty-arguments validation bug fixed in v0.5.0 (#116). None of these are hypothetical, and none of them require guessing, they were all found, diagnosed, and resolved in the open, and the same tracker is worth searching the next time something new turns up.

With debugging covered, the natural next steps depend on where your project is headed. If you haven’t yet built the permission and security layer this track assumes, go back to WordPress MCP Security & Authentication (Course 4). If your server itself still needs work before you’re ready to debug it in production, revisit Build a WordPress MCP Server From Scratch (Course 2) and WordPress AI Foundations (Course 1) for the Abilities API fundamentals this entire course assumed you already had.

Resources & further reading

← Reading MCP Adapter Logs and Error Handlers Finish ✓