Repository navigation
Added: Documentation for AI safety and namespace configuration - #8
Conversation
Document the ability namespace configuration option that was already implemented but missing from documentation: - Add MAINWP_ABILITY_NAMESPACE to README environment variables table - Add new "Namespace Filtering" section to configuration.md with: - Default behavior explanation - Use cases for custom extensions, multi-vendor, and multiple instances - Security warning for empty namespace
- Installation guide now includes AI safety notice warning about LLM non-determinism and recommending backups before first use - Security guide expanded with dry-run preview documentation showing how to preview destructive operations safely - New section documenting AI client limitations when following confirmation flows, with recommended protective configurations - Version bump to 1.0.0-alpha.20
WalkthroughThe release introduces namespace filtering configuration for ability management via a new MAINWP_ABILITY_NAMESPACE environment variable, along with comprehensive documentation updates covering configuration guidance, AI safety practices, and dry-run preview usage. Version bumped to 1.0.0-alpha.20. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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 (1)
docs/security.md (1)
1-634: Address Prettier formatting issues flagged by CI.The GitHub Actions CI pipeline detected Prettier formatting issues in this file. Please run the formatter to resolve:
prettier --write docs/security.md
🧹 Nitpick comments (2)
docs/configuration.md (1)
82-142: Excellent documentation of namespace filtering with practical examples.The new section clearly explains the abilityNamespace setting, its default behavior, and includes relevant use cases for custom extensions and multi-vendor setups. The warning about empty namespaces exposing all abilities is particularly important for safety.
The markdownlint hints indicate that lines 100, 112, and 124 use bold text instead of headings for subsections. While this doesn't affect functionality, using proper heading levels would improve document structure:
🔎 Optional markdown structure improvement
-**Custom Extension Development** +### Custom Extension Development -**Multi-Vendor Dashboard** +### Multi-Vendor Dashboard -**Multiple MCP Server Instances** +### Multiple MCP Server Instancesdocs/installation.md (1)
7-32: Excellent addition of AI safety notice with clear recommendations.The safety notice is appropriately placed at the beginning of the installation guide and provides actionable recommendations for users. The Known AI Client Limitations section sets proper expectations about AI client behavior and correctly identifies these as client-side issues rather than server bugs.
Line 11 could be more concise per the LanguageTool suggestion:
🔎 Optional wording improvement
-Large Language Models (LLMs) and AI agents are non-deterministic systems that can make mistakes, misinterpret instructions, or perform unintended actions. When connected to your MainWP Dashboard, an AI assistant has the ability to modify or delete sites, plugins, themes, clients, and tags. +Large Language Models (LLMs) and AI agents are non-deterministic systems that can make mistakes, misinterpret instructions, or perform unintended actions. When connected to your MainWP Dashboard, an AI assistant can modify or delete sites, plugins, themes, clients, and tags.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
README.md(1 hunks)docs/configuration.md(1 hunks)docs/installation.md(1 hunks)docs/security.md(3 hunks)package.json(1 hunks)src/index.ts(1 hunks)
🧰 Additional context used
🪛 GitHub Actions: CI
docs/security.md
[warning] 1-1: Prettier formatting issues detected in docs/security.md. Run 'prettier --write docs/security.md' to fix.
🪛 LanguageTool
docs/installation.md
[style] ~11-~11: The phrase ‘has the ability to’ might be wordy. Consider using “can”.
Context: ... your MainWP Dashboard, an AI assistant has the ability to modify or delete sites, plugins, themes...
(HAS_THE_ABILITY_TO)
🪛 markdownlint-cli2 (0.18.1)
docs/configuration.md
100-100: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
112-112: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
124-124: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
docs/security.md
181-181: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
package.json (1)
3-3: LGTM! Version bump is consistent across the project.The version increment to 1.0.0-alpha.20 aligns with the SERVER_VERSION update in src/index.ts and the documentation changes in this PR.
src/index.ts (1)
50-50: LGTM! Server version is consistent with package.json.The version bump to 1.0.0-alpha.20 correctly matches the package.json version update.
README.md (1)
406-406: LGTM! Clear documentation of the new namespace filtering option.The MAINWP_ABILITY_NAMESPACE environment variable is well-documented with default value and description. This aligns with the detailed explanation in docs/configuration.md.
docs/security.md (2)
136-153: Good addition of first-time setup recommendations.The expanded Safe Mode section now includes practical guidance for first-time users to start with Safe Mode enabled and build confidence before enabling destructive operations. This aligns well with the safety recommendations in the installation guide.
355-424: Important documentation of AI client limitations.The AI Client Limitations section appropriately documents observed behaviors where AI clients may not properly follow the confirmation flow. The clarification that these are client-side issues (not mainwp-mcp bugs) is important, and the protective configuration recommendations are practical.
| ## Using Dry-Run Previews | ||
|
|
||
| Before executing any destructive operation, you can preview exactly what will be affected using the `dry_run` parameter. | ||
|
|
||
| ### How It Works | ||
|
|
||
| Many destructive tools support `dry_run: true`, which simulates the operation without making any changes: | ||
|
|
||
| ``` | ||
| You: Delete the staging plugins, but show me what will happen first | ||
|
|
||
| AI: [Calls delete_site_plugins_v1(site_id: 3, plugin_slugs: ["debug-bar"], dry_run: true)] | ||
| Server returns preview: | ||
| { | ||
| "dry_run": true, | ||
| "would_delete": ["debug-bar/debug-bar.php"], | ||
| "sites_affected": 1 | ||
| } | ||
|
|
||
| AI: If I proceed, this will delete the "debug-bar" plugin from site 3. | ||
| Should I continue? | ||
| ``` | ||
|
|
||
| ### Tools Supporting Dry-Run | ||
|
|
||
| The following destructive tools support `dry_run: true`: | ||
|
|
||
| - `delete_site_v1` - Preview site deletion | ||
| - `delete_client_v1` - Preview client deletion | ||
| - `delete_tag_v1` - Preview tag deletion | ||
| - `delete_site_plugins_v1` - Preview plugin removal | ||
| - `delete_site_themes_v1` - Preview theme removal | ||
|
|
||
| ### When to Use Dry-Run | ||
|
|
||
| - **Always** before bulk operations affecting multiple items | ||
| - When you're unsure about the scope of a deletion | ||
| - When training or learning the system | ||
| - Before any operation you can't easily reverse | ||
|
|
||
| --- |
There was a problem hiding this comment.
Clear documentation of dry-run preview functionality.
The dry-run previews section provides practical examples and lists all tools that support this feature. The guidance on when to use dry-run is particularly helpful.
Line 181 has a fenced code block without a language specification. While this doesn't affect the content, it should specify the language for proper syntax highlighting:
🔎 Proposed fix
-```
+```text
You: Delete the staging plugins, but show me what will happen first
AI: [Calls delete_site_plugins_v1(site_id: 3, plugin_slugs: ["debug-bar"], dry_run: true)]🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
181-181: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In docs/security.md around lines 173 to 213, the fenced code block starting at
line 181 lacks a language tag; update the opening triple-backtick to include an
appropriate language identifier (e.g., text or bash) to enable proper syntax
highlighting, ensuring the block remains unchanged otherwise.
Summary
Adds documentation for the MAINWP_ABILITY_NAMESPACE configuration option and expands security documentation to address AI client behavior limitations.
Key Improvements
Technical Notes
MAINWP_ABILITY_NAMESPACE was already implemented but undocumented. The namespace filtering section explains use cases for custom extensions and multi-vendor setups.
The AI client limitations section documents observed behaviors where clients skip confirmation flows or assume operations are safe. This is advisory documentation - the server mechanisms remain unchanged.
Version bumped to 1.0.0-alpha.20.
Testing
Documentation changes only. Verified markdown renders correctly.
Summary by CodeRabbit
New Features
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.