mcp-wordpress 1.2.2 → 1.3.0

package/docs/contract-testing.md

@@ -11,6 +11,7 @@ npm run test:contracts:live
 ```
 
 This command will:
+
 1. 🐳 Start isolated WordPress + MySQL containers (port 8081)
 2. ⚙️ Auto-configure WordPress with test data
 3. 🧪 Run contract tests against the live instance
@@ -21,17 +22,20 @@ This command will:
 ## 📋 What the Automated Setup Includes
 
 ### WordPress Configuration
+
 - **URL**: `http://localhost:8081`
 - **Admin User**: `testuser` / `test-password-123`
 - **App Password**: Auto-generated for API access
 - **Test Content**: Pre-created posts and media for testing
 
 ### Docker Services
+
 - **WordPress**: Latest WordPress with auto-setup
 - **MySQL**: 8.0 with optimized configuration
 - **WP-CLI**: For automated WordPress configuration
 
 ### Network Isolation
+
 - Uses separate Docker network: `wordpress-test-network`
 - Port 8081 (different from main development environment)
 - Isolated volumes: `wordpress_test_data`, `db_test_data`
@@ -41,21 +45,25 @@ This command will:
 If you prefer manual setup or need custom configuration:
 
 ### 1. Start Services
+
 ```bash
 docker-compose -f docker-compose.test.yml up -d
 ```
 
 ### 2. Check Status
+
 ```bash
 docker-compose -f docker-compose.test.yml ps
 docker-compose -f docker-compose.test.yml logs -f wordpress-test
 ```
 
 ### 3. Access WordPress
-- WordPress: http://localhost:8081
-- Admin Panel: http://localhost:8081/wp-admin
+
+- WordPress: <http://localhost:8081>
+- Admin Panel: <http://localhost:8081/wp-admin>
 
 ### 4. Run Tests
+
 ```bash
 # Set environment variables
 export WORDPRESS_TEST_URL="http://localhost:8081"
@@ -68,6 +76,7 @@ npm run test:contracts
 ```
 
 ### 5. Cleanup
+
 ```bash
 docker-compose -f docker-compose.test.yml down -v
 ```
@@ -75,18 +84,22 @@ docker-compose -f docker-compose.test.yml down -v
 ## 🧪 Test Modes
 
 ### Mock Testing (Default)
+
 ```bash
 npm run test:contracts
 ```
+
 - Uses Pact mock provider
 - No external dependencies
 - Fast execution
 - Good for CI/CD
 
 ### Live Testing
+
 ```bash
 npm run test:contracts:live
 ```
+
 - Tests against real WordPress
 - Validates actual API behavior
 - Comprehensive integration testing
@@ -97,21 +110,25 @@ npm run test:contracts:live
 The contract tests verify:
 
 ### ✅ Posts API
+
 - Create posts with proper structure
 - Retrieve posts with pagination
 - Response format validation
 
 ### ✅ Media API  
+
 - File upload handling
 - Multipart form data
 - Media library integration
 
 ### ✅ Users API
+
 - User information retrieval
 - Authentication validation
 - Permission handling
 
 ### ✅ Authentication
+
 - App password authentication
 - Authorization headers
 - Error handling
@@ -119,6 +136,7 @@ The contract tests verify:
 ## 🛠️ Troubleshooting
 
 ### Port Already in Use
+
 ```bash
 # Check what's using port 8081
 lsof -i :8081
@@ -128,6 +146,7 @@ kill -9 <PID>
 ```
 
 ### Docker Issues
+
 ```bash
 # Clean up Docker resources
 docker system prune -f
@@ -139,6 +158,7 @@ sudo service docker restart  # Linux
 ```
 
 ### WordPress Not Ready
+
 ```bash
 # Check WordPress logs
 docker-compose -f docker-compose.test.yml logs wordpress-test
@@ -151,6 +171,7 @@ curl http://localhost:8081/wp-json/wp/v2/
 ```
 
 ### Test Failures
+
 ```bash
 # Run with debug output
 DEBUG=true npm run test:contracts:live
@@ -180,4 +201,4 @@ To use in CI/CD pipelines:
   timeout-minutes: 10
 ```
 
-The automated setup is designed to work in CI environments with proper Docker support.
+The automated setup is designed to work in CI environments with proper Docker support.

package/docs/developer/GITHUB_ACTIONS_SETUP.md

@@ -12,6 +12,7 @@ The MCP WordPress project includes comprehensive GitHub Actions workflows for au
 **Purpose**: Automatically publish the package to NPM
 
 **Features**:
+
 - ✅ Checkout code with latest actions
 - ✅ Setup Node.js 18 with NPM registry
 - ✅ Install dependencies with `npm ci`
@@ -23,6 +24,7 @@ The MCP WordPress project includes comprehensive GitHub Actions workflows for au
 **Required Secret**: `NPM_TOKEN`
 
 **Usage**:
+
 ```bash
 # Create a GitHub release to trigger publishing
 gh release create v1.1.3 --title "Release v1.1.3" --notes "Release notes here"
@@ -30,12 +32,14 @@ gh release create v1.1.3 --title "Release v1.1.3" --notes "Release notes here"
 
 ### 2. CI Workflow (`.github/workflows/ci.yml`)
 
-**Triggers**: 
+**Triggers**:
+
 - Push to `main` or `develop` branches
 - Pull requests to `main`
 - Scheduled nightly runs
 
 **Features**:
+
 - 🧪 **Test Matrix**: Multiple Node.js versions (18, 20, 22)
 - 🔍 **Quality Checks**: Linting, type checking, coverage
 - 📦 **Build Verification**: Package building and installation
@@ -79,12 +83,14 @@ Check that your workflows reference the correct package name and repository:
 ### 3. Test the Workflows
 
 1. **Test CI Workflow**:
+
    ```bash
    # Push to main branch triggers CI
    git push origin main
    ```
 
 2. **Test NPM Publish**:
+
    ```bash
    # Create a release to trigger publishing
    git tag v1.1.3
@@ -205,4 +211,4 @@ This automatically triggers the NPM publish workflow and makes the new version a
 - [GitHub Actions Documentation](https://docs.github.com/en/actions)
 - [NPM Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
 - [Semantic Versioning](https://semver.org/)
-- [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github)
+- [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github)

package/docs/developer/MAINTENANCE.md

@@ -9,6 +9,7 @@ This document outlines automated and manual processes to keep the project secure
 ### NPM Package Configuration
 
 #### `.npmignore` File Maintenance
+
 The `.npmignore` file is automatically checked before each publication:
 
 ```bash
@@ -20,6 +21,7 @@ npm run check:ignore
 ```
 
 **What it checks:**
+
 - ✅ **Security files** are excluded (`.env`, `.npmrc`, `*.pem`, `*.key`, credentials)
 - ✅ **Test files** are excluded (`tests/`, `*.test.js`, `coverage/`)
 - ✅ **Development files** are excluded (`src/`, config files, IDE settings)
@@ -28,9 +30,11 @@ npm run check:ignore
 - ✅ **Documentation** is selectively included (README, LICENSE, CHANGELOG only)
 
 #### Files Excluded from NPM Package
+
 The following are **never** published to NPM:
 
 **Security & Secrets:**
+
 - `.env*` files
 - `.npmrc` (contains auth tokens)
 - `*.pem`, `*.key`, `*.cert` (certificates/keys)
@@ -38,22 +42,26 @@ The following are **never** published to NPM:
 - `*.token`, `*.credentials` files
 
 **Development Files:**
+
 - `src/` (source TypeScript - only `dist/` is published)
 - `tests/`, `coverage/`, test configuration files
 - `tsconfig.json`, `eslint.config.js`
 - `.vscode/`, `.idea/` (IDE settings)
 
 **CI/CD & Git:**
+
 - `.git/`, `.github/`
 - `.gitignore`, `.gitattributes`
 - CI configuration files (`.travis.yml`, `.circleci/`, etc.)
 
 **Logs & Temporary:**
+
 - `logs/`, `*.log`, `debug/`
 - `tmp/`, `temp/`, `*.tmp`
 - `test-results/`, `test-reports/`
 
 **Documentation (Selective):**
+
 - ❌ Development docs: `TODO.md`, `REFACTORING.md`, `MIGRATION_GUIDE.md`
 - ❌ Release docs: `COMMUNITY_ANNOUNCEMENT_*.md`, `RELEASE_NOTES_*.md`
 - ❌ Setup docs: `NPM_AUTH_SETUP.md`, `CLAUDE_DESKTOP_SETUP.md`
@@ -62,6 +70,7 @@ The following are **never** published to NPM:
 ### Scripts for Maintenance
 
 #### Ignore Files Sync (`scripts/sync-ignore-files.js`)
+
 Ensures `.gitignore` and `.npmignore` stay synchronized and secure:
 
 ```bash
@@ -73,12 +82,14 @@ npm run prepublishOnly
 ```
 
 **Features:**
+
 - Verifies security patterns are in place
 - Checks for missing patterns in both files
 - Validates that sensitive files are properly excluded
 - Reports summary statistics
 
 #### Pre-commit Hooks
+
 Automated checks before each commit:
 
 ```bash
@@ -90,6 +101,7 @@ npx lint-staged
 ```
 
 **What runs:**
+
 - ESLint fixes on TypeScript/JavaScript
 - Prettier formatting
 - Markdown linting
@@ -114,6 +126,7 @@ The following scripts help maintain file integrity:
 ### Weekly Tasks
 
 1. **Dependency Updates**
+
    ```bash
    npm audit
    npm audit fix
@@ -121,12 +134,14 @@ The following scripts help maintain file integrity:
    ```
 
 2. **Security Review**
+
    ```bash
    npm run check:ignore
    git status # Ensure no sensitive files are staged
    ```
 
 3. **Test Coverage Review**
+
    ```bash
    npm run test:coverage
    npm run health
@@ -145,6 +160,7 @@ The following scripts help maintain file integrity:
    - Check all markdown files for accuracy
 
 3. **Dependency Major Updates**
+
    ```bash
    npm update
    npm run test
@@ -154,6 +170,7 @@ The following scripts help maintain file integrity:
 ### Before Each Release
 
 1. **Pre-publication Checklist**
+
    ```bash
    # 1. Build and test everything
    npm run build
@@ -182,6 +199,7 @@ The following scripts help maintain file integrity:
 ### File Exclusion Patterns
 
 **Always exclude from NPM:**
+
 ```
 .env*
 .npmrc
@@ -194,6 +212,7 @@ secrets/
 ```
 
 **Always exclude from Git:**
+
 ```
 .env
 .npmrc
@@ -219,10 +238,11 @@ node_modules/
 **If credentials are accidentally published:**
 
 1. **Immediate Response:**
+
    ```bash
-   npm unpublish @aiondadotcom/mcp-wordpress@version
+   npm unpublish mcp-wordpress@version
    # Or deprecate if unpublish is not allowed
-   npm deprecate @aiondadotcom/mcp-wordpress@version "Security issue - use newer version"
+   npm deprecate mcp-wordpress@version "Security issue - use newer version"
    ```
 
 2. **Credential Rotation:**
@@ -232,6 +252,7 @@ node_modules/
    - Regenerate any exposed credentials
 
 3. **Republish:**
+
    ```bash
    npm version patch
    npm publish
@@ -242,6 +263,7 @@ node_modules/
 ### Automated Checks
 
 The following run automatically:
+
 - `prepublishOnly` before each npm publish
 - `pre-commit` before each git commit
 - CI/CD tests on every push/PR
@@ -249,6 +271,7 @@ The following run automatically:
 ### Manual Verification
 
 Regular checks to perform:
+
 ```bash
 # Check what would be published
 npm publish --dry-run
@@ -266,6 +289,7 @@ git log --oneline -10
 ## Tools and Dependencies
 
 ### Core Tools
+
 - **ESLint**: Code quality and consistency
 - **Prettier**: Code formatting
 - **Husky**: Git hooks management
@@ -273,6 +297,7 @@ git log --oneline -10
 - **Jest**: Testing framework
 
 ### Security Tools
+
 - **npm audit**: Vulnerability scanning
 - **Custom scripts**: File exclusion verification
 - **Git hooks**: Pre-commit security checks
@@ -301,7 +326,8 @@ git status --ignored
 ```
 
 This maintenance approach ensures:
+
 - 🔒 **Security**: No sensitive files ever published
 - 📦 **Optimization**: Minimal package size
 - 🔄 **Automation**: Critical checks run automatically
-- 📋 **Consistency**: Standardized maintenance procedures
+- 📋 **Consistency**: Standardized maintenance procedures

package/docs/developer/MIGRATION_GUIDE.md

@@ -7,6 +7,7 @@ This guide helps you migrate from the previous single-site configuration to the
 ### 1. Configuration Method Changed
 
 **Old Method (Environment Variables):**
+
 ```bash
 WORDPRESS_SITE_URL=https://example.com
 WORDPRESS_USERNAME=admin
@@ -15,6 +16,7 @@ WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
 
 **New Method (Configuration File):**
 Create a `mcp-wordpress.config.json` file:
+
 ```json
 {
   "sites": [
@@ -36,11 +38,13 @@ Create a `mcp-wordpress.config.json` file:
 All tools now require a `site` parameter when multiple sites are configured.
 
 **Old Usage:**
+
 ```
 wp_list_posts
 ```
 
 **New Usage:**
+
 ```
 wp_list_posts --site="main"
 ```
@@ -50,6 +54,7 @@ Note: If only one site is configured, the `site` parameter is optional and that
 ### 3. Tool Architecture Refactored
 
 Tools have been refactored from function-based to class-based architecture:
+
 - All tools are now organized into classes (e.g., `PostTools`, `PageTools`)
 - Tool registration is centralized through `src/tools/index.ts`
 - Each tool category has its own class file in `src/tools/`
@@ -59,6 +64,7 @@ Tools have been refactored from function-based to class-based architecture:
 ### Step 1: Backup Your Configuration
 
 Save your current environment variables:
+
 ```bash
 cp .env .env.backup
 ```
@@ -104,6 +110,7 @@ wp_create_post --title="Hello" --content="World"
 ### Step 4: Test Your Configuration
 
 Run the health check to verify your configuration:
+
 ```bash
 npm run health
 ```
@@ -111,6 +118,7 @@ npm run health
 ### Step 5: Remove Old Configuration (Optional)
 
 Once verified, you can remove the old `.env` file:
+
 ```bash
 rm .env
 ```
@@ -145,6 +153,7 @@ The main benefit of the new configuration is support for multiple WordPress site
 ```
 
 Then use tools with specific sites:
+
 ```bash
 wp_list_posts --site="site1"
 wp_create_post --site="site2" --title="New Blog Post"
@@ -157,16 +166,19 @@ The server maintains backward compatibility with environment variables. If no `m
 ## Troubleshooting
 
 ### Issue: "Site parameter is required"
+
 **Solution:** When multiple sites are configured, you must specify which site to use with the `--site` parameter.
 
 ### Issue: "Site 'xyz' not found"
+
 **Solution:** Check that the site ID in your command matches an ID in your configuration file.
 
 ### Issue: Tools not working after migration
+
 **Solution:** Run `npm run health` to diagnose configuration issues.
 
 ## Need Help?
 
 - Check the [CLAUDE.md](./CLAUDE.md) file for detailed documentation
 - Run `npm run health` for system diagnostics
-- Open an issue on GitHub if you encounter problems
+- Open an issue on GitHub if you encounter problems

package/docs/developer/NPM_AUTH_SETUP.md

@@ -5,11 +5,13 @@
 The project includes a pre-configured `.npmrc` file that uses environment variables:
 
 1. **Set your NPM token as environment variable:**
+
    ```bash
    export NPM_TOKEN="npm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    ```
 
 2. **Or add to your shell profile:**
+
    ```bash
    # Add to ~/.bashrc, ~/.zshrc, or ~/.profile
    echo 'export NPM_TOKEN="npm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"' >> ~/.zshrc
@@ -17,11 +19,13 @@ The project includes a pre-configured `.npmrc` file that uses environment variab
    ```
 
 3. **Verify authentication:**
+
    ```bash
    npm whoami
    ```
 
 4. **Publish:**
+
    ```bash
    npm publish
    ```
@@ -37,13 +41,15 @@ The project includes a pre-configured `.npmrc` file that uses environment variab
    - Copy the generated token
 
 2. **Store the token locally**:
-   
+
    Create or edit `~/.npmrc`:
+
    ```bash
    echo "//registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN" >> ~/.npmrc
    ```
 
    Or set it for this project only in `.npmrc` (in project root):
+
    ```bash
    # Copy the example file
    cp .npmrc.example .npmrc
@@ -53,6 +59,7 @@ The project includes a pre-configured `.npmrc` file that uses environment variab
    ```
 
 3. **Using environment variable** (more secure):
+
    ```bash
    # Add to ~/.bashrc or ~/.zshrc
    export NPM_TOKEN="npm_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
@@ -95,11 +102,13 @@ npm config set //registry.npmjs.org/:_authToken YOUR_NPM_TOKEN
 ## Publishing with Token
 
 Once authenticated, publish with:
+
 ```bash
 npm publish
 ```
 
 Or with explicit registry:
+
 ```bash
 npm publish --registry https://registry.npmjs.org/
 ```
@@ -107,6 +116,7 @@ npm publish --registry https://registry.npmjs.org/
 ## Verifying Authentication
 
 Check if you're logged in:
+
 ```bash
 npm whoami
 ```
@@ -137,6 +147,7 @@ Your `NPM_TOKEN` is already stored in GitHub secrets. For automated publishing v
 ## Revoking Tokens
 
 If a token is compromised:
+
 1. Go to npmjs.com → Account Settings → Access Tokens
 2. Find the token and click "Revoke"
-3. Generate a new token and update your configurations
+3. Generate a new token and update your configurations