docs: v0.5.0 documentation improvements#147
docs: v0.5.0 documentation improvements#147galatanovidiu wants to merge 12 commits intorelease/v0.5.0from
Conversation
Two-layer architecture (Schema Layer + Adapter Layer), McpComponentInterface, DTO-based handler returns, new utility classes section, updated extension points.
Breaking changes with before/after code, migration steps for custom transports, handlers, components, error handling, and observability. Backward compat notes.
Adds Tool Naming section to creating-abilities guide covering /→- transformation, full sanitization pipeline, mcp_adapter_tool_name filter, and naming examples.
…for v0.5.0 Add McpComponentInterface, utility classes, FailureReason to architecture tree. Add php-mcp-schema as required dependency. Add migration guide link.
Comparison table, layered discovery explanation, direct registration pattern, filters for disabling/extending the default server.
Session lifecycle (initialize, use header, terminate), curl examples, error cases, configuration hooks, STDIO exemption, troubleshooting entry.
…ndex Link v0.3.0 and v0.5.0 migration guides from docs/README.md navigation.
Aligns with v0.5.0 DTO-based error responses documented in migration guide.
Most users see no breaking changes — public APIs, hooks, and factory methods are all unchanged. Internal API changes moved to an Advanced section for custom handler/transport implementers only.
Architecture: fix ping return type, transport interface signature, json_text signature, rest_ensure_response → WP_REST_Response, condense redundant sections. Guides: fix protocol version in curl example, clarify tool naming scope, add HTTP 200 error note, explain initialized notification. README: add 4 missing files to component tree, fix dash formatting. Troubleshooting: fix HTTP 400 reference to JSON-RPC error code. Source: fix SessionManager PHPDoc timeout default (was 3600, actual DAY_IN_SECONDS).
Convert all headings to sentence case per WordPress Documentation Style Guide. Fix broken bold markup on creating-abilities.md line 12.
|
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 If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## release/v0.5.0 #147 +/- ##
====================================================
+ Coverage 87.48% 87.62% +0.14%
- Complexity 1197 1218 +21
====================================================
Files 53 54 +1
Lines 3898 3944 +46
====================================================
+ Hits 3410 3456 +46
Misses 488 488
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
galatanovidiu
force-pushed
the
release/v0.5.0
branch
from
2207780 to
5162f62
Compare
There was a problem hiding this comment.
Pull request overview
Documentation refresh for v0.5.0 to reflect the schema/adapter split (php-mcp-schema DTOs), clarify default vs custom server usage, document HTTP session requirements, and add a v0.5.0 migration guide.
Changes:
- Adds a new v0.5.0 migration guide covering DTO return types and McpErrorFactory changes.
- Expands default server guide (layered discovery vs custom server) and documents HTTP session flow & error cases.
- Updates architecture overview, troubleshooting docs, and README/doc index navigation for v0.5.0.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| includes/Transport/Infrastructure/SessionManager.php | Corrects PHPDoc to match the actual default inactivity timeout (DAY_IN_SECONDS). |
| docs/troubleshooting/common-issues.md | Adds HTTP session troubleshooting and updates McpErrorFactory example usage. |
| docs/migration/v0.5.0.md | New migration guide explaining DTO-based internals and advanced upgrade steps. |
| docs/guides/default-server.md | Adds guidance on choosing default vs custom servers + HTTP sessions section. |
| docs/guides/creating-abilities.md | Adds tool naming/sanitization documentation and filter hook details. |
| docs/architecture/overview.md | Rewrites architecture docs to describe schema DTOs vs adapter layer and new utilities. |
| docs/README.md | Updates docs index/nav and adds migration guide links. |
| README.md | Updates component tree and references php-mcp-schema + migration docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Tool names now show MCP-sanitized form (hyphens) with a note explaining the ability registration name (slashes) vs MCP tool name distinction. Session flow clarifies GET/SSE is reserved for future support. Protocol version corrected to 2025-11-25 in troubleshooting example. Interface snippet aligned with actual McpRestTransportInterface signature.
| | `my-plugin/my-tool` | `my-plugin-my-tool` | | ||
| | `fluent/get-posts` | `fluent-get-posts` | | ||
| | `café/résumé-tool` | `cafe-resume-tool` | |
There was a problem hiding this comment.
Does it make any difference in how the tool name is created from the ability name? With the current implementation, there is a tiny risk of name clash. It's rather academic consideration but it could happen with the number of plugin WordPress hosts in the directory. In particular now that multiple / can be used in the ability name:
fluent/get-posts->fluent-get-posts.fluent/get/posts->fluent-get-posts.
Just something to keep in mind. If you would go with _ which is alsow allowed the problem doesn't exist:
fluent/get-posts->fluent_get-posts.fluent/get/posts->fluent_get_posts.
gziolo
left a comment
gziolo
left a comment
There was a problem hiding this comment.
I reviewed everything and all changes look good. I can't say much about the migration guide as I'm not deeply familiar with the changes, but assuming it's correct, it's going to be extremely helpful, so kudos for including it.
Summary
Complete documentation update for v0.5.0 reflecting the architectural changes (schema/adapter separation via php-mcp-schema DTOs) and addressing documentation gaps from #105.
Changes
/→-transformation, sanitization pipeline,mcp_adapter_tool_namefilter, registration name vs MCP name distinctionOther fixes
Closes #105