mcp-wordpress 1.1.2 → 1.1.7

package/docs/developer/MAINTENANCE.md

@@ -0,0 +1,307 @@
+# Maintenance Guide - MCP WordPress
+
+## Overview
+
+This document outlines automated and manual processes to keep the project secure, up-to-date, and well-maintained.
+
+## Automated Maintenance
+
+### NPM Package Configuration
+
+#### `.npmignore` File Maintenance
+The `.npmignore` file is automatically checked before each publication:
+
+```bash
+# Runs automatically before npm publish
+npm run prepublishOnly
+
+# Manual check
+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)
+- ✅ **CI/CD files** are excluded (`.github/`, various CI configs)
+- ✅ **Logs and temporary files** are excluded
+- ✅ **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)
+- `credentials/`, `secrets/`, `auth/` directories
+- `*.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`
+- ✅ User docs: `README.md`, `LICENSE`, `CHANGELOG.md`
+
+### Scripts for Maintenance
+
+#### Ignore Files Sync (`scripts/sync-ignore-files.js`)
+Ensures `.gitignore` and `.npmignore` stay synchronized and secure:
+
+```bash
+# Check ignore files manually
+npm run check:ignore
+
+# Automatically runs before publish
+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
+# Runs automatically on git commit
+npm run pre-commit
+
+# Manual run
+npx lint-staged
+```
+
+**What runs:**
+- ESLint fixes on TypeScript/JavaScript
+- Prettier formatting
+- Markdown linting
+- Package.json sorting
+
+### Package.json Scripts Integration
+
+The following scripts help maintain file integrity:
+
+```json
+{
+  "scripts": {
+    "check:ignore": "node scripts/sync-ignore-files.js",
+    "prepublishOnly": "npm run build && npm run check:ignore",
+    "pre-commit": "lint-staged"
+  }
+}
+```
+
+## Manual Maintenance Tasks
+
+### Weekly Tasks
+
+1. **Dependency Updates**
+   ```bash
+   npm audit
+   npm audit fix
+   npm outdated
+   ```
+
+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
+   ```
+
+### Monthly Tasks
+
+1. **Comprehensive Security Review**
+   - Check `.gitignore` and `.npmignore` for new patterns
+   - Review npm audit results
+   - Verify no credentials in commit history
+
+2. **Documentation Updates**
+   - Update README.md with new features
+   - Review and update CLAUDE.md
+   - Check all markdown files for accuracy
+
+3. **Dependency Major Updates**
+   ```bash
+   npm update
+   npm run test
+   npm run build
+   ```
+
+### Before Each Release
+
+1. **Pre-publication Checklist**
+   ```bash
+   # 1. Build and test everything
+   npm run build
+   npm test
+   npm run test:tools
+   npm run health
+   
+   # 2. Check ignore files
+   npm run check:ignore
+   
+   # 3. Verify no sensitive data
+   npm publish --dry-run
+   
+   # 4. Check package contents
+   npx pkgfiles
+   ```
+
+2. **Security Verification**
+   - Verify `.npmrc` is not in the package
+   - Check that no `.env` files are included
+   - Ensure no credential files are packaged
+   - Review the file list from `npm publish --dry-run`
+
+## Security Best Practices
+
+### File Exclusion Patterns
+
+**Always exclude from NPM:**
+```
+.env*
+.npmrc
+*.pem
+*.key
+*.cert
+credentials/
+secrets/
+*.token
+```
+
+**Always exclude from Git:**
+```
+.env
+.npmrc
+mcp-wordpress.config.json
+*.log
+node_modules/
+```
+
+### Credential Management
+
+1. **Local Development:**
+   - Store tokens in `~/.npmrc` or environment variables
+   - Never commit `.npmrc` to version control
+   - Use separate tokens for development vs. CI/CD
+
+2. **CI/CD:**
+   - Use GitHub Secrets for `NPM_TOKEN`
+   - Use automation tokens (not personal tokens)
+   - Rotate tokens regularly
+
+### Emergency Procedures
+
+**If credentials are accidentally published:**
+
+1. **Immediate Response:**
+   ```bash
+   npm unpublish @aiondadotcom/mcp-wordpress@version
+   # Or deprecate if unpublish is not allowed
+   npm deprecate @aiondadotcom/mcp-wordpress@version "Security issue - use newer version"
+   ```
+
+2. **Credential Rotation:**
+   - Revoke compromised NPM tokens
+   - Rotate any exposed API keys
+   - Update GitHub secrets
+   - Regenerate any exposed credentials
+
+3. **Republish:**
+   ```bash
+   npm version patch
+   npm publish
+   ```
+
+## Monitoring and Alerts
+
+### Automated Checks
+
+The following run automatically:
+- `prepublishOnly` before each npm publish
+- `pre-commit` before each git commit
+- CI/CD tests on every push/PR
+
+### Manual Verification
+
+Regular checks to perform:
+```bash
+# Check what would be published
+npm publish --dry-run
+
+# Verify ignore files are current
+npm run check:ignore
+
+# Check for sensitive files in working directory
+git status --ignored
+
+# Review recent commits for sensitive data
+git log --oneline -10
+```
+
+## Tools and Dependencies
+
+### Core Tools
+- **ESLint**: Code quality and consistency
+- **Prettier**: Code formatting
+- **Husky**: Git hooks management
+- **lint-staged**: Run linters on staged files
+- **Jest**: Testing framework
+
+### Security Tools
+- **npm audit**: Vulnerability scanning
+- **Custom scripts**: File exclusion verification
+- **Git hooks**: Pre-commit security checks
+
+### Maintenance Commands Summary
+
+```bash
+# Daily development
+npm run dev
+npm test
+npm run lint
+
+# Before commit
+npm run pre-commit  # (runs automatically)
+
+# Before release
+npm run build
+npm run check:ignore
+npm publish --dry-run
+npm publish
+
+# Security checks
+npm audit
+npm run check:ignore
+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

package/docs/developer/MIGRATION_GUIDE.md

@@ -0,0 +1,172 @@
+# Migration Guide: Single-Site to Multi-Site Configuration
+
+This guide helps you migrate from the previous single-site configuration to the new multi-site configuration introduced in v2.0.0.
+
+## Breaking Changes
+
+### 1. Configuration Method Changed
+
+**Old Method (Environment Variables):**
+```bash
+WORDPRESS_SITE_URL=https://example.com
+WORDPRESS_USERNAME=admin
+WORDPRESS_APP_PASSWORD=xxxx xxxx xxxx xxxx xxxx xxxx
+```
+
+**New Method (Configuration File):**
+Create a `mcp-wordpress.config.json` file:
+```json
+{
+  "sites": [
+    {
+      "id": "main",
+      "name": "My WordPress Site",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://example.com",
+        "WORDPRESS_USERNAME": "admin",
+        "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx"
+      }
+    }
+  ]
+}
+```
+
+### 2. Tool Usage Changed
+
+All tools now require a `site` parameter when multiple sites are configured.
+
+**Old Usage:**
+```
+wp_list_posts
+```
+
+**New Usage:**
+```
+wp_list_posts --site="main"
+```
+
+Note: If only one site is configured, the `site` parameter is optional and that site will be used by default.
+
+### 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/`
+
+## Migration Steps
+
+### Step 1: Backup Your Configuration
+
+Save your current environment variables:
+```bash
+cp .env .env.backup
+```
+
+### Step 2: Create Configuration File
+
+Create `mcp-wordpress.config.json` in the project root:
+
+```json
+{
+  "sites": [
+    {
+      "id": "main",
+      "name": "Your Site Name",
+      "config": {
+        "WORDPRESS_SITE_URL": "YOUR_SITE_URL",
+        "WORDPRESS_USERNAME": "YOUR_USERNAME",
+        "WORDPRESS_APP_PASSWORD": "YOUR_APP_PASSWORD",
+        "WORDPRESS_AUTH_METHOD": "app-password"
+      }
+    }
+  ]
+}
+```
+
+Replace the values with your actual configuration from `.env`.
+
+### Step 3: Update Tool Usage
+
+If you have scripts or automation using the tools, update them to include the site parameter:
+
+```bash
+# Old
+wp_create_post --title="Hello" --content="World"
+
+# New (explicit site)
+wp_create_post --site="main" --title="Hello" --content="World"
+
+# New (implicit - only works with single site)
+wp_create_post --title="Hello" --content="World"
+```
+
+### Step 4: Test Your Configuration
+
+Run the health check to verify your configuration:
+```bash
+npm run health
+```
+
+### Step 5: Remove Old Configuration (Optional)
+
+Once verified, you can remove the old `.env` file:
+```bash
+rm .env
+```
+
+## Adding Multiple Sites
+
+The main benefit of the new configuration is support for multiple WordPress sites:
+
+```json
+{
+  "sites": [
+    {
+      "id": "site1",
+      "name": "Main Website",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://site1.com",
+        "WORDPRESS_USERNAME": "admin1",
+        "WORDPRESS_APP_PASSWORD": "password1"
+      }
+    },
+    {
+      "id": "site2", 
+      "name": "Blog",
+      "config": {
+        "WORDPRESS_SITE_URL": "https://blog.site2.com",
+        "WORDPRESS_USERNAME": "admin2",
+        "WORDPRESS_APP_PASSWORD": "password2"
+      }
+    }
+  ]
+}
+```
+
+Then use tools with specific sites:
+```bash
+wp_list_posts --site="site1"
+wp_create_post --site="site2" --title="New Blog Post"
+```
+
+## Backward Compatibility
+
+The server maintains backward compatibility with environment variables. If no `mcp-wordpress.config.json` file is found, it will fall back to using environment variables as before.
+
+## 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

package/docs/developer/NPM_AUTH_SETUP.md

@@ -0,0 +1,142 @@
+# NPM Authentication Setup
+
+## Quick Setup for This Project
+
+The project includes a pre-configured `.npmrc` file that uses environment variables:
+
+1. **Set your NPM token as environment variable:**
+   ```bash
+   export NPM_TOKEN="your_npm_token_here"
+   ```
+
+2. **Or add to your shell profile:**
+   ```bash
+   # Add to ~/.bashrc, ~/.zshrc, or ~/.profile
+   echo 'export NPM_TOKEN="your_npm_token_here"' >> ~/.zshrc
+   source ~/.zshrc
+   ```
+
+3. **Verify authentication:**
+   ```bash
+   npm whoami
+   ```
+
+4. **Publish:**
+   ```bash
+   npm publish
+   ```
+
+## Local NPM Authentication Methods
+
+### Method 1: Using NPM Token (Recommended for Automation)
+
+1. **Create an NPM automation token**:
+   - Log in to npmjs.com
+   - Go to Account Settings → Access Tokens
+   - Click "Generate New Token" → Choose "Automation" type
+   - 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
+   
+   # Edit .npmrc with your token (if not using environment variable)
+   echo "//registry.npmjs.org/:_authToken=YOUR_NPM_TOKEN" > .npmrc
+   ```
+
+3. **Using environment variable** (more secure):
+   ```bash
+   # Add to ~/.bashrc or ~/.zshrc
+   export NPM_TOKEN="your_npm_token_here"
+   
+   # Then in .npmrc:
+   //registry.npmjs.org/:_authToken=${NPM_TOKEN}
+   ```
+
+### Method 2: Interactive Login
+
+```bash
+npm login
+# Follow the prompts for username, password, email, and 2FA code
+```
+
+This creates an entry in `~/.npmrc` automatically.
+
+### Method 3: Using npm CLI with Token
+
+```bash
+npm config set //registry.npmjs.org/:_authToken YOUR_NPM_TOKEN
+```
+
+## Security Best Practices
+
+1. **Never commit `.npmrc` with tokens** to version control
+   - Add `.npmrc` to `.gitignore` if storing tokens there
+   - Use environment variables for tokens
+
+2. **Use different tokens for different purposes**:
+   - Personal development: Read-only or Publish token
+   - CI/CD: Automation token (like your NPM_TOKEN in GitHub secrets)
+   - Team projects: Shared organization tokens
+
+3. **Token permissions**:
+   - **Read-only**: Can only install packages
+   - **Publish**: Can publish new versions
+   - **Automation**: Best for CI/CD, can publish but has restrictions
+
+## Publishing with Token
+
+Once authenticated, publish with:
+```bash
+npm publish
+```
+
+Or with explicit registry:
+```bash
+npm publish --registry https://registry.npmjs.org/
+```
+
+## Verifying Authentication
+
+Check if you're logged in:
+```bash
+npm whoami
+```
+
+## GitHub Actions Setup (Already Done)
+
+Your `NPM_TOKEN` is already stored in GitHub secrets. For automated publishing via GitHub Actions, use:
+
+```yaml
+- name: Setup Node.js
+  uses: actions/setup-node@v3
+  with:
+    node-version: '18'
+    registry-url: 'https://registry.npmjs.org'
+
+- name: Publish to NPM
+  run: npm publish
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+## Troubleshooting
+
+1. **401 Unauthorized**: Token is invalid or expired
+2. **403 Forbidden**: Token lacks publish permissions
+3. **E402**: Package requires payment (for private packages)
+
+## 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