Add 11 handler filter hooks for extensibility

[galatanovidiu]

Summary

11 new apply_filters hooks across the MCP handler lifecycle. Covers execution gates, argument/result transformation, list operations, initialization, and component naming.

Motivation

The plugin had 20 hooks but none in the request/response lifecycle. Once a request entered RequestRouter, there were zero extension points until the JSON-RPC response left. No way to modify arguments, filter results, block execution, or dynamically adjust component lists.

Hooks added

Pre-execution (can short-circuit with WP_Error)

Hook	Params	Purpose
mcp_adapter_pre_tool_call	(array $args, string $tool_name, McpTool $mcp_tool, McpServer $server) => array|WP_Error	Modify tool arguments or return WP_Error to block execution
mcp_adapter_pre_resource_read	(array $params, string $uri, McpResource $mcp_resource, McpServer $server) => array|WP_Error	Modify resource params or return WP_Error to block execution
mcp_adapter_pre_prompt_get	(array $arguments, string $prompt_name, McpPrompt $mcp_prompt, McpServer $server) => array|WP_Error	Modify prompt arguments or return WP_Error to block execution

Result filters

Hook	Params	Purpose
mcp_adapter_tool_call_result	(mixed $result, array $args, string $tool_name, McpTool $mcp_tool, McpServer $server) => mixed	Transform tool result before DTO assembly (PII redaction, audit logging)
mcp_adapter_resource_read_result	(mixed $contents, array $params, string $uri, McpResource $mcp_resource, McpServer $server) => mixed	Transform resource contents before DTO conversion
mcp_adapter_prompt_get_result	(mixed $result, array $arguments, string $prompt_name, McpPrompt $mcp_prompt, McpServer $server) => mixed	Transform prompt result before normalization

List filters

Hook	Params	Purpose
mcp_adapter_tools_list	(array $tools, McpServer $server) => array	Hide tools per user/role, add dynamic tools, reorder
mcp_adapter_resources_list	(array $resources, McpServer $server) => array	Filter resources by context, add dynamic resources
mcp_adapter_prompts_list	(array $prompts, McpServer $server) => array	Filter prompts, add dynamic prompts

Initialize

Hook	Params	Purpose
mcp_adapter_initialize_response	(InitializeResult $result, McpServer $server) => InitializeResult	Dynamic capabilities, custom instructions

Naming

Hook	Params	Purpose
mcp_adapter_prompt_name	(string $name, WP_Ability $ability) => string	Naming parity with existing mcp_adapter_tool_name and mcp_adapter_resource_name

Why the names differ from #130

The names differ from the ones proposed in the #130 investigation. During implementation I found two problems with the _pre/_post naming from the issue:

1. _pre was ambiguous. It could mean "modify arguments" or "gate execution" but couldn't do both. I need to block execution (rate limiting, circuit breakers) from the same hook that modifies arguments, not from a separate one.

2. _post didn't say what you're filtering. _result is explicit.

I went with the WordPress core pre_* short-circuit pattern instead (pre_delete_post, pre_update_option, pre_get_shortlink). The filter returns the modified value to proceed or WP_Error to block. This is a pattern WordPress developers already know.

Test plan

• All tests pass (npm run test:php)
• PHPCS clean (npm run lint:php)
• PHPStan Level 8 zero errors (npm run lint:php:stan)
• pre_tool_call filter can modify arguments
• pre_tool_call filter can block execution with WP_Error
• tool_call_result filter can modify result
• List filters can remove/add components
• initialize_response filter can modify instructions
• prompt_name filter can customize name
• MCP Inspector smoke test: npx @modelcontextprotocol/inspector --cli --config .mcp.json --server mcp-adapter-default-npx --method tools/list

Ref #130

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: galatanovidiu <ovidiu-galatan@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

❌ Patch coverage is 98.52941% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 87.74%. Comparing base (31a4485) to head (9ad1c31).
⚠️ Report is 2 commits behind head on release/v0.5.0.

Files with missing lines	Patch %	Lines
...udes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php	94.44%	1 Missing ⚠️

Additional details and impacted files

@@                 Coverage Diff                  @@
##             release/v0.5.0     #151      +/-   ##
====================================================
+ Coverage             87.62%   87.74%   +0.11%     
- Complexity             1218     1230      +12     
====================================================
  Files                    54       54              
  Lines                  3944     3990      +46     
====================================================
+ Hits                   3456     3501      +45     
- Misses                  488      489       +1     

Flag	Coverage Δ
unit	87.74% <98.52%> (+0.11%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gziolo]

A quick thought before I jump into details. There is a very similar feature request for the AI plugin:

• Add extensibility hooks for system instructions, ability results, and post context ai#304

I shared my thoughts in WordPress/ai#304 (comment), with the main takeaway being some of these filters would be better suited for WP core rather than the plugin.

Based only on the PR's description, I can see some similarities here. I can see why it also makes sense to add MCP adapter specific filters that tap into the execution flow (pre & result). At the same time, it's clear there is gap in WordPress core that we won't be able to fill before WordPress 7.1 (August 2026).

@ovidiu-galatan, I'd be curious to hear your perspective here.

[gziolo]

I see it in a few places, so adding a simpler converter would be useful here.

[galatanovidiu]

Done. Extracted create_error_result() as a private method at the bottom of the class. Replaces all 4 identical CallToolResult::fromArray(... isError: true) constructions in call_tool(). See 5df485d.

[gziolo]

It would be worth explicitly mentioning WP_Error as a possible result here. In fact, it probably can be passed as $result in the first place.

[galatanovidiu]

Good call. Updated the @param to mixed|\WP_Error on all three result filters (tool_call_result, resource_read_result, prompt_get_result). See d091cef.

[gziolo]

In other filters, some basic validation is in place for what the filter returns. Here, this value is passed through, which might be fine. However, it's worth confirming it is an expected flow.

[galatanovidiu]

Added validate_filtered_list() to HandlerHelperTrait. If a filter returns a non-array, it logs a warning and falls back to the original unfiltered list. Applied to all three list filters. See 9ad1c31.

[gziolo]

Solid set of hooks — good naming rationale, clean test coverage, and the pre_* / *_result pattern follows WordPress conventions well.

One question: the three mcp_adapter_pre_* filters handle WP_Error short-circuits differently:

• mcp_adapter_pre_tool_call → CallToolResult with isError=true (makes sense per MCP spec)
• mcp_adapter_pre_resource_read → McpErrorFactory::internal_error()
• mcp_adapter_pre_prompt_get → McpErrorFactory::permission_denied()

Was the permission_denied vs internal_error distinction intentional?

[galatanovidiu]

Wasn't intentional. The permission_denied on the prompt pre-filter was a copy-paste from the nearby permission check. Both resources and prompts should probably use internal_error for pre-filter short-circuits since the WP_Error could be anything (rate limiting, maintenance mode, etc.), not specifically a permission failure.

Opened #152 to track this. I'd rather fix it in a follow-up PR since changing the error type is a behavior change that should be tested on its own.

[gziolo]

Works for me. New utility methods added look great 👍🏻

[galatanovidiu]

I looked at your comment on WordPress/ai#304. I think you're right that generic ability result filtering belongs in core (inside WP_Ability::execute()). That would close the gap between the existing wp_after_execute_ability action and what plugins actually need.

That said, I'd keep the MCP adapter's own result filters (mcp_adapter_tool_call_result, etc.) even after core adds its version. They operate at a different layer. A core filter would fire inside execute() and affect every consumer. The MCP filters fire after execution but before DTO assembly, so they're specific to what goes out over the MCP protocol.

Concrete example: you might want to redact sensitive data only in MCP responses (exposed to external LLMs) but not in the AI plugin's internal usage. That's only possible if both layers have their own hooks.

They'd compose naturally too: core filter runs first, MCP filter sees the already-filtered output. No conflict.

For the other hooks in this PR (pre_* short-circuits, list filters, initialize_response, prompt_name), those are all MCP-specific. They work with MCP domain objects and protocol DTOs, so there's no overlap with what core would provide.

[gziolo]

I looked at your comment on WordPress/ai#304. I think you're right that generic ability result filtering belongs in core (inside WP_Ability::execute()). That would close the gap between the existing wp_after_execute_ability action and what plugins actually need.

Thank you for checking that and confirming my concerns. I will file a new Trac ticket at some point.

That said, I'd keep the MCP adapter's own result filters (mcp_adapter_tool_call_result, etc.) even after core adds its version. They operate at a different layer.

There is definitely a place for a specific filter like that. Even in WP core, you often have a pair of filters, one general purpose, and one that is tied to some subset of cases. If someone uses mcp_adapter_tool_call_result then it's clear they only care about MCP flow.

[gziolo]

To close the loop and seek additional feedback, I opened Abilities API: Add execution lifecycle filters to WP_Ability methods in WordPress core.