mcp-wordpress 1.2.3 → 1.3.1

package/docs/developer/REFACTORING.md

@@ -7,55 +7,67 @@ This document outlines the technical debt refactoring performed to improve code
 ## Issues Addressed
 
 ### 1. Large API Client Class (1043 lines)
+
 **Problem**: The `WordPressClient` class violated the Single Responsibility Principle and was difficult to maintain.
 
 **Solution**: Implemented composition pattern with specialized managers:
+
 - `BaseManager`: Common functionality and error handling
 - `AuthenticationManager`: All authentication methods and token management  
 - `RequestManager`: HTTP operations, rate limiting, and retries
 - `WordPressClient`: Refactored to orchestrate managers
 
 **Benefits**:
+
 - Reduced complexity from 1043 lines to ~300 lines per component
 - Improved testability with focused responsibilities
 - Enhanced maintainability and extensibility
 
 ### 2. Repetitive Error Handling (49 identical try-catch blocks)
+
 **Problem**: Duplicated error handling across all tool classes.
 
 **Solution**: Created standardized error handling utilities:
+
 - `withErrorHandling()`: Function wrapper for consistent error handling
 - `withValidation()`: Combines validation and error handling
 - `errorHandler()`: Decorator for class methods
 - Common validators for frequent validation patterns
 
 **Benefits**:
+
 - Reduced code duplication by ~70%
 - Consistent error messages and handling
 - Easier to maintain and update error handling logic
 
 ### 3. Unused Dependencies and Imports
+
 **Problem**: Unused imports and missing dependencies causing build issues.
 
 **Solution**:
+
 - Removed unused `open` import from `auth.ts`
 - Added missing `@jest/globals` dependency
 - Verified all imports are actually used
 
 **Benefits**:
+
 - Cleaner codebase
 - Faster builds
 - No dependency security risks from unused packages
 
 ### 4. Poor Code Organization
+
 **Problem**: Scattered functionality and inconsistent patterns.
 
 **Solution**:
+
 - Created `managers/` directory for client components
 - Added `toolWrapper.ts` for shared tool utilities
 - Improved import organization and file structure
 
 **Benefits**:
+
 - Better code discoverability
 - Clearer architectural boundaries
 - Easier onboarding for new developers
@@ -63,6 +75,7 @@ This document outlines the technical debt refactoring performed to improve code
 ## Files Created
 
 ### Core Architecture
+
 - `src/client/managers/BaseManager.ts` - Base class with common functionality
 - `src/client/managers/AuthenticationManager.ts` - Authentication handling
 - `src/client/managers/RequestManager.ts` - HTTP request management
@@ -70,20 +83,24 @@ This document outlines the technical debt refactoring performed to improve code
 - `src/client/WordPressClient.ts` - Refactored main client
 
 ### Utilities
+
 - `src/utils/toolWrapper.ts` - Standardized error handling and validation
 - `REFACTORING.md` - This documentation
 
 ## Files Modified
 
 ### Dependencies
+
 - `package.json` - Added `@jest/globals` dependency
 
 ### Code Cleanup
+
 - `src/client/auth.ts` - Removed unused `open` import
 
 ## Backward Compatibility
 
 The refactoring maintains 100% backward compatibility:
+
 - All public APIs remain unchanged
 - Existing tool implementations continue to work
 - Configuration and usage patterns unchanged
@@ -92,17 +109,20 @@ The refactoring maintains 100% backward compatibility:
 ## Performance Improvements
 
 ### Request Management
+
 - Intelligent rate limiting with exponential backoff
 - Connection pooling preparation
 - Optimized retry logic
 - Better timeout handling
 
 ### Error Handling
+
 - Pre-compiled error patterns
 - Reduced object allocation
 - Faster error categorization
 
 ### Memory Usage
+
 - Reduced object creation in hot paths
 - Better garbage collection patterns
 - Smaller memory footprint per request
@@ -110,12 +130,14 @@ The refactoring maintains 100% backward compatibility:
 ## Code Quality Metrics
 
 ### Before Refactoring
+
 - Largest file: 1043 lines (api.ts)
 - Try-catch blocks: 49 identical patterns
 - Cyclomatic complexity: High in client classes
 - Code duplication: ~30% in error handling
 
 ### After Refactoring  
+
 - Largest file: ~400 lines (reduced by 60%)
 - Try-catch blocks: 3 standardized patterns
 - Cyclomatic complexity: Significantly reduced
@@ -124,12 +146,14 @@ The refactoring maintains 100% backward compatibility:
 ## Testing Impact
 
 ### Test Coverage
+
 - All existing tests continue to pass
 - New modular structure enables better unit testing
 - Manager classes can be tested independently
 - Mock and stub creation simplified
 
 ### Test Performance
+
 - Faster test execution due to modular loading
 - Better test isolation
 - More focused test scenarios possible
@@ -137,6 +161,7 @@ The refactoring maintains 100% backward compatibility:
 ## Migration Guide
 
 ### For Developers
+
 The refactoring is transparent to end users but improves the development experience:
 
 ```typescript
@@ -149,6 +174,7 @@ import { AuthenticationManager, RequestManager } from './client/managers/index.j
 ```
 
 ### For Tool Development
+
 New tools can leverage standardized patterns:
 
 ```typescript
@@ -167,16 +193,19 @@ const handleGetPost = withErrorHandling(
 ## Future Improvements
 
 ### Short Term
+
 1. **Media Manager**: Extract file upload logic to specialized manager
 2. **Cache Manager**: Implement intelligent response caching
 3. **Connection Pool**: Add HTTP connection pooling
 
 ### Medium Term
+
 1. **Plugin Architecture**: Enable third-party manager plugins
 2. **Metrics Collection**: Add performance monitoring
 3. **Auto-scaling**: Dynamic rate limiting based on server response
 
 ### Long Term
+
 1. **GraphQL Support**: Alternative to REST API
 2. **Offline Mode**: Local caching and sync capabilities
 3. **Multi-tenant**: Enhanced multi-site optimizations
@@ -186,6 +215,7 @@ const handleGetPost = withErrorHandling(
 This refactoring addresses the major technical debt items while maintaining full backward compatibility. The codebase is now more maintainable, testable, and performant, setting a solid foundation for future enhancements.
 
 **Key Achievements**:
+
 - ✅ Reduced largest file size by 60%
 - ✅ Eliminated 85% of code duplication  
 - ✅ Improved architectural separation of concerns
@@ -193,4 +223,4 @@ This refactoring addresses the major technical debt items while maintaining full
 - ✅ Maintained 100% test coverage
 - ✅ Zero breaking changes
 
-The refactored codebase is ready for the next phase of development with significantly reduced technical debt.
+The refactored codebase is ready for the next phase of development with significantly reduced technical debt.

package/docs/releases/COMMUNITY_ANNOUNCEMENT_v1.1.2.md

@@ -1,4 +1,4 @@
-# 🎉 MCP WordPress v1.1.2 Released - Major Technical Achievement!
+# 🎉 MCP WordPress v1.1.2 Released - Major Technical Achievement
 
 ## For WordPress Forums / Reddit
 
@@ -9,21 +9,31 @@ Hey WordPress community! 👋
 I'm excited to share that we've just released **MCP WordPress v1.1.2**, featuring a major technical debt refactoring that achieved a **94% reduction in our core API module** (from 1,043 lines to just 59 lines)!
 
 ### What is MCP WordPress?
+
 It's a Model Context Protocol server that provides 54 tools for managing WordPress sites through the REST API. Perfect for automation, AI assistants, and developers who want programmatic WordPress control.
 
 ### What's New in v1.1.2?
+
 - 🏗️ **Modular Architecture**: Complete refactoring using manager pattern
 - ✅ **95%+ Test Coverage**: Everything is tested and verified
 - ⚡ **Performance Improvements**: Better memory management and rate limiting
 - 🔄 **100% Backward Compatible**: No breaking changes!
 
 ### Get Started
+
 ```bash
 npx mcp-wordpress
 ```
 
-**GitHub**: https://github.com/AiondaDotCom/mcp-wordpress
-**NPM**: https://www.npmjs.com/package/mcp-wordpress
+📖 **Comprehensive Setup Guides**:
+
+- [NPX Setup](../user-guides/NPX_SETUP.md) - Zero installation (recommended)
+- [NPM Setup](../user-guides/NPM_SETUP.md) - Local development
+- [Docker Setup](../user-guides/DOCKER_SETUP.md) - Containerized deployment
+- [DTX Setup](../user-guides/DTX_SETUP.md) - Desktop Extension
+
+**GitHub**: <https://github.com/docdyhr/mcp-wordpress>
+**NPM**: <https://www.npmjs.com/package/mcp-wordpress>
 
 Would love your feedback and contributions! 🚀
 
@@ -42,7 +52,7 @@ Major achievement: 94% code reduction through modular refactoring (1043→59 lin
 
 Try it: npx mcp-wordpress
 
-#WordPress #TypeScript #OpenSource
+# WordPress #TypeScript #OpenSource
 
 ---
 
@@ -62,9 +72,9 @@ This release demonstrates how technical debt can be addressed systematically wit
 
 MCP WordPress provides 54 tools for managing WordPress sites programmatically, supporting multi-site configurations and multiple authentication methods.
 
-Try it today: https://www.npmjs.com/package/mcp-wordpress
+Try it today: <https://www.npmjs.com/package/mcp-wordpress>
 
-#SoftwareEngineering #OpenSource #WordPress #TypeScript #TechnicalDebt
+# SoftwareEngineering #OpenSource #WordPress #TypeScript #TechnicalDebt
 
 ---
 
@@ -117,10 +127,11 @@ Just released a major update to MCP WordPress with significant architectural imp
 Perfect for using with Claude Desktop to manage your WordPress sites through natural language!
 
 Installation:
+
 ```bash
 npx mcp-wordpress
 ```
 
 Check out the modular architecture that makes it easy to extend and maintain. Would love feedback from the Claude community on how you're using it!
 
-GitHub: https://github.com/AiondaDotCom/mcp-wordpress
+GitHub: <https://github.com/docdyhr/mcp-wordpress>

package/docs/releases/RELEASE_NOTES_v1.1.2.md

@@ -9,11 +9,13 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ## ⭐ Headline Features
 
 ### 🏗️ **Modular Architecture Revolution**
+
 - **94% Code Reduction**: Transformed monolithic `api.ts` from 1043 lines to 59 lines
 - **Manager Pattern**: Introduced composition-based architecture with specialized managers
 - **Zero Breaking Changes**: 100% API compatibility maintained during refactoring
 
 ### 🎯 **Technical Excellence**
+
 - **95%+ Test Coverage**: All critical functionality verified and working
 - **Standardized Error Handling**: Reduced repetitive code patterns by 85%
 - **Performance Optimizations**: Better memory management and intelligent rate limiting
@@ -25,23 +27,27 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ### **New Modular Architecture**
 
 #### Manager Components
+
 - **BaseManager**: Common functionality and error handling patterns
 - **AuthenticationManager**: All authentication methods and token management
 - **RequestManager**: HTTP operations, rate limiting, and retry logic with exponential backoff
 - **WordPressClient**: Refactored main orchestrator using composition pattern
 
 #### Utility Enhancements
+
 - **toolWrapper.ts**: Standardized error handling utilities
 - **Consistent Validation**: Unified parameter validation across all tools
 - **Smart Retry Logic**: Intelligent request retry with exponential backoff
 
 ### **Performance Enhancements**
+
 - **Memory Optimization**: Reduced object allocation in hot code paths
 - **Rate Limiting**: Intelligent request throttling with backoff
 - **Error Processing**: Pre-compiled error patterns for faster categorization
 - **Garbage Collection**: Improved memory allocation patterns
 
 ### **Developer Experience**
+
 - **Modular Testing**: Better unit test isolation and mock capabilities
 - **Clear Separation**: Well-defined architectural boundaries
 - **Future-Proof**: Foundation set for additional specialized managers
@@ -51,12 +57,14 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ## 📊 Test Results Achievement
 
 ### **100% Core Functionality**
+
 - ✅ **TypeScript Build Tests**: 41/41 passing
 - ✅ **Tool Functionality Tests**: 14/14 tools operational  
 - ✅ **Authentication Tests**: 100% success rate
 - ✅ **Multi-site Configuration**: All sites working correctly
 
 ### **WordPress Integration**
+
 - ✅ **Posts Management**: Create, read, update, delete operations
 - ✅ **Media Handling**: File uploads and media library management
 - ✅ **User Operations**: Account management and authentication
@@ -68,12 +76,14 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ## 🔄 Migration & Compatibility
 
 ### **For Existing Users**
+
 - **No Action Required**: All existing configurations continue to work
 - **Same API**: All tool names and parameters unchanged
 - **Same Configuration**: Environment variables and config files work as before
 - **Same Commands**: All CLI commands and scripts function identically
 
 ### **For Developers**
+
 - **New Internal Structure**: Modular managers available for advanced usage
 - **Better Testing**: Improved test isolation and mock capabilities
 - **Cleaner Codebase**: Easier to understand and contribute to
@@ -83,18 +93,21 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ## 📋 Files Changed
 
 ### **Core Architecture**
+
 - `src/client/managers/BaseManager.ts` - New base class with common functionality
 - `src/client/managers/AuthenticationManager.ts` - Centralized auth handling
 - `src/client/managers/RequestManager.ts` - HTTP request management
 - `src/client/api.ts` - Refactored to re-export modular components (1043→59 lines)
 
 ### **Utilities & Documentation**
+
 - `src/utils/toolWrapper.ts` - Standardized error handling utilities
 - `REFACTORING.md` - Comprehensive technical debt analysis and resolution
 - `CHANGELOG.md` - Updated with detailed v1.1.2 changes
 - `TODO.md` - Updated roadmap with strategic priorities
 
 ### **Dependencies & Cleanup**
+
 - `package.json` - Version bump and dependency cleanup
 - Removed unused imports across multiple files
 - Added missing `@jest/globals` dependency
@@ -104,12 +117,14 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ## 🚀 What's Next
 
 ### **Immediate Priorities**
+
 1. **NPM Publication**: Make v1.1.2 available to all users
 2. **Community Engagement**: Share this architectural achievement
 3. **Documentation Enhancement**: GitHub Pages and improved guides
 4. **CI/CD Pipeline**: Automated testing to maintain quality standards
 
 ### **Short-term Goals**
+
 - Performance monitoring and analytics
 - Enhanced user experience features
 - Advanced multi-site management capabilities
@@ -120,12 +135,14 @@ We're excited to announce **v1.1.2**, a major milestone featuring comprehensive
 ## 🎯 Success Metrics
 
 ### **Code Quality**
+
 - **Lines of Code**: 94% reduction in main client file
 - **Duplication**: Reduced from 30% to 5%
 - **Complexity**: Significantly decreased through modular design
 - **Maintainability**: Dramatically improved with clear separation of concerns
 
 ### **Reliability**
+
 - **Test Coverage**: 95%+ with all core functionality verified
 - **Backward Compatibility**: 100% preserved
 - **Error Handling**: Standardized and consistent across all components
@@ -144,13 +161,22 @@ This refactoring represents months of careful planning and implementation, ensur
 ## 📦 Installation & Upgrade
 
 ### **New Installations**
+
 ```bash
-npm install -g @aiondadotcom/mcp-wordpress@1.1.2
+npm install -g mcp-wordpress@1.1.2
 ```
 
+📖 **Comprehensive Setup Guides**:
+
+- [NPX Setup](../user-guides/NPX_SETUP.md) - Zero installation (recommended)
+- [NPM Setup](../user-guides/NPM_SETUP.md) - Local development
+- [Docker Setup](../user-guides/DOCKER_SETUP.md) - Containerized deployment
+- [DTX Setup](../user-guides/DTX_SETUP.md) - Desktop Extension
+
 ### **Existing Users**
+
 ```bash
-npm update -g @aiondadotcom/mcp-wordpress
+npm update -g mcp-wordpress
 ```
 
 **No configuration changes required** - your existing setup will continue working seamlessly.
@@ -159,8 +185,8 @@ npm update -g @aiondadotcom/mcp-wordpress
 
 ## 🔗 Resources
 
-- **GitHub Repository**: [https://github.com/AiondaDotCom/mcp-wordpress](https://github.com/AiondaDotCom/mcp-wordpress)
-- **NPM Package**: [@aiondadotcom/mcp-wordpress](https://www.npmjs.com/package/@aiondadotcom/mcp-wordpress)
+- **GitHub Repository**: [https://github.com/docdyhr/mcp-wordpress](https://github.com/docdyhr/mcp-wordpress)
+- **NPM Package**: [mcp-wordpress](https://www.npmjs.com/package/mcp-wordpress)
 - **Documentation**: See CLAUDE.md for comprehensive architecture overview
 - **Technical Details**: See REFACTORING.md for in-depth refactoring analysis
 
@@ -170,4 +196,4 @@ npm update -g @aiondadotcom/mcp-wordpress
 
 *Release Date: June 29, 2025*
 *Version: 1.1.2*
-*Codename: "Modular Foundation"*
+*Codename: "Modular Foundation"*

package/docs/user-guides/DOCKER_NPM_DTX_SETUP.md

@@ -0,0 +1,217 @@
+# Docker, NPM, and DTX Setup Guide
+
+This guide provides step-by-step instructions for setting up the MCP WordPress server using Docker, NPM, and DTX, including Claude Desktop configuration.
+
+---
+
+## 🚀 Docker Setup
+
+### 1. Build the Docker Image
+
+Use the provided `Dockerfile` to build the MCP WordPress container:
+
+```bash
+git clone https://github.com/docdyhr/mcp-wordpress.git
+cd mcp-wordpress
+docker build -t mcp-wordpress .
+```
+
+### 2. Run the Docker Container
+
+Start the container with the necessary environment variables:
+
+```bash
+# For Claude Desktop MCP integration (recommended)
+docker run --rm -i \
+  -e WORDPRESS_SITE_URL=https://example.com \
+  -e WORDPRESS_USERNAME=your_username \
+  -e WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  mcp-wordpress
+
+# For debugging/testing (background mode)
+docker run -d --name mcp-wordpress-debug \
+  -e WORDPRESS_SITE_URL=https://example.com \
+  -e WORDPRESS_USERNAME=your_username \
+  -e WORDPRESS_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" \
+  mcp-wordpress
+```
+
+### 3. Multi-Site Configuration
+
+For multi-site setups, mount a configuration file:
+
+1. Create `mcp-wordpress.config.json`:
+
+```json
+{
+  "sites": [
+    {
+      "id": "site1",
+      "name": "Main Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://site1.com",
+        "WORDPRESS_USERNAME": "admin",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    },
+    {
+      "id": "site2",
+      "name": "Blog Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://blog.site2.com",
+        "WORDPRESS_USERNAME": "editor",
+        "WORDPRESS_APP_PASSWORD": "yyyy yyyy yyyy yyyy yyyy yyyy"
+      }
+    }
+  ]
+}
+```
+
+2. Run the container with the configuration file:
+
+```bash
+# For Claude Desktop MCP integration (recommended)
+docker run --rm -i \
+  -v $(pwd)/mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro \
+  mcp-wordpress
+
+# For debugging/testing (background mode)
+docker run -d --name mcp-wordpress-multisite \
+  -v $(pwd)/mcp-wordpress.config.json:/app/mcp-wordpress.config.json:ro \
+  mcp-wordpress
+```
+
+---
+
+## 📦 NPM Setup
+
+### 1. Install Dependencies
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/docdyhr/mcp-wordpress.git
+cd mcp-wordpress
+npm install
+```
+
+### 2. Run the Setup Wizard
+
+Run the interactive setup wizard:
+
+```bash
+npm run setup
+```
+
+### 3. Start the Server
+
+Start the MCP WordPress server:
+
+```bash
+npm start
+```
+
+### 4. Test the Tools
+
+Run tests to verify functionality:
+
+```bash
+npm run test:tools
+```
+
+---
+
+## 🖼️ DTX Setup
+
+### 1. Build the DTX Package
+
+Use the provided script to build the DTX package:
+
+```bash
+npm run build
+```
+
+### 2. Deploy the DTX Package
+
+Deploy the DTX package to the appropriate directory:
+
+```bash
+cp -r dxt/ /path/to/dtx/directory
+```
+
+### 3. Verify DTX Integration
+
+Ensure the DTX package is correctly integrated by checking the `manifest.json` file:
+
+```json
+{
+  "name": "MCP WordPress",
+  "version": "1.0.0",
+  "description": "DTX package for MCP WordPress",
+  "main": "index.js"
+}
+```
+
+---
+
+## 🤖 Claude Desktop Configuration
+
+### 1. Update Configuration File
+
+Add the MCP WordPress server to your Claude Desktop configuration file:
+
+```json
+{
+  "mcpServers": {
+    "mcp-wordpress": {
+      "command": "node",
+      "args": ["/path/to/your/mcp-wordpress/dist/index.js"],
+      "env": {
+        "WORDPRESS_SITE_URL": "https://example.com",
+        "WORDPRESS_USERNAME": "your_username",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx",
+        "WORDPRESS_AUTH_METHOD": "app-password"
+      }
+    }
+  }
+}
+```
+
+### 2. Restart Claude Desktop
+
+Close and reopen Claude Desktop to load the new configuration.
+
+### 3. Test Integration
+
+Use natural language commands in Claude Desktop to interact with your WordPress site:
+
+- "List my WordPress posts"
+- "Show me my site statistics"
+- "What categories do I have?"
+
+---
+
+## 🛠️ Maintenance Commands
+
+### Docker
+
+```bash
+docker ps                # List running containers
+docker logs mcp-wordpress # View container logs
+docker stop mcp-wordpress # Stop the container
+docker rm mcp-wordpress   # Remove the container
+```
+
+### NPM
+
+```bash
+npm run status          # Check WordPress connection
+npm run health          # Full system health check
+npm run verify-claude   # Verify Claude Desktop integration
+```
+
+### DTX
+
+```bash
+npm run build           # Rebuild the DTX package
+```