MCP WordPress Server

# Development Setup Guide This guide walks you through setting up a complete development environment for the MCP WordPress Server. ## 🔧 Prerequisites ### Required Software - **Node.js 18+** - [Download from nodejs.org](https://nodejs.org/) - **npm 9+** - Comes with Node.js - **Git** - [Download from git-scm.com](https://git-scm.com/) - **TypeScript 5+** - Installed via npm - **Docker & Docker Compose** - [Download from docker.com](https://docker.com/) ### Optional Tools - **VS Code** - Recommended IDE with TypeScript support - **GitHub CLI** - For GitHub integration (`gh`) - **WordPress Site** - For testing (or use Docker test environment) ## 🚀 Quick Setup ### 1. Clone Repository ```bash git clone https://github.com/docdyhr/mcp-wordpress.git cd mcp-wordpress ``` ### 2. Install Dependencies ```bash # Install all dependencies npm ci # Install development tools globally (optional) npm install -g typescript @types/node jest ``` ### 3. Build Project ```bash # Initial build npm run build # Type checking npm run typecheck ``` ### 4. Run Tests ```bash # Run all tests npm test # Quick validation npm run test:fast ``` ## 📁 Project Structure ```text mcp-wordpress/ ├── src/ # TypeScript source code │ ├── index.ts # Main MCP server entry point │ ├── server.ts # Server compatibility layer │ ├── types/ # TypeScript type definitions │ │ ├── wordpress.ts # WordPress REST API types │ │ ├── mcp.ts # MCP protocol types │ │ ├── client.ts # Client interface types │ │ └── index.ts # Type exports │ ├── client/ # WordPress API client (modular) │ │ ├── WordPressClient.ts # Main client orchestrator │ │ ├── CachedWordPressClient.ts # Caching wrapper │ │ ├── api.ts # Legacy compatibility │ │ ├── auth.ts # Authentication utilities │ │ └── managers/ # Manager components │ │ ├── BaseManager.ts # Common functionality │ │ ├── AuthenticationManager.ts # Auth methods │ │ └── RequestManager.ts # HTTP operations │ ├── tools/ # MCP tool implementations │ │ ├── posts.ts # Post management tools │ │ ├── pages.ts # Page management tools │ │ ├── media.ts # Media management tools │ │ ├── users.ts # User management tools │ │ ├── comments.ts # Comment management tools │ │ ├── taxonomies.ts # Categories/Tags tools │ │ ├── site.ts # Site settings tools │ │ ├── auth.ts # Authentication tools │ │ ├── cache.ts # Cache management tools │ │ ├── performance.ts # Performance monitoring tools │ │ └── index.ts # Tool registry │ ├── cache/ # Intelligent caching system │ │ ├── CacheManager.ts # Core cache functionality │ │ ├── CacheInvalidation.ts # Cache invalidation logic │ │ └── types.ts # Cache type definitions │ ├── performance/ # Performance monitoring system │ │ ├── PerformanceMonitor.ts # Core monitoring │ │ ├── MetricsCollector.ts # Metrics collection │ │ └── PerformanceAnalytics.ts # Analytics engine │ ├── security/ # Security validation and utilities │ │ ├── InputValidator.ts # Input validation │ │ ├── SecurityConfig.ts # Security configuration │ │ └── SecurityUtils.ts # Security utilities │ ├── docs/ # Documentation generation system │ │ ├── DocumentationGenerator.ts # Doc extraction │ │ └── MarkdownFormatter.ts # Markdown formatting │ ├── server/ # Server infrastructure │ │ └── ToolRegistry.ts # Tool registration system │ └── utils/ # Shared utility functions │ └── debug.ts # Debug logging utilities ├── dist/ # Compiled JavaScript output ├── tests/ # Comprehensive test suite │ ├── auth-headers-fix.test.js # Authentication tests │ ├── config-loading.test.js # Configuration tests │ ├── tool-validation.test.js # Tool validation tests │ ├── typescript-build.test.js # Build tests │ ├── env-loading.test.js # Environment tests │ ├── unit/ # Unit tests │ ├── security/ # Security tests │ ├── performance/ # Performance tests │ ├── cache/ # Cache tests │ ├── property/ # Property-based tests │ └── config/ # Configuration tests ├── scripts/ # Build, test, and utility scripts ├── docs/ # Documentation └── .github/workflows/ # CI/CD automation ``` ## 🔧 Development Commands ### Build System ```bash # TypeScript compilation npm run build # Compile to dist/ npm run build:watch # Watch mode compilation npm run typecheck # Type checking without output # Development mode npm run dev # Development with debug output DEBUG=true npm run dev # Enhanced debug logging ``` ### Testing Commands ```bash # Test execution npm test # Run main test suite npm run test:watch # Watch mode testing npm run test:coverage # Generate coverage report (50% threshold) npm run test:fast # Quick test run # Specific test suites npm run test:typescript # TypeScript build tests npm run test:security # Security validation tests npm run test:performance # Performance regression tests npm run test:cache # Cache system tests npm run test:config # Configuration validation tests npm run test:property # Property-based tests # Integration tests npm run test:tools # Tool functionality tests npm run test:auth # Authentication tests npm run test:mcp # MCP protocol tests npm run test:multisite # Multi-site configuration tests # Contract testing npm run test:contracts # Contract tests (mock) npm run test:contracts:live # Live WordPress contract tests # Docker test environment npm run test:with-env # Tests with Docker WordPress ./scripts/start-test-env.sh # Start test environment ``` ### Code Quality ```bash # Linting and formatting npm run lint # ESLint check npm run lint:fix # Auto-fix ESLint errors npm run format # Prettier formatting npm run format:check # Check formatting without changes # Security scanning npm run security:check # Quick vulnerability scan npm run security:scan # Comprehensive security scanning npm run security:test # Security policy validation npm run security:full # Complete security testing suite ``` ### Documentation ```bash # Documentation generation npm run docs:generate # Generate API documentation npm run docs:validate # Validate documentation completeness npm run docs:serve # Start local documentation server npm run docs:watch # Watch mode for documentation ``` ### Utility Commands ```bash # Status and diagnostics npm run status # Check connection status npm run health # Comprehensive system health check npm run setup # Interactive setup wizard # Maintenance npm run clean # Clean build artifacts npm run verify-claude # Verify Claude integration ``` ## 🐳 Docker Development Environment ### Test Environment Setup ```bash # Start complete test environment ./scripts/start-test-env.sh # Run tests with Docker environment npm run test:with-env # Stop test environment docker-compose -f docker-compose.test.yml down ``` ### Development with Docker ```bash # Build Docker image docker build -t mcp-wordpress-dev . # Run development container docker run --rm -it \ -v $(pwd):/app \ -w /app \ mcp-wordpress-dev npm run dev # Docker Compose for development docker-compose up --profile dev ``` ## ⚙️ Configuration ### Environment Variables Create a `.env` file in the project root: ```env # WordPress connection (for testing) WORDPRESS_SITE_URL=https://your-test-site.com WORDPRESS_USERNAME=your-username WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx WORDPRESS_AUTH_METHOD=app-password # Development settings DEBUG=true NODE_ENV=development LOG_LEVEL=debug # Test configuration WORDPRESS_TEST_URL=http://localhost:8081 PACT_LIVE_TESTING=false ``` ### Multi-Site Development Create `mcp-wordpress.config.json` for multi-site testing: ```json { "sites": [ { "id": "test-site", "name": "Test WordPress Site", "config": { "WORDPRESS_SITE_URL": "http://localhost:8081", "WORDPRESS_USERNAME": "admin", "WORDPRESS_APP_PASSWORD": "test test test test test test" } }, { "id": "dev-site", "name": "Development Site", "config": { "WORDPRESS_SITE_URL": "https://your-dev-site.com", "WORDPRESS_USERNAME": "dev_user", "WORDPRESS_APP_PASSWORD": "your-dev-password" } } ] } ``` ## 🧪 Testing WordPress Setup ### Option 1: Use Docker Test Environment (Recommended) ```bash # Automated test WordPress setup ./scripts/start-test-env.sh ``` This creates: - WordPress instance on `http://localhost:8081` - Admin user: `admin` / `password` - Pre-configured application password - MySQL database - Isolated from your development environment ### Option 2: Manual WordPress Setup 1. Install WordPress locally or use existing site 2. Enable Application Passwords (WordPress 5.6+) 3. Create application password for testing 4. Configure `.env` file with credentials ### Option 3: Use WordPress.com or Hosted Site 1. Use existing WordPress site 2. Create application password 3. Configure credentials in `.env` 4. Ensure REST API is accessible ## 🔍 IDE Setup (VS Code Recommended) ### Required Extensions ```json { "recommendations": [ "ms-vscode.vscode-typescript-next", "esbenp.prettier-vscode", "dbaeumer.vscode-eslint", "bradlc.vscode-tailwindcss", "ms-vscode.vscode-json" ] } ``` ### Workspace Settings ```json { "typescript.preferences.includePackageJsonAutoImports": "on", "typescript.suggest.autoImports": true, "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "files.exclude": { "dist/": true, "node_modules/": true, "coverage/": true } } ``` ## 🚀 First Development Task ### 1. Verify Setup ```bash # Check all systems npm run health # Run quick tests npm run test:fast # Check connection to WordPress npm run status ``` ### 2. Make a Small Change ```bash # Edit a tool description in src/tools/posts.ts # Run tests to verify npm test # Check linting npm run lint # Build project npm run build ``` ### 3. Test Integration ```bash # Test with Claude Desktop (if configured) npm run verify-claude # Or test with development mode npm run dev ``` ## 🐛 Common Development Issues ### TypeScript Errors ```bash # Check TypeScript configuration npm run typecheck # Clear and rebuild rm -rf dist/ npm run build ``` ### Test Failures ```bash # Run specific test suite npm run test:auth # Debug with verbose output DEBUG=true npm test # Check test environment ./scripts/start-test-env.sh npm run test:with-env ``` ### WordPress Connection Issues ```bash # Test WordPress REST API directly curl https://your-site.com/wp-json/wp/v2/ # Check authentication npm run status # Re-run setup wizard npm run setup ``` ### Docker Issues ```bash # Clean Docker environment docker-compose -f docker-compose.test.yml down -v docker system prune # Rebuild test environment ./scripts/start-test-env.sh ``` ## 📚 Next Steps 1. **[Architecture Guide](ARCHITECTURE.md)** - Understand the system design 2. **[API Reference](API_REFERENCE.md)** - Technical API documentation 3. **[Testing Guide](TESTING.md)** - Comprehensive testing information 4. **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute --- **Need help?** Check the [troubleshooting guide](../TROUBLESHOOTING.md) or create an issue on GitHub.