mcp-wordpress 2.3.0 → 2.4.0

package/docs/PUBLISHING-TROUBLESHOOTING.md

@@ -0,0 +1,227 @@
+# Publishing Troubleshooting Guide
+
+## Overview
+
+This guide helps troubleshoot and resolve publishing issues for the MCP WordPress project. The project publishes
+to two main targets:
+
+1. **NPM Registry** - Node.js package
+2. **Docker Hub** - Container images
+
+## Automated Publishing Process
+
+### Normal Flow
+
+1. **Push to main branch** → triggers semantic-release
+2. **Semantic-release** → creates release, publishes to NPM, creates GitHub release
+3. **GitHub release created** → triggers Docker publishing
+4. **Verification workflow** → checks both NPM and Docker Hub
+5. **Success** → all done, or **Failure** → creates issue and triggers retry
+
+### Workflow Files
+
+- `.github/workflows/release.yml` - Main release workflow
+- `.github/workflows/docker-publish.yml` - Manual/fallback Docker publishing
+- `.github/workflows/verify-release.yml` - Verification and retry logic
+
+## Common Issues and Solutions
+
+### 1. Docker Publishing Failed (NPM Succeeded)
+
+**Symptoms:**
+
+- NPM has the new version
+- Docker Hub is missing the version
+- Verification workflow creates an issue
+
+**Causes:**
+
+- Docker Hub credentials expired
+- Docker build failure (platform issues, Dockerfile errors)
+- Network timeouts
+- Docker Hub rate limiting
+
+**Solutions:**
+
+#### Option A: Automatic Retry (Recommended)
+
+The verification workflow should automatically trigger a retry. Check the workflow run logs.
+
+#### Option B: Manual Workflow Trigger
+
+```bash
+# Replace v2.3.0 with your version
+gh workflow run docker-publish.yml -f tag=v2.3.0 -f push=true
+```
+
+#### Option C: Local Manual Build (Emergency)
+
+```bash
+# Use the provided script
+./scripts/manual-docker-publish.sh 2.3.0
+
+# Or manually:
+docker build --platform linux/amd64,linux/arm64 \
+  --tag docdyhr/mcp-wordpress:2.3.0 \
+  --tag docdyhr/mcp-wordpress:latest \
+  --push .
+```
+
+### 2. NPM Publishing Failed
+
+**Symptoms:**
+
+- GitHub release created but NPM doesn't have the version
+- Semantic-release logs show NPM errors
+
+**Causes:**
+
+- NPM_TOKEN expired or invalid
+- Package.json issues
+- NPM registry issues
+
+**Solutions:**
+
+```bash
+# Verify you're logged in
+npm whoami
+
+# Manual publish
+npm publish
+
+# Or with explicit registry
+npm publish --registry https://registry.npmjs.org
+```
+
+### 3. Both NPM and Docker Failed
+
+**Causes:**
+
+- GitHub secrets issues (NPM_TOKEN, DOCKER_USERNAME, DOCKER_PASSWORD)
+- Semantic-release configuration problems
+- Build/test failures
+
+**Solutions:**
+
+1. **Check secrets in GitHub repository settings**
+2. **Verify semantic-release configuration**
+3. **Run release dry-run locally:**
+
+   ```bash
+   npm run release:dry
+   ```
+
+### 4. Version Already Exists
+
+**Symptoms:**
+
+- "Version 2.3.0 already exists" errors
+
+**Solutions:**
+
+For NPM:
+
+```bash
+# You cannot overwrite existing versions
+# You need to bump the version and release again
+npm version patch  # or minor/major
+```
+
+For Docker:
+
+```bash
+# You can overwrite Docker tags
+docker build --platform linux/amd64,linux/arm64 \
+  --tag docdyhr/mcp-wordpress:2.3.0 --push .
+```
+
+## Verification
+
+### Check NPM Publication
+
+```bash
+# Check if version exists
+npm view mcp-wordpress@2.3.0
+
+# Check latest version
+npm view mcp-wordpress version
+
+# View all versions
+npm view mcp-wordpress versions --json
+```
+
+### Check Docker Hub Publication
+
+```bash
+# Pull the image
+docker pull docdyhr/mcp-wordpress:2.3.0
+
+# Check manifest
+docker manifest inspect docdyhr/mcp-wordpress:2.3.0
+
+# API check
+curl -s https://hub.docker.com/v2/repositories/docdyhr/mcp-wordpress/tags | jq '.results[] | select(.name == "2.3.0")'
+```
+
+## Emergency Manual Release Process
+
+If all automated processes fail:
+
+1. **Prepare the release:**
+
+   ```bash
+   git checkout main
+   git pull origin main
+   npm ci
+   npm run build
+   npm test
+   ```
+
+2. **Manual NPM publish:**
+
+   ```bash
+   npm publish
+   ```
+
+3. **Manual Docker publish:**
+
+   ```bash
+   ./scripts/manual-docker-publish.sh
+   ```
+
+4. **Create GitHub release:**
+
+   ```bash
+   gh release create v2.3.0 --title "v2.3.0" --notes "Manual release"
+   ```
+
+## Prevention
+
+### Regular Maintenance
+
+1. **Rotate secrets annually:**
+   - NPM_TOKEN
+   - DOCKER_USERNAME/DOCKER_PASSWORD
+
+2. **Test publishing process:**
+
+   ```bash
+   npm run release:dry
+   ```
+
+3. **Monitor workflow success rates**
+
+### Monitoring
+
+- **GitHub Actions** - Check workflow success rates
+- **NPM** - Monitor download stats for version gaps
+- **Docker Hub** - Check pull statistics
+- **Verification workflow** - Reviews automated issue creation
+
+## Contact
+
+For persistent issues:
+
+1. Check existing GitHub issues with label `publishing-failure`
+2. Create new issue with publishing logs
+3. Contact maintainers if critical

package/docs/api/README.md

@@ -11,7 +11,7 @@
 
 The WordPress MCP Server provides **59 tools** across **10 categories** for comprehensive WordPress management through the Model Context Protocol.
 
-**Last Updated:** 14.7.2025  
+**Last Updated:** 19.7.2025  
 **Version:** 1.2.0  
 **Coverage:** 59/59 tools with examples
 
@@ -66,7 +66,14 @@ wp_get_site_settings --site=production
 | [`wp_create_category`](./tools/wp_create_category.md) | taxonomy | Creates a new category. |
 | [`wp_create_comment`](./tools/wp_create_comment.md) | comment | Creates a new comment on a post. |
 | [`wp_create_page`](./tools/wp_create_page.md) | page | Creates a new page. |
-| [`wp_create_post`](./tools/wp_create_post.md) | post | Creates a new post. |
+| [`wp_create_post`](./tools/wp_create_post.md) | post | Creates a new WordPress post with comprehensive validation and detailed success feedback including management links.
+
+**Usage Examples:**
+• Simple post: `wp_create_post --title="My New Post" --content="<p>Hello World!</p>"`
+• Draft post: `wp_create_post --title="Draft Post" --status="draft"`
+• Categorized post: `wp_create_post --title="Tech News" --categories=[1,5] --tags=[10,20]`
+• Scheduled post: `wp_create_post --title="Future Post" --status="future" --date="2024-12-25T10:00:00"`
+• Complete post: `wp_create_post --title="Complete Post" --content="<p>Content</p>" --excerpt="Summary" --status="publish"` |
 | [`wp_create_tag`](./tools/wp_create_tag.md) | taxonomy | Creates a new tag. |
 | [`wp_create_user`](./tools/wp_create_user.md) | user | Creates a new user. |
 | [`wp_delete_application_password`](./tools/wp_delete_application_password.md) | site | Revokes an existing application password. |
@@ -74,19 +81,25 @@ wp_get_site_settings --site=production
 | [`wp_delete_comment`](./tools/wp_delete_comment.md) | comment | Deletes a comment. |
 | [`wp_delete_media`](./tools/wp_delete_media.md) | media | Deletes a media item. |
 | [`wp_delete_page`](./tools/wp_delete_page.md) | page | Deletes a page. |
-| [`wp_delete_post`](./tools/wp_delete_post.md) | post | Deletes a post. |
+| [`wp_delete_post`](./tools/wp_delete_post.md) | post | Deletes a WordPress post with option for permanent deletion or moving to trash. |
 | [`wp_delete_tag`](./tools/wp_delete_tag.md) | taxonomy | Deletes a tag. |
 | [`wp_delete_user`](./tools/wp_delete_user.md) | user | Deletes a user. |
 | [`wp_get_application_passwords`](./tools/wp_get_application_passwords.md) | site | Lists application passwords for a specific user. |
 | [`wp_get_auth_status`](./tools/wp_get_auth_status.md) | auth | Gets the current authentication status for a configured WordPress site. |
 | [`wp_get_category`](./tools/wp_get_category.md) | taxonomy | Retrieves a single category by its ID. |
 | [`wp_get_comment`](./tools/wp_get_comment.md) | comment | Retrieves a single comment by its ID. |
-| [`wp_get_current_user`](./tools/wp_get_current_user.md) | user | Retrieves the currently authenticated user. |
+| [`wp_get_current_user`](./tools/wp_get_current_user.md) | user | Retrieves the currently authenticated user with comprehensive profile information including roles, capabilities, and account details.
+
+**Usage Examples:**
+• Get current user: `wp_get_current_user`
+• Check permissions: Use this to verify your current user's capabilities and roles
+• Account verification: Confirm you're authenticated with the correct account
+• Profile details: View registration date, email, and user metadata |
 | [`wp_get_media`](./tools/wp_get_media.md) | media | Retrieves a single media item by its ID. |
 | [`wp_get_page`](./tools/wp_get_page.md) | page | Retrieves a single page by its ID. |
 | [`wp_get_page_revisions`](./tools/wp_get_page_revisions.md) | page | Retrieves revisions for a specific page. |
-| [`wp_get_post`](./tools/wp_get_post.md) | post | Retrieves a single post by its ID. |
-| [`wp_get_post_revisions`](./tools/wp_get_post_revisions.md) | post | Retrieves revisions for a specific post. |
+| [`wp_get_post`](./tools/wp_get_post.md) | post | Retrieves detailed information about a single post including metadata, content statistics, and management links. |
+| [`wp_get_post_revisions`](./tools/wp_get_post_revisions.md) | post | Retrieves the revision history for a specific post showing author and modification dates. |
 | [`wp_get_site_settings`](./tools/wp_get_site_settings.md) | site | Retrieves the general settings for a WordPress site. |
 | [`wp_get_tag`](./tools/wp_get_tag.md) | taxonomy | Retrieves a single tag by its ID. |
 | [`wp_get_user`](./tools/wp_get_user.md) | user | Retrieves a single user by their ID. |
@@ -94,24 +107,53 @@ wp_get_site_settings --site=production
 | [`wp_list_comments`](./tools/wp_list_comments.md) | comment | Lists comments from a WordPress site, with filters. |
 | [`wp_list_media`](./tools/wp_list_media.md) | media | Lists media items from a WordPress site, with filters. |
 | [`wp_list_pages`](./tools/wp_list_pages.md) | page | Lists pages from a WordPress site, with filters. |
-| [`wp_list_posts`](./tools/wp_list_posts.md) | post | Lists posts from a WordPress site, with filters. |
+| [`wp_list_posts`](./tools/wp_list_posts.md) | post | Lists posts from a WordPress site with comprehensive filtering options. Supports search, status filtering, and category/tag filtering with enhanced metadata display.
+
+**Usage Examples:**
+• Basic listing: `wp_list_posts`
+• Search posts: `wp_list_posts --search="AI trends"`
+• Filter by status: `wp_list_posts --status="draft"`
+• Category filtering: `wp_list_posts --categories=[1,2,3]`
+• Paginated results: `wp_list_posts --per_page=20 --page=2`
+• Combined filters: `wp_list_posts --search="WordPress" --status="publish" --per_page=10` |
 | [`wp_list_tags`](./tools/wp_list_tags.md) | taxonomy | Lists tags from a WordPress site. |
-| [`wp_list_users`](./tools/wp_list_users.md) | user | Lists users from a WordPress site, with filters. |
+| [`wp_list_users`](./tools/wp_list_users.md) | user | Lists users from a WordPress site with comprehensive filtering and detailed user information including roles, registration dates, and activity status.
+
+**Usage Examples:**
+• List all users: `wp_list_users`
+• Search users: `wp_list_users --search="john"`
+• Filter by role: `wp_list_users --roles=["editor","author"]`
+• Find admins: `wp_list_users --roles=["administrator"]`
+• Combined search: `wp_list_users --search="smith" --roles=["subscriber"]` |
 | [`wp_performance_alerts`](./tools/wp_performance_alerts.md) | performance | Get performance alerts and anomaly detection results |
 | [`wp_performance_benchmark`](./tools/wp_performance_benchmark.md) | performance | Compare current performance against industry benchmarks |
 | [`wp_performance_export`](./tools/wp_performance_export.md) | performance | Export comprehensive performance report |
 | [`wp_performance_history`](./tools/wp_performance_history.md) | performance | Get historical performance data and trends |
 | [`wp_performance_optimize`](./tools/wp_performance_optimize.md) | performance | Get optimization recommendations and insights |
 | [`wp_performance_stats`](./tools/wp_performance_stats.md) | performance | Get real-time performance statistics and metrics |
-| [`wp_search_site`](./tools/wp_search_site.md) | site | Performs a site-wide search for content. |
+| [`wp_search_site`](./tools/wp_search_site.md) | site | Performs a site-wide search for content across posts, pages, and media with comprehensive results and metadata.
+
+**Usage Examples:**
+• Search everything: `wp_search_site --term="WordPress"`
+• Search posts only: `wp_search_site --term="tutorial" --type="posts"`
+• Search pages: `wp_search_site --term="about" --type="pages"`
+• Search media: `wp_search_site --term="logo" --type="media"`
+• Find specific content: `wp_search_site --term="contact form"` |
 | [`wp_spam_comment`](./tools/wp_spam_comment.md) | comment | Marks a comment as spam. |
 | [`wp_switch_auth_method`](./tools/wp_switch_auth_method.md) | auth | Switches the authentication method for a site for the current session. |
-| [`wp_test_auth`](./tools/wp_test_auth.md) | auth | Tests the authentication and connectivity for a configured WordPress site. |
+| [`wp_test_auth`](./tools/wp_test_auth.md) | auth | Tests the authentication and connectivity for a configured WordPress site with detailed connection diagnostics.
+
+**Usage Examples:**
+• Test connection: `wp_test_auth`
+• Multi-site test: `wp_test_auth --site="my-site"`
+• Verify setup: Use this after configuring new credentials
+• Troubleshoot: Run when experiencing connection issues
+• Health check: Regular verification of WordPress connectivity |
 | [`wp_update_category`](./tools/wp_update_category.md) | taxonomy | Updates an existing category. |
 | [`wp_update_comment`](./tools/wp_update_comment.md) | comment | Updates an existing comment. |
 | [`wp_update_media`](./tools/wp_update_media.md) | media | Updates the metadata of an existing media item. |
 | [`wp_update_page`](./tools/wp_update_page.md) | page | Updates an existing page. |
-| [`wp_update_post`](./tools/wp_update_post.md) | post | Updates an existing post. |
+| [`wp_update_post`](./tools/wp_update_post.md) | post | Updates an existing WordPress post with validation and detailed confirmation. |
 | [`wp_update_site_settings`](./tools/wp_update_site_settings.md) | site | Updates one or more general settings for a WordPress site. |
 | [`wp_update_tag`](./tools/wp_update_tag.md) | taxonomy | Updates an existing tag. |
 | [`wp_update_user`](./tools/wp_update_user.md) | user | Updates an existing user. |

package/docs/api/openapi.json

@@ -487,7 +487,7 @@
     },
     "/tools/wp_create_post": {
       "post": {
-        "summary": "Creates a new post.",
+        "summary": "Creates a new WordPress post with comprehensive validation and detailed success feedback including management links.\n\n**Usage Examples:**\n• Simple post: `wp_create_post --title=\"My New Post\" --content=\"<p>Hello World!</p>\"`\n• Draft post: `wp_create_post --title=\"Draft Post\" --status=\"draft\"`\n• Categorized post: `wp_create_post --title=\"Tech News\" --categories=[1,5] --tags=[10,20]`\n• Scheduled post: `wp_create_post --title=\"Future Post\" --status=\"future\" --date=\"2024-12-25T10:00:00\"`\n• Complete post: `wp_create_post --title=\"Complete Post\" --content=\"<p>Content</p>\" --excerpt=\"Summary\" --status=\"publish\"`",
         "description": "Execute wp_create_post MCP tool",
         "tags": [
           "post"
@@ -938,7 +938,7 @@
     },
     "/tools/wp_delete_post": {
       "post": {
-        "summary": "Deletes a post.",
+        "summary": "Deletes a WordPress post with option for permanent deletion or moving to trash.",
         "description": "Execute wp_delete_post MCP tool",
         "tags": [
           "post"
@@ -1281,7 +1281,7 @@
     },
     "/tools/wp_get_current_user": {
       "post": {
-        "summary": "Retrieves the currently authenticated user.",
+        "summary": "Retrieves the currently authenticated user with comprehensive profile information including roles, capabilities, and account details.\n\n**Usage Examples:**\n• Get current user: `wp_get_current_user`\n• Check permissions: Use this to verify your current user's capabilities and roles\n• Account verification: Confirm you're authenticated with the correct account\n• Profile details: View registration date, email, and user metadata",
         "description": "Execute wp_get_current_user MCP tool",
         "tags": [
           "user"
@@ -1469,7 +1469,7 @@
     },
     "/tools/wp_get_post": {
       "post": {
-        "summary": "Retrieves a single post by its ID.",
+        "summary": "Retrieves detailed information about a single post including metadata, content statistics, and management links.",
         "description": "Execute wp_get_post MCP tool",
         "tags": [
           "post"
@@ -1518,7 +1518,7 @@
     },
     "/tools/wp_get_post_revisions": {
       "post": {
-        "summary": "Retrieves revisions for a specific post.",
+        "summary": "Retrieves the revision history for a specific post showing author and modification dates.",
         "description": "Execute wp_get_post_revisions MCP tool",
         "tags": [
           "post"
@@ -1932,7 +1932,7 @@
     },
     "/tools/wp_list_posts": {
       "post": {
-        "summary": "Lists posts from a WordPress site, with filters.",
+        "summary": "Lists posts from a WordPress site with comprehensive filtering options. Supports search, status filtering, and category/tag filtering with enhanced metadata display.\n\n**Usage Examples:**\n• Basic listing: `wp_list_posts`\n• Search posts: `wp_list_posts --search=\"AI trends\"`\n• Filter by status: `wp_list_posts --status=\"draft\"`\n• Category filtering: `wp_list_posts --categories=[1,2,3]`\n• Paginated results: `wp_list_posts --per_page=20 --page=2`\n• Combined filters: `wp_list_posts --search=\"WordPress\" --status=\"publish\" --per_page=10`",
         "description": "Execute wp_list_posts MCP tool",
         "tags": [
           "post"
@@ -2049,7 +2049,7 @@
     },
     "/tools/wp_list_users": {
       "post": {
-        "summary": "Lists users from a WordPress site, with filters.",
+        "summary": "Lists users from a WordPress site with comprehensive filtering and detailed user information including roles, registration dates, and activity status.\n\n**Usage Examples:**\n• List all users: `wp_list_users`\n• Search users: `wp_list_users --search=\"john\"`\n• Filter by role: `wp_list_users --roles=[\"editor\",\"author\"]`\n• Find admins: `wp_list_users --roles=[\"administrator\"]`\n• Combined search: `wp_list_users --search=\"smith\" --roles=[\"subscriber\"]`",
         "description": "Execute wp_list_users MCP tool",
         "tags": [
           "user"
@@ -2511,7 +2511,7 @@
     },
     "/tools/wp_search_site": {
       "post": {
-        "summary": "Performs a site-wide search for content.",
+        "summary": "Performs a site-wide search for content across posts, pages, and media with comprehensive results and metadata.\n\n**Usage Examples:**\n• Search everything: `wp_search_site --term=\"WordPress\"`\n• Search posts only: `wp_search_site --term=\"tutorial\" --type=\"posts\"`\n• Search pages: `wp_search_site --term=\"about\" --type=\"pages\"`\n• Search media: `wp_search_site --term=\"logo\" --type=\"media\"`\n• Find specific content: `wp_search_site --term=\"contact form\"`",
         "description": "Execute wp_search_site MCP tool",
         "tags": [
           "site"
@@ -2674,7 +2674,7 @@
     },
     "/tools/wp_test_auth": {
       "post": {
-        "summary": "Tests the authentication and connectivity for a configured WordPress site.",
+        "summary": "Tests the authentication and connectivity for a configured WordPress site with detailed connection diagnostics.\n\n**Usage Examples:**\n• Test connection: `wp_test_auth`\n• Multi-site test: `wp_test_auth --site=\"my-site\"`\n• Verify setup: Use this after configuring new credentials\n• Troubleshoot: Run when experiencing connection issues\n• Health check: Regular verification of WordPress connectivity",
         "description": "Execute wp_test_auth MCP tool",
         "tags": [
           "auth"
@@ -2967,7 +2967,7 @@
     },
     "/tools/wp_update_post": {
       "post": {
-        "summary": "Updates an existing post.",
+        "summary": "Updates an existing WordPress post with validation and detailed confirmation.",
         "description": "Execute wp_update_post MCP tool",
         "tags": [
           "post"

package/docs/api/summary.json

@@ -2,7 +2,7 @@
   "totalTools": 59,
   "totalCategories": 10,
   "totalTypes": 1,
-  "lastUpdated": "2025-07-14T17:43:04.283Z",
+  "lastUpdated": "2025-07-19T13:22:47.886Z",
   "version": "1.2.0",
   "coverage": {
     "toolsWithExamples": 59,

package/docs/api/tools/wp_create_post.md

@@ -2,7 +2,14 @@
 
 ![post](https://img.shields.io/badge/category-post-lightgrey)
 
-Creates a new post.
+Creates a new WordPress post with comprehensive validation and detailed success feedback including management links.
+
+**Usage Examples:**
+• Simple post: `wp_create_post --title="My New Post" --content="<p>Hello World!</p>"`
+• Draft post: `wp_create_post --title="Draft Post" --status="draft"`
+• Categorized post: `wp_create_post --title="Tech News" --categories=[1,5] --tags=[10,20]`
+• Scheduled post: `wp_create_post --title="Future Post" --status="future" --date="2024-12-25T10:00:00"`
+• Complete post: `wp_create_post --title="Complete Post" --content="<p>Content</p>" --excerpt="Summary" --status="publish"`
 
 ## Parameters
 
@@ -75,8 +82,7 @@ wp_create_post --title="Example Post Title" --content="This is example content f
 
 **Endpoint:** `/wp-json/wp/v2/posts`
 
-This tool directly interfaces with the WordPress REST API endpoint above. The response format and available
-parameters are determined by WordPress core functionality.
+This tool directly interfaces with the WordPress REST API endpoint above. The response format and available parameters are determined by WordPress core functionality.
 
 ### WordPress Documentation
 - [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)

package/docs/api/tools/wp_delete_post.md

@@ -2,7 +2,7 @@
 
 ![post](https://img.shields.io/badge/category-post-lightgrey)
 
-Deletes a post.
+Deletes a WordPress post with option for permanent deletion or moving to trash.
 
 ## Parameters
 
@@ -46,8 +46,7 @@ wp_delete_post --id="123"
 
 **Endpoint:** `/wp-json/wp/v2/posts/{id}`
 
-This tool directly interfaces with the WordPress REST API endpoint above. The response format and available
-parameters are determined by WordPress core functionality.
+This tool directly interfaces with the WordPress REST API endpoint above. The response format and available parameters are determined by WordPress core functionality.
 
 ### WordPress Documentation
 - [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)

package/docs/api/tools/wp_get_current_user.md

@@ -2,7 +2,13 @@
 
 ![user](https://img.shields.io/badge/category-user-lightgrey)
 
-Retrieves the currently authenticated user.
+Retrieves the currently authenticated user with comprehensive profile information including roles, capabilities, and account details.
+
+**Usage Examples:**
+• Get current user: `wp_get_current_user`
+• Check permissions: Use this to verify your current user's capabilities and roles
+• Account verification: Confirm you're authenticated with the correct account
+• Profile details: View registration date, email, and user metadata
 
 ## Parameters
 

package/docs/api/tools/wp_get_post.md

@@ -2,7 +2,7 @@
 
 ![post](https://img.shields.io/badge/category-post-lightgrey)
 
-Retrieves a single post by its ID.
+Retrieves detailed information about a single post including metadata, content statistics, and management links.
 
 ## Parameters
 
@@ -48,8 +48,7 @@ wp_get_post --id="123"
 
 **Endpoint:** `/wp-json/wp/v2/posts/{id}`
 
-This tool directly interfaces with the WordPress REST API endpoint above. The response format and available
-parameters are determined by WordPress core functionality.
+This tool directly interfaces with the WordPress REST API endpoint above. The response format and available parameters are determined by WordPress core functionality.
 
 ### WordPress Documentation
 - [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)

package/docs/api/tools/wp_get_post_revisions.md

@@ -2,7 +2,7 @@
 
 ![post](https://img.shields.io/badge/category-post-lightgrey)
 
-Retrieves revisions for a specific post.
+Retrieves the revision history for a specific post showing author and modification dates.
 
 ## Parameters
 

package/docs/api/tools/wp_list_posts.md

@@ -2,7 +2,15 @@
 
 ![post](https://img.shields.io/badge/category-post-lightgrey)
 
-Lists posts from a WordPress site, with filters.
+Lists posts from a WordPress site with comprehensive filtering options. Supports search, status filtering, and category/tag filtering with enhanced metadata display.
+
+**Usage Examples:**
+• Basic listing: `wp_list_posts`
+• Search posts: `wp_list_posts --search="AI trends"`
+• Filter by status: `wp_list_posts --status="draft"`
+• Category filtering: `wp_list_posts --categories=[1,2,3]`
+• Paginated results: `wp_list_posts --per_page=20 --page=2`
+• Combined filters: `wp_list_posts --search="WordPress" --status="publish" --per_page=10`
 
 ## Parameters
 
@@ -92,8 +100,7 @@ wp_list_posts --per_page="10" --search="wordpress" --status="publish" --categori
 
 **Endpoint:** `/wp-json/wp/v2/posts`
 
-This tool directly interfaces with the WordPress REST API endpoint above. The response format and available
-parameters are determined by WordPress core functionality.
+This tool directly interfaces with the WordPress REST API endpoint above. The response format and available parameters are determined by WordPress core functionality.
 
 ### WordPress Documentation
 - [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)

package/docs/api/tools/wp_list_users.md

@@ -2,7 +2,14 @@
 
 ![user](https://img.shields.io/badge/category-user-lightgrey)
 
-Lists users from a WordPress site, with filters.
+Lists users from a WordPress site with comprehensive filtering and detailed user information including roles, registration dates, and activity status.
+
+**Usage Examples:**
+• List all users: `wp_list_users`
+• Search users: `wp_list_users --search="john"`
+• Filter by role: `wp_list_users --roles=["editor","author"]`
+• Find admins: `wp_list_users --roles=["administrator"]`
+• Combined search: `wp_list_users --search="smith" --roles=["subscriber"]`
 
 ## Parameters
 

package/docs/api/tools/wp_search_site.md

@@ -2,7 +2,14 @@
 
 ![site](https://img.shields.io/badge/category-site-lightblue)
 
-Performs a site-wide search for content.
+Performs a site-wide search for content across posts, pages, and media with comprehensive results and metadata.
+
+**Usage Examples:**
+• Search everything: `wp_search_site --term="WordPress"`
+• Search posts only: `wp_search_site --term="tutorial" --type="posts"`
+• Search pages: `wp_search_site --term="about" --type="pages"`
+• Search media: `wp_search_site --term="logo" --type="media"`
+• Find specific content: `wp_search_site --term="contact form"`
 
 ## Parameters
 

package/docs/api/tools/wp_test_auth.md

@@ -2,7 +2,14 @@
 
 ![auth](https://img.shields.io/badge/category-auth-darkblue)
 
-Tests the authentication and connectivity for a configured WordPress site.
+Tests the authentication and connectivity for a configured WordPress site with detailed connection diagnostics.
+
+**Usage Examples:**
+• Test connection: `wp_test_auth`
+• Multi-site test: `wp_test_auth --site="my-site"`
+• Verify setup: Use this after configuring new credentials
+• Troubleshoot: Run when experiencing connection issues
+• Health check: Regular verification of WordPress connectivity
 
 ## Parameters
 

package/docs/api/tools/wp_update_post.md

@@ -2,7 +2,7 @@
 
 ![post](https://img.shields.io/badge/category-post-lightgrey)
 
-Updates an existing post.
+Updates an existing WordPress post with validation and detailed confirmation.
 
 ## Parameters
 
@@ -73,8 +73,7 @@ wp_update_post --id="123" --title="Example Post Title" --content="This is exampl
 
 **Endpoint:** `/wp-json/wp/v2/posts/{id}`
 
-This tool directly interfaces with the WordPress REST API endpoint above. The response format and available
-parameters are determined by WordPress core functionality.
+This tool directly interfaces with the WordPress REST API endpoint above. The response format and available parameters are determined by WordPress core functionality.
 
 ### WordPress Documentation
 - [WordPress REST API Handbook](https://developer.wordpress.org/rest-api/)