Skip to content

docs: consolidate and cleanup documentation - #11

Merged
dennisdornon merged 3 commits into
mainfrom
docs-update
Dec 31, 2025
Merged

dennisdornon merged 3 commits into
mainfrom
docs-update

Conversation

@dennisdornon

@dennisdornon dennisdornon commented Dec 30, 2025 •

Copy link
Copy Markdown
Member

Removes redundant docs and streamlines what remains.

Changes:

  • removed ci-cd.md, installation.md, test-suite.md (outdated/duplicative)
  • trimmed security.md and troubleshooting.md significantly
  • simplified configuration.md
  • added audit logging for destructive operations
  • fixed settings.example.json accuracy

Net: -1800 lines. Core info preserved, noise removed.

Summary by CodeRabbit

  • New Features

    • Configurable retry mechanism (enable, max attempts, base/max delay)
    • User confirmation gating for destructive actions
    • Option to allow HTTP URLs/credentials (MAINWP_ALLOW_HTTP) and expanded config options (blocked tools, schema verbosity, ability namespace)
  • Documentation

    • Added Alpha badge; reorganized guides into Configuration Reference, Troubleshooting, and Contributing
    • Removed standalone Installation, CI/CD, and Test Suite docs; updated examples and settings (confirmation + retry fields)
    • Streamlined Security, Troubleshooting, and examples for clarity

✏️ Tip: You can customize this high-level summary in your review settings.

- 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
@coderabbitai

coderabbitai Bot commented Dec 30, 2025 •

Copy link
Copy Markdown

Walkthrough

Restructures 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

Cohort / File(s) Summary
Top-level README & Navigation
README.md
Added Alpha badge; updated project description and pre-release/testing notes; simplified Quick Start and CI messaging; renamed/normalized documentation links and navigation.
Configuration docs & settings file
docs/configuration.md, settings.example.json
Streamlined configuration text; added env vars including MAINWP_ALLOW_HTTP, MAINWP_BLOCKED_TOOLS, MAINWP_SCHEMA_VERBOSITY, MAINWP_ABILITY_NAMESPACE, retry-related vars (MAINWP_RETRY_ENABLED, MAINWP_MAX_RETRIES, MAINWP_RETRY_BASE_DELAY, MAINWP_RETRY_MAX_DELAY); settings.example.json gains requireUserConfirmation, retryEnabled, maxRetries, retryBaseDelay, retryMaxDelay.
Security & Troubleshooting docs
docs/security.md, docs/troubleshooting.md
Major consolidation and rewrite: merged sections, condensed guidance (trust model, credential management, safe mode, dry-run/confirmation flow), and added concise curl/JSON troubleshooting examples.
Removed documentation
docs/installation.md, docs/ci-cd.md, docs/test-suite.md
Deleted full documents (installation guide, CI/CD reference, and test-suite documentation).
Example prompts doc
docs/example-prompts.md
Removed the "Next Steps" section and associated links; minor formatting/content cleanup.
Runtime / Audit logging
src/abilities.ts
When an ability is marked destructive, emit an audit log line to stderr with the operation name. No API signature changes.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Pre-merge checks

✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The PR title 'docs: consolidate and cleanup documentation' clearly and accurately summarizes the main change—a comprehensive documentation refactor that removes outdated/redundant files and simplifies remaining documentation.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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.md to fix.

docs/security.md (1)

1-294: Prettier formatting issue detected by CI.

The pipeline has identified formatting inconsistencies. Run prettier --write docs/security.md to fix.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2ea2d5a and b29cb36.

📒 Files selected for processing (10)
  • README.md
  • docs/ci-cd.md
  • docs/configuration.md
  • docs/example-prompts.md
  • docs/installation.md
  • docs/security.md
  • docs/test-suite.md
  • docs/troubleshooting.md
  • settings.example.json
  • src/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.

Comment thread docs/example-prompts.md Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

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

📥 Commits

Reviewing files that changed from the base of the PR and between 0425122 and c75a84c.

📒 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant