mcp-wordpress 1.1.7 → 1.2.2

package/docs/SECURITY_TESTING.md

@@ -0,0 +1,393 @@
+# Security Testing Guide
+
+![Security](https://img.shields.io/badge/security-hardened-brightgreen)
+![Testing](https://img.shields.io/badge/testing-comprehensive-blue)
+![Validation](https://img.shields.io/badge/validation-strict-orange)
+
+This guide covers the comprehensive security testing and validation framework implemented in the MCP WordPress Server.
+
+## 🔒 Security Framework Overview
+
+### Core Security Components
+
+1. **Input Validation** (`src/security/InputValidator.ts`)
+   - Zod-based schema validation
+   - XSS protection patterns
+   - SQL injection prevention
+   - Path traversal protection
+
+2. **Rate Limiting** (`SecurityLimiter` class)
+   - Request throttling per user/IP
+   - DoS attack prevention
+   - Automatic cleanup of expired entries
+
+3. **Input Sanitization** (`InputSanitizer` class)
+   - HTML content sanitization
+   - Search query cleaning
+   - File path normalization
+   - Output encoding for safe display
+
+4. **Security Testing** (`tests/security/`)
+   - Comprehensive vulnerability tests
+   - Penetration testing scenarios
+   - Edge case validation
+
+## 🛡️ Validation Schemas
+
+### Core Security Schemas
+
+```typescript
+// Safe string validation (XSS protection)
+SecuritySchemas.safeString
+  .max(10000)
+  .refine(val => !SCRIPT_PATTERN.test(val))
+  .refine(val => !val.includes('javascript:'))
+
+// URL validation
+SecuritySchemas.url
+  .url()
+  .regex(URL_PATTERN)
+  .refine(val => !val.includes('javascript:'))
+
+// Search query validation (SQL injection protection)
+SecuritySchemas.searchQuery
+  .max(500)
+  .refine(val => !SQL_INJECTION_PATTERN.test(val))
+  .refine(val => !val.includes('--'))
+```
+
+### Tool-Specific Schemas
+
+```typescript
+// Post creation validation
+ToolSchemas.postData = z.object({
+  site: SecuritySchemas.siteId.optional(),
+  title: SecuritySchemas.safeString.optional(),
+  content: SecuritySchemas.wpContent.optional(),
+  status: z.enum(['publish', 'draft', 'private', 'pending']).optional()
+});
+
+// User management validation
+ToolSchemas.userData = z.object({
+  username: SecuritySchemas.slug,
+  email: SecuritySchemas.email,
+  password: SecuritySchemas.safeString.optional()
+});
+```
+
+## 🧪 Security Tests
+
+### 1. XSS Protection Tests
+
+```bash
+npm test tests/security/security-validation.test.js -- --grep "XSS"
+```
+
+**Covered Attack Vectors:**
+- Script tag injection
+- Event handler injection
+- JavaScript URL schemes
+- Data URL schemes
+- HTML entity encoding
+
+**Example Test:**
+```javascript
+test('should reject script tags in safe strings', () => {
+  const maliciousInput = 'Hello <script>alert("XSS")</script> World';
+  expect(() => SecuritySchemas.safeString.parse(maliciousInput)).toThrow();
+});
+```
+
+### 2. SQL Injection Protection Tests
+
+```bash
+npm test tests/security/security-validation.test.js -- --grep "SQL"
+```
+
+**Covered Attack Vectors:**
+- Union-based injection
+- Boolean-based blind injection
+- Time-based blind injection
+- Error-based injection
+- Comment-based injection
+
+**Example Test:**
+```javascript
+test('should reject SQL injection patterns', () => {
+  const maliciousQueries = [
+    "'; DROP TABLE wp_posts; --",
+    "1' OR '1'='1",
+    "admin'--"
+  ];
+  
+  maliciousQueries.forEach(query => {
+    expect(() => SecuritySchemas.searchQuery.parse(query)).toThrow();
+  });
+});
+```
+
+### 3. Path Traversal Protection Tests
+
+```bash
+npm test tests/security/security-validation.test.js -- --grep "Path"
+```
+
+**Covered Attack Vectors:**
+- Directory traversal (../)
+- Encoded path traversal
+- Windows path traversal (..\\)
+- Absolute path injection
+
+### 4. Penetration Testing Suite
+
+```bash
+npm test tests/security/penetration-tests.test.js
+```
+
+**Comprehensive Attack Simulation:**
+- Command injection attempts
+- Authentication bypass
+- Header injection
+- Rate limiting bypass
+- Large payload attacks
+
+## 🔧 Implementation Guide
+
+### Adding Security to New Tools
+
+1. **Import Security Framework:**
+```typescript
+import { validateSecurity, ToolSchemas } from '../security/InputValidator.js';
+```
+
+2. **Apply Validation Decorator:**
+```typescript
+export class MyTools {
+  @validateSecurity(ToolSchemas.postData)
+  async createPost(params: any): Promise<any> {
+    // Tool implementation
+  }
+}
+```
+
+3. **Custom Validation Schema:**
+```typescript
+const customSchema = z.object({
+  customField: SecuritySchemas.safeString,
+  numericField: SecuritySchemas.wpId
+});
+
+@validateSecurity(customSchema)
+async customTool(params: any) {
+  // Implementation
+}
+```
+
+### Manual Input Sanitization
+
+```typescript
+import { InputSanitizer } from '../security/InputValidator.js';
+
+// Sanitize HTML content
+const safeHtml = InputSanitizer.sanitizeHtml(userInput);
+
+// Sanitize search queries
+const safeQuery = InputSanitizer.sanitizeSearchQuery(searchInput);
+
+// Encode output for display
+const safeOutput = InputSanitizer.encodeOutput(userContent);
+```
+
+### Rate Limiting Integration
+
+```typescript
+import { SecurityLimiter } from '../security/InputValidator.js';
+
+async function toolMethod(params: any) {
+  const userId = params.userId || 'anonymous';
+  
+  if (!SecurityLimiter.checkRateLimit(userId)) {
+    throw new Error('Rate limit exceeded. Please try again later.');
+  }
+  
+  // Continue with tool logic
+}
+```
+
+## 🚨 Security Testing Commands
+
+### Run All Security Tests
+```bash
+npm run test:security
+```
+
+### Run Specific Security Test Categories
+```bash
+# Input validation tests
+npm test tests/security/security-validation.test.js
+
+# Penetration testing
+npm test tests/security/penetration-tests.test.js
+
+# XSS protection only
+npm test -- --grep "XSS"
+
+# SQL injection protection only
+npm test -- --grep "SQL"
+```
+
+### Security Test Coverage
+```bash
+npm run test:coverage -- tests/security/
+```
+
+## 📊 Security Monitoring
+
+### Error Logging
+Security validation errors are automatically logged:
+
+```typescript
+{
+  timestamp: "2024-01-01T00:00:00.000Z",
+  level: "error",
+  method: "wp_create_post",
+  error: "Security validation failed",
+  details: {
+    field: "title",
+    violation: "Script tags not allowed"
+  }
+}
+```
+
+### Rate Limiting Monitoring
+```typescript
+{
+  timestamp: "2024-01-01T00:00:00.000Z",
+  level: "warning", 
+  event: "rate_limit_exceeded",
+  userId: "user123",
+  requestCount: 1001,
+  windowMs: 60000
+}
+```
+
+## 🔍 Security Audit Checklist
+
+### ✅ Input Validation
+- [ ] All user inputs validated with Zod schemas
+- [ ] XSS protection on all text fields
+- [ ] SQL injection protection on search/query fields
+- [ ] Path traversal protection on file operations
+- [ ] Length limits enforced on all inputs
+
+### ✅ Output Encoding
+- [ ] HTML entities encoded in output
+- [ ] JSON responses properly escaped
+- [ ] Error messages sanitized
+- [ ] Log entries do not contain sensitive data
+
+### ✅ Authentication & Authorization
+- [ ] Rate limiting implemented
+- [ ] Secure password handling
+- [ ] Session management (if applicable)
+- [ ] Permission checks on all operations
+
+### ✅ Error Handling
+- [ ] Sensitive information not exposed in errors
+- [ ] Consistent error response format
+- [ ] Proper logging without data leakage
+- [ ] Graceful handling of edge cases
+
+### ✅ File Operations
+- [ ] Upload restrictions enforced
+- [ ] File type validation
+- [ ] Size limits implemented
+- [ ] Path sanitization applied
+
+## 🛠️ Security Tools Integration
+
+### ESLint Security Rules
+```javascript
+{
+  "extends": ["plugin:security/recommended"],
+  "rules": {
+    "security/detect-sql-injection": "error",
+    "security/detect-unsafe-regex": "error",
+    "security/detect-buffer-noassert": "error"
+  }
+}
+```
+
+### Automated Security Scanning
+```bash
+# Add to package.json
+{
+  "scripts": {
+    "security:audit": "npm audit --production",
+    "security:scan": "node scripts/security-check.js",
+    "security:fix": "npm audit fix"
+  }
+}
+```
+
+### CI/CD Security Pipeline
+```yaml
+# GitHub Actions workflow
+- name: Security Audit
+  run: |
+    npm audit --audit-level moderate
+    npm run test:security
+    npm run security:scan
+```
+
+## 📚 Best Practices
+
+### Input Validation Best Practices
+1. **Validate Early**: Check inputs at the entry point
+2. **Use Allow Lists**: Define what is allowed, not what is blocked
+3. **Sanitize and Validate**: Both sanitize and validate inputs
+4. **Fail Securely**: Default to rejecting invalid input
+
+### Error Handling Best Practices
+1. **Generic Error Messages**: Don't expose implementation details
+2. **Log Detailed Errors**: Log full details for debugging (securely)
+3. **Rate Limit Errors**: Prevent information gathering
+4. **Sanitize Stack Traces**: Remove sensitive information
+
+### Security Testing Best Practices
+1. **Test All Input Vectors**: Every parameter that accepts user input
+2. **Use Real Attack Payloads**: Test with actual malicious inputs
+3. **Automate Security Tests**: Include in CI/CD pipeline
+4. **Regular Security Reviews**: Periodic manual code reviews
+
+## 🚀 Continuous Security
+
+### Regular Security Updates
+- Monthly dependency audits
+- Quarterly penetration testing
+- Annual security architecture review
+- Continuous monitoring and alerting
+
+### Security Metrics
+- Number of blocked malicious requests
+- Rate limiting effectiveness
+- Input validation error rates
+- Security test coverage percentage
+
+## 📞 Security Incident Response
+
+### If You Discover a Vulnerability
+1. **Do Not** create a public issue
+2. **Do** email security concerns privately
+3. **Include** steps to reproduce
+4. **Provide** impact assessment if possible
+
+### Response Timeline
+- **24 hours**: Initial acknowledgment
+- **72 hours**: Preliminary assessment
+- **7 days**: Fix development and testing
+- **14 days**: Patched release and disclosure
+
+---
+
+**🔒 Security is a shared responsibility - implement, test, and monitor continuously!**

package/docs/api/README.md

@@ -0,0 +1,200 @@
+# WordPress MCP Server - API Documentation
+
+![Version](https://img.shields.io/badge/version-1.2.0-blue)
+![Tools](https://img.shields.io/badge/tools-60+-green)
+![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+
+## Overview
+
+The WordPress MCP Server provides **59 tools** across **10 categories** for comprehensive WordPress management through the Model Context Protocol.
+
+**Last Updated:** 30.6.2025  
+**Version:** 1.2.0  
+**Coverage:** 59/59 tools with examples
+
+## Quick Start
+
+### Basic Usage
+```bash
+# List all posts
+wp_list_posts
+
+# Get specific post
+wp_get_post --id=123
+
+# Create new post
+wp_create_post --title="My Post" --content="Post content"
+```
+
+### Multi-Site Usage
+```bash
+# Target specific site
+wp_list_posts --site=site1
+
+# Use with different authentication
+wp_get_site_settings --site=production
+```
+
+## Tool Categories
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| [comment](./categories/comment.md) | 7 | comment management tools |
+| [cache](./categories/cache.md) | 4 | Performance caching and optimization tools |
+| [site](./categories/site.md) | 6 | Site settings and configuration tools |
+| [taxonomy](./categories/taxonomy.md) | 10 | taxonomy management tools |
+| [page](./categories/page.md) | 6 | page management tools |
+| [post](./categories/post.md) | 6 | post management tools |
+| [user](./categories/user.md) | 6 | user management tools |
+| [media](./categories/media.md) | 5 | File upload, management, and media library tools |
+| [auth](./categories/auth.md) | 3 | Authentication testing and management tools |
+| [performance](./categories/performance.md) | 6 | Performance monitoring and analytics tools |
+
+## Available Tools
+
+| Tool | Category | Description |
+|------|----------|-------------|
+| [`wp_approve_comment`](./tools/wp_approve_comment.md) | comment | Approves a pending comment. |
+| [`wp_cache_clear`](./tools/wp_cache_clear.md) | cache | Clear cache for a WordPress site. |
+| [`wp_cache_info`](./tools/wp_cache_info.md) | cache | Get detailed cache configuration and status information. |
+| [`wp_cache_stats`](./tools/wp_cache_stats.md) | cache | Get cache statistics for a WordPress site. |
+| [`wp_cache_warm`](./tools/wp_cache_warm.md) | cache | Pre-warm cache with essential WordPress data. |
+| [`wp_create_application_password`](./tools/wp_create_application_password.md) | site | Creates a new application password for a user. |
+| [`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_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. |
+| [`wp_delete_category`](./tools/wp_delete_category.md) | taxonomy | Deletes a category. |
+| [`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_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_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_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. |
+| [`wp_list_categories`](./tools/wp_list_categories.md) | taxonomy | Lists categories from a WordPress site. |
+| [`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_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_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_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_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_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. |
+| [`wp_upload_media`](./tools/wp_upload_media.md) | media | Uploads a file to the WordPress media library. |
+
+## Authentication
+
+All tools support multiple authentication methods:
+- **Application Passwords** (recommended)
+- **JWT Authentication** 
+- **Basic Authentication** (development only)
+- **API Key Authentication**
+
+## Error Handling
+
+Standard error response format:
+```json
+{
+  "error": "Error type",
+  "message": "Human-readable error message",
+  "code": "ERROR_CODE",
+  "details": {
+    "endpoint": "/wp-json/wp/v2/posts",
+    "method": "GET"
+  }
+}
+```
+
+## Configuration
+
+### Multi-Site Configuration
+```json
+{
+  "sites": [
+    {
+      "id": "site1",
+      "name": "My WordPress Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://example.com",
+        "WORDPRESS_USERNAME": "username",
+        "WORDPRESS_APP_PASSWORD": "app_password"
+      }
+    }
+  ]
+}
+```
+
+## Response Formats
+
+All tools return responses in this format:
+```json
+{
+  "success": true,
+  "data": {
+    // Tool-specific response data
+  },
+  "metadata": {
+    "timestamp": "2024-01-01T00:00:00.000Z",
+    "site": "site1",
+    "tool": "wp_list_posts"
+  }
+}
+```
+
+## Performance Monitoring
+
+The server includes comprehensive performance monitoring:
+- Real-time metrics collection
+- Historical performance analysis
+- Industry benchmark comparisons
+- Automated optimization recommendations
+
+See [Performance Monitoring Guide](./performance/README.md) for details.
+
+## Additional Resources
+
+- [Tool Reference](./tools/README.md) - Detailed tool documentation
+- [Type Definitions](./types/README.md) - TypeScript type definitions
+- [Examples](./examples/README.md) - Usage examples and workflows
+- [OpenAPI Specification](./openapi.json) - Machine-readable API spec
+
+## Support
+
+- **Documentation:** [GitHub Repository](https://github.com/docdyhr/mcp-wordpress)
+- **Issues:** [GitHub Issues](https://github.com/docdyhr/mcp-wordpress/issues)
+- **Discussions:** [GitHub Discussions](https://github.com/docdyhr/mcp-wordpress/discussions)

package/docs/api/categories/auth.md

@@ -0,0 +1,40 @@
+# auth Tools
+
+Authentication testing and management tools
+
+**Tool Count:** 3
+
+## Available Tools
+
+- [`wp_get_auth_status`](./tools/wp_get_auth_status.md)
+- [`wp_switch_auth_method`](./tools/wp_switch_auth_method.md)
+- [`wp_test_auth`](./tools/wp_test_auth.md)
+
+## Common Usage Patterns
+
+- Manage auth efficiently
+- Bulk auth operations
+- Search and filter auth
+
+## Examples
+
+### Basic auth Workflow
+```bash
+# List all auth
+wp_list_auth
+
+# Get specific item
+wp_get_aut --id=123
+
+# Create new item  
+wp_create_aut --title="Example"
+```
+
+### Multi-Site auth Management
+```bash
+# Work with specific site
+wp_list_auth --site=production
+
+# Bulk operations
+wp_list_auth --site=staging --limit=50
+```

package/docs/api/categories/cache.md

@@ -0,0 +1,41 @@
+# cache Tools
+
+Performance caching and optimization tools
+
+**Tool Count:** 4
+
+## Available Tools
+
+- [`wp_cache_clear`](./tools/wp_cache_clear.md)
+- [`wp_cache_info`](./tools/wp_cache_info.md)
+- [`wp_cache_stats`](./tools/wp_cache_stats.md)
+- [`wp_cache_warm`](./tools/wp_cache_warm.md)
+
+## Common Usage Patterns
+
+- Manage cache efficiently
+- Bulk cache operations
+- Search and filter cache
+
+## Examples
+
+### Basic cache Workflow
+```bash
+# List all cache
+wp_list_cache
+
+# Get specific item
+wp_get_cach --id=123
+
+# Create new item  
+wp_create_cach --title="Example"
+```
+
+### Multi-Site cache Management
+```bash
+# Work with specific site
+wp_list_cache --site=production
+
+# Bulk operations
+wp_list_cache --site=staging --limit=50
+```