Repository navigation
docs: consolidate and cleanup documentation - #11
Conversation
- Consolidated docs by removing ci-cd.md, installation.md, test-suite.md - Added MAINWP_ALLOW_HTTP to environment variable tables - Added retry configuration variables to configuration.md - Added allowHttp to field mapping table - Added HTTP URL troubleshooting entry - Added missing fields to settings.example.json - Moved Node.js requirement to Quick Start section - Renamed Development section to Contributing
WalkthroughRestructures and consolidates documentation (README and multiple docs), deletes three standalone docs (installation, ci-cd, test-suite), expands configuration with retry and user-confirmation options in settings.example.json, adds MAINWP_ALLOW_HTTP and other env vars, and logs an audit message to stderr when destructive abilities execute in src/abilities.ts. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Pre-merge checks✅ Passed checks (3 passed)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/troubleshooting.md (1)
1-293: Excellent consolidation of troubleshooting guidance.The rewrite successfully transforms verbose narrative sections into compact, actionable troubleshooting steps. The curl examples are particularly helpful for diagnosing connection issues. The technical content is accurate and well-organized.
Note: The pipeline has detected a Prettier formatting issue. Run
prettier --write docs/troubleshooting.mdto fix.docs/security.md (1)
1-294: Prettier formatting issue detected by CI.The pipeline has identified formatting inconsistencies. Run
prettier --write docs/security.mdto fix.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
README.mddocs/ci-cd.mddocs/configuration.mddocs/example-prompts.mddocs/installation.mddocs/security.mddocs/test-suite.mddocs/troubleshooting.mdsettings.example.jsonsrc/abilities.ts
💤 Files with no reviewable changes (3)
- docs/test-suite.md
- docs/installation.md
- docs/ci-cd.md
🧰 Additional context used
🪛 GitHub Actions: CI
docs/security.md
[error] 1-1: Prettier formatting check found issues in this file. Run 'prettier --write docs/security.md' to fix.
docs/example-prompts.md
[error] 1-1: Prettier formatting check found issues in this file. Run 'prettier --write docs/example-prompts.md' to fix.
🪛 Gitleaks (8.30.0)
docs/troubleshooting.md
[high] 12-20: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
[high] 28-28: Discovered a potential basic authorization token provided in a curl command, which could compromise the curl accessed resource.
(curl-auth-user)
🪛 LanguageTool
docs/security.md
[style] ~58-~58: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... bash MAINWP_SAFE_MODE=true ``` Safe mode blocks delete_site_v1, `delete_c...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~167-~167: Ensure spelling is correct
Context: ...on. --- ## AI Client Limitations The mainwp-mcp server provides multiple safety mec...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/troubleshooting.md
[style] ~261-~261: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ....101+, verify Agent Mode is enabled. For Claude Desktop: Check config file loc...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🔇 Additional comments (8)
settings.example.json (1)
14-29: LGTM!The new configuration fields (requireUserConfirmation, retry settings) are properly structured and align with the documented defaults in configuration.md. The JSON syntax is valid.
docs/configuration.md (2)
15-29: LGTM!The new environment variables (MAINWP_ALLOW_HTTP and retry configuration) are properly documented with clear descriptions and appropriate defaults. These align correctly with the corresponding fields in settings.example.json.
59-73: LGTM!The field mapping table correctly documents the relationship between settings.json fields and environment variables for the newly added configuration options. Type annotations are accurate.
README.md (2)
6-6: LGTM!The Alpha status badge appropriately sets expectations for users about the maturity of this project.
397-407: LGTM!The environment variables table correctly documents the new configuration options (MAINWP_ALLOW_HTTP and retry settings) with accurate descriptions and defaults. These align with the detailed documentation in configuration.md.
src/abilities.ts (1)
355-358: LGTM! Excellent security enhancement.The audit logging for destructive operations is well-implemented:
- Logs only the operation name, avoiding any sensitive parameter exposure
- Uses stderr (console.error) for proper stream separation
- Clear prefix "[mainwp-mcp] AUDIT:" makes logs easily filterable
- Positioned correctly before execution to ensure all destructive attempts are recorded
This aligns with the security documentation updates and provides proper accountability for destructive actions.
docs/security.md (2)
96-101: LGTM! Important compliance consideration.This new section correctly warns users about DELETE request parameters appearing in web server access logs due to WordPress Abilities API requirements. This is crucial information for organizations with strict data handling policies.
276-281: LGTM!The logging and auditing section accurately reflects the new audit logging implementation in abilities.ts. The clear delineation of what is and isn't logged is excellent for security transparency.
Fixes CI failure from format:check job.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/security.md (1)
47-47: Reduce repetitive sentence beginnings in the Safe Mode section.Three consecutive paragraphs each begin with "Safe mode," which impacts readability. Consider rephrasing one or two of these for variety.
Safe mode prevents all destructive operations by stripping the `confirm: true` parameter that destructive tools require. ... -Safe mode blocks `delete_site_v1`, `delete_client_v1`, `delete_tag_v1`, `delete_site_plugins_v1`, and `delete_site_themes_v1`. These tools require `confirm: true` to execute, and safe mode strips this parameter, causing the API to reject the request. +It blocks `delete_site_v1`, `delete_client_v1`, `delete_tag_v1`, `delete_site_plugins_v1`, and `delete_site_themes_v1`. These tools require `confirm: true` to execute, and safe mode strips this parameter, causing the API to reject the request. All read operations and non-destructive writes remain available: listing and viewing sites, clients, tags; running updates (reversible via backups); activating and deactivating plugins and themes; syncing sites; creating new clients and tags. -Safe mode is useful for training (let users explore without risk), development (test integrations without affecting real data), read-only access (when you only need reporting capabilities), demos (show capabilities without live changes), and first-time setup (familiarize yourself with the system safely). +The feature is useful for training (let users explore without risk), development (test integrations without affecting real data), read-only access (when you only need reporting capabilities), demos (show capabilities without live changes), and first-time setup (familiarize yourself with the system safely).Also applies to: 59-59, 63-63
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/security.md
🧰 Additional context used
🪛 LanguageTool
docs/security.md
[style] ~58-~58: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... bash MAINWP_SAFE_MODE=true ``` Safe mode blocks delete_site_v1, `delete_c...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
[grammar] ~167-~167: Ensure spelling is correct
Context: ...on. --- ## AI Client Limitations The mainwp-mcp server provides multiple safety mec...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (1)
docs/security.md (1)
1-284: Documentation consolidation is clear and well-organized.The security guide has been effectively streamlined while preserving critical guidance on trust boundaries, credential management, safe mode, confirmation flows, and risk mitigation. The sections are logically ordered, examples are practical, and the checklist provides actionable production readiness criteria. The addition of the Server Log Considerations section (lines 96–101) is a valuable security clarification about query parameter logging.
Removes redundant docs and streamlines what remains.
Changes:
Net: -1800 lines. Core info preserved, noise removed.
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.