Skip to content

docs: fix errors, remove duplication and improve examples - #204

Merged
justlevine merged 6 commits into
WordPress:trunkfrom
itsgajendraSingh:docs/initial-cleanup
Jun 13, 2026
Merged

docs: fix errors, remove duplication and improve examples#204
justlevine merged 6 commits into
WordPress:trunkfrom
itsgajendraSingh:docs/initial-cleanup

Conversation

@itsgajendraSingh

@itsgajendraSingh itsgajendraSingh commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

Summary

Documentation cleanup across the repository focused on accuracy,
removing duplication, and improving code examples to follow WordPress
coding standards.

Removed

Deleted README-INITIAL.md — stale pre-project placeholder fully superseded by README.md

Removed duplicate and redundant content:

  • Duplicate "Understanding Abilities as MCP Components" section from README.md
  • Duplicate mcp_adapter_default_server_config filter example from docs/guides/default-server.md
  • Redundant "Quick navigation" section from docs/README.md
  • "What Just Happened?" filler section from docs/getting-started/README.md
  • Duplicate troubleshooting block in docs/getting-started/README.md (replaced with a link)
  • 100-line architecture file tree from README.md (moved to docs/architecture/overview.md)

Fixed

CONTRIBUTING.md: wrong plugin name ("Performance Lab plugin" → "MCP Adapter"), {@todo} placeholder, truncated sentence, broken SECURITY.md link

README.md: incorrect composer require wordpress/abilities-api (it is a plugin, not a Composer package), PHP version (>= 7.4 → ^7.4 || ^8.0), MCP spec version 2025-06-18 → 2025-11-25, McpAdapter::instance() example now wrapped in plugins_loaded hook with correct timing context

docs/getting-started/README.md and docs/getting-started/installation.md: missing observability_handler argument in create_server() examples — tools array was being passed as the wrong positional argument

docs/guides/custom-transports.md: MCP spec version 2025-06-18 → 2025-11-25

docs/troubleshooting/common-issues.md: missing strict comparison (true) in in_array() call

Improved

Plugin installation is now the primary recommended method

Added sanitize_text_field() to API key example in docs/guides/custom-transports.md

Added input validation (WP_Error) before wp_insert_post() in docs/getting-started/basic-examples.md

Switched [] to array() in code examples for WordPress coding standards consistency

Added strict true to in_array() calls in examples

Added verified directory structure to docs/architecture/overview.md including 4 files missing from the old map

Test plan

  • Read through README.md and verify installation instructions are accurate
  • Verify create_server() examples pass the correct number of arguments in all files
  • Confirm docs/architecture/overview.md directory structure matches includes/

cc @justlevine

Copilot AI review requested due to automatic review settings June 1, 2026 16:31
@github-actions

github-actions Bot commented Jun 1, 2026 •
edited
Loading

Copy link
Copy Markdown

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: itsgajendraSingh <gajendrasingh@git.wordpress.org>
Co-authored-by: justlevine <justlevine@git.wordpress.org>

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

Copilot AI reviewed Jun 1, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Documentation cleanup and refresh across the repository, removing redundant/outdated content and updating MCP specification references.

Changes:

  • Updated MCP specification references from 2025-06-18 to 2025-11-25 in README and guides.
  • Restructured README, getting-started, and docs to remove duplicated content and link to canonical sources (architecture overview, common issues, etc.).
  • Minor code-example improvements (WP Coding Standards compliance: array() syntax, in_array strict mode, added input validation, observability handler param).

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file
File Description
docs/troubleshooting/common-issues.md Added strict mode to in_array example.
docs/guides/default-server.md Removed Customization section about mcp_adapter_default_server_config filter.
docs/guides/custom-transports.md Updated spec version; sanitize API key header; use array().
docs/getting-started/installation.md Added missing observability handler argument in create_server example.
docs/getting-started/basic-examples.md Added title validation, switched to array() syntax and strict in_array.
docs/getting-started/README.md Added observability handler arg; trimmed redundant sections; link to common-issues.
docs/architecture/overview.md Added detailed directory-structure section.
docs/README.md Removed Quick navigation section; condensed footer.
README.md Major restructuring; updated spec version; clarified install paths; new plugins_loaded example.
README-INITIAL.md Deleted obsolete placeholder README.
CONTRIBUTING.md Corrected stale text (Performance Lab → MCP Adapter), fixed SECURITY.md link, removed TODOs.
Comments suppressed due to low confidence (1)

docs/getting-started/README.md:1

  • Same clarification as in installation.md: the (null = default) comment is ambiguous. Please describe the actual fallback behavior so readers know whether observability is silently disabled or enabled with a default handler.
# Getting Started with MCP Adapter

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/getting-started/basic-examples.md
Comment thread README.md
Comment thread docs/getting-started/installation.md
@codecov

codecov Bot commented Jun 1, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.85%. Comparing base (530a541) to head (cd201a4).

Additional details and impacted files 
@@            Coverage Diff            @@
##              trunk     #204   +/-   ##
=========================================
  Coverage     87.85%   87.85%           
  Complexity     1243     1243           
=========================================
  Files            53       53           
  Lines          4035     4035           
=========================================
  Hits           3545     3545           
  Misses          490      490
Flag Coverage Δ
unit 87.85% <ø> (ø)

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.

@jeffpaul
jeffpaul requested a review from justlevine June 10, 2026 14:15
justlevine
justlevine approved these changes Jun 13, 2026
View reviewed changes

@justlevine justlevine left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did a little technical cleanup in ef0500e . Otherwise this LGTM - thanks @itsgajendraSingh b🙇

Merging so we can iterate in followup PRs.

@justlevine
justlevine merged commit 78b7373 into WordPress:trunk Jun 13, 2026
24 of 25 checks passed
This was referenced Jun 24, 2026
Merged
Closed
galatanovidiu pushed a commit that referenced this pull request Aug 11, 2026
@mathetos
docs: clarify Abilities API is core in 6.9+ (fixes #150) (#223)
1b96b15 
## Summary

Some docs still read like you need a separate Abilities API install.
README.md was mostly updated in #165 and #204, but readme.txt and the
getting-started guides were still Composer-first and pretty quiet about
core.

This PR lines those up: says plainly that Abilities API ships with
WordPress 6.9+, matches install docs to README (plugin first, Composer
for plugin devs), and tightens the admin notice when core is too old.

Closes #150

## What changed

- README.md: one line in Dependencies
- readme.txt: plugin-first install wording
- docs/getting-started/README.md and installation.md: same story,
flipped order
- common-issues.md + Plugin.php: clearer "you need WP 6.9+" messaging

## Test plan

- [x] Read-through for stale abilities-api / composer require references
- [ ] Maintainer eyeball on install doc ordering
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@justlevine justlevine justlevine approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@itsgajendraSingh @justlevine