MCP WordPress Server

# DXT Package Analysis - Multi-Site Support Issue **Date**: 2025-10-07 **Status**: 🔴 **ISSUE IDENTIFIED** **Severity**: High - Multi-site functionality not available in DXT --- ## Executive Summary The MCP WordPress codebase **fully supports multi-site configuration**, but the **DXT package manifest only exposes single-site configuration** to Claude Desktop users. This means users installing the `.dxt` extension cannot configure multiple WordPress sites, limiting them to single-site usage only. --- ## Root Cause Analysis ### 1. Codebase Multi-Site Support ✅ The codebase correctly implements multi-site support: **File**: [src/config/ServerConfiguration.ts](src/config/ServerConfiguration.ts) ```typescript /** * Configuration loader for MCP WordPress Server * Handles both single-site (environment variables) and multi-site (JSON config) modes */ export class ServerConfiguration { /** * Load WordPress client configurations * Returns a Map of site ID to WordPressClient instances */ public async loadClientConfigurations(mcpConfig?: McpConfigType): Promise<{ clients: Map<string, WordPressClient>; configs: SiteConfig[]; }> { const configPath = path.resolve(this.rootDir, "mcp-wordpress.config.json"); try { await fsPromises.access(configPath); return await this.loadMultiSiteConfig(configPath); // ✅ Multi-site config } catch (_error) { return this.loadSingleSiteFromEnv(mcpConfig); // ✅ Single-site fallback } } } ``` **Multi-Site Configuration Format**: [mcp-wordpress.config.json.example](mcp-wordpress.config.json.example) ```json { "sites": [ { "id": "site1", "name": "My First WordPress Site", "config": { "WORDPRESS_SITE_URL": "https://site1.example.com", "WORDPRESS_USERNAME": "your_username", "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx" } }, { "id": "site2", "name": "My Second WordPress Site", "config": { "WORDPRESS_SITE_URL": "https://site2.example.com", "WORDPRESS_USERNAME": "your_username", "WORDPRESS_APP_PASSWORD": "xxxx xxxx xxxx xxxx xxxx xxxx" } } ] } ``` ### 2. DXT Manifest Limitation ❌ **File**: [dxt/manifest.json](dxt/manifest.json) The manifest only exposes single-site configuration: ```json { "user_config": { "wordpress_site_url": { "type": "string", "title": "WordPress Site URL", "required": true }, "wordpress_username": { "type": "string", "title": "WordPress Username", "required": true }, "wordpress_app_password": { "type": "string", "title": "WordPress Application Password", "required": true, "sensitive": true } } } ``` **Problem**: No mechanism to configure multiple sites through the DXT user interface. ### 3. DXT Entry Point **File**: [src/dxt-entry.ts](src/dxt-entry.ts) ```typescript logger.debug("Environment variables passed from DXT:"); logger.debug(` MULTI_SITE_MODE: ${process.env.MULTI_SITE_MODE ? "SET" : "NOT SET"}`); logger.debug(` WORDPRESS_SITE_URL: ${process.env.WORDPRESS_SITE_URL ? "SET" : "NOT SET"}`); ``` The entry point checks for `MULTI_SITE_MODE` but there's **no way to set it** through the DXT manifest. --- ## Current DXT Configuration Flow ``` Claude Desktop User ↓ Installs mcp-wordpress.dxt ↓ Claude Desktop shows user_config form: - wordpress_site_url (string) - wordpress_username (string) - wordpress_app_password (string) - auth_method (string, optional) - debug_mode (boolean, optional) ↓ Environment variables set: - WORDPRESS_SITE_URL - WORDPRESS_USERNAME - WORDPRESS_APP_PASSWORD - WORDPRESS_AUTH_METHOD - DEBUG ↓ dxt-entry.js loads → index.js ↓ ServerConfiguration.loadClientConfigurations() ↓ Tries to find mcp-wordpress.config.json → NOT FOUND (DXT doesn't package it) ↓ Falls back to single-site mode from env vars ↓ RESULT: Only ONE site configured ❌ ``` --- ## Issues Identified ### Issue #1: No Multi-Site User Configuration **Severity**: High **Impact**: Users cannot configure multiple WordPress sites The DXT manifest `user_config` only allows one set of credentials. There's no way to define multiple sites through the Claude Desktop UI. ### Issue #2: Missing Configuration File in DXT Package **Severity**: High **Impact**: Even if user manually creates config, it's not in DXT filesystem The DXT package doesn't include or support `mcp-wordpress.config.json`: **File**: [scripts/build-dxt-clean.cjs](scripts/build-dxt-clean.cjs:48) ```javascript // Copy essential config files await fs.copy(path.join(rootDir, 'package.json'), path.join(tempDir, 'package.json')); await fs.copy(path.join(rootDir, 'package-lock.json'), path.join(tempDir, 'package-lock.json')); await fs.copy(path.join(rootDir, 'LICENSE'), path.join(tempDir, 'LICENSE')); await fs.copy(path.join(rootDir, 'mcp-wordpress.config.json.example'), path.join(tempDir, 'mcp-wordpress.config.json.example')); // ❌ But ServerConfiguration looks for mcp-wordpress.config.json (not .example) ``` ### Issue #3: Manifest Version Mismatch **Severity**: Low **Impact**: Users may see outdated version **Manifest**: `"version": "2.6.3"` **Package.json**: `"version": "2.10.2"` The manifest version is hardcoded and outdated. ### Issue #4: Missing Multi-Site Prompts **Severity**: Medium **Impact**: Users see multi-site prompts but can't use them **Manifest prompts include**: ```json { "name": "multi_site_management", "description": "Multi-site WordPress administration workflow" } ``` But users can't actually configure multiple sites! This is misleading. --- ## Proposed Solutions ### Solution Option 1: Add Array Support to DXT Manifest (Ideal) **If DXT spec supports arrays**, modify manifest: ```json { "user_config": { "sites": { "type": "array", "title": "WordPress Sites", "description": "Configure one or more WordPress sites", "items": { "type": "object", "properties": { "site_id": { "type": "string", "title": "Site ID", "required": true }, "site_url": { "type": "string", "title": "Site URL", "required": true }, "username": { "type": "string", "title": "Username", "required": true }, "app_password": { "type": "string", "title": "App Password", "required": true, "sensitive": true } } }, "required": true } } } ``` **Pros**: - ✅ Clean user experience - ✅ Native multi-site support - ✅ Matches codebase capability **Cons**: - ❌ Requires DXT spec to support array types - ❌ May not be supported in DXT 0.1 ### Solution Option 2: JSON String Configuration Allow users to paste a JSON configuration string: ```json { "user_config": { "multi_site_config": { "type": "string", "title": "Multi-Site Configuration (JSON)", "description": "Paste your multi-site configuration as JSON, or leave empty for single-site mode", "required": false }, "wordpress_site_url": { "type": "string", "title": "WordPress Site URL (Single-Site Mode)", "required": false } // ... other single-site fields } } ``` **DXT Entry Logic**: ```typescript if (process.env.MULTI_SITE_CONFIG) { const config = JSON.parse(process.env.MULTI_SITE_CONFIG); // Write to mcp-wordpress.config.json in DXT working directory // Then reload configuration } else { // Use single-site mode from individual env vars } ``` **Pros**: - ✅ Works with current DXT spec - ✅ Supports advanced users - ✅ Minimal code changes **Cons**: - ❌ Poor UX (users paste JSON) - ❌ Error-prone - ❌ Not beginner-friendly ### Solution Option 3: Post-Install Configuration File Create configuration file after DXT installation: 1. DXT installs with single-site config 2. Show prompt: "To configure multiple sites, create mcp-wordpress.config.json in [location]" 3. Provide documentation link 4. Server detects config file on next startup **Pros**: - ✅ Clean separation - ✅ Power users can configure - ✅ Works with current DXT **Cons**: - ❌ Extra manual step - ❌ Users need to know file location - ❌ May be confusing ### Solution Option 4: Single-Site Only (Document Limitation) Accept that DXT = single-site only, and document it clearly: **Update manifest**: ```json { "name": "mcp-wordpress-single", "display_name": "WordPress MCP Server (Single Site)", "description": "WordPress management for a single site. For multi-site support, use NPM installation." } ``` Remove multi-site prompts from manifest. **Pros**: - ✅ Clear expectations - ✅ No code changes - ✅ Still useful for most users **Cons**: - ❌ Limits DXT functionality - ❌ Wastes existing multi-site code - ❌ Two different installation experiences --- ## Recommended Approach ### Phase 1: Immediate Fix (Single-Site Clarification) 1. **Update manifest.json**: - Set correct version: `"version": "2.10.2"` - Update description to mention "single-site mode when installed via DXT" - Remove `multi_site_management` prompt - Add note about NPM install for multi-site 2. **Update DXT entry point**: - Remove MULTI_SITE_MODE logging (not applicable in DXT) - Add clear single-site mode message 3. **Rebuild DXT package**: ```bash npm run dxt:package:official ``` ### Phase 2: Enhanced Multi-Site Support (If Requested) 1. **Research DXT spec** for array support 2. **Implement Solution Option 1 or 2** based on findings 3. **Test thoroughly** with Claude Desktop 4. **Update documentation** --- ## Files That Need Changes ### Immediate (Phase 1) 1. [dxt/manifest.json](dxt/manifest.json) - Update version to 2.10.2 - Clarify single-site limitation - Remove multi_site_management prompt 2. [src/dxt-entry.ts](src/dxt-entry.ts) - Remove MULTI_SITE_MODE debug logging - Add single-site mode confirmation 3. [scripts/build-dxt-clean.cjs](scripts/build-dxt-clean.cjs) - Ensure version sync from package.json ### Future (Phase 2) 4. [dxt/manifest.json](dxt/manifest.json) - Add multi-site configuration schema 5. [src/dxt-entry.ts](src/dxt-entry.ts) - Handle multi-site config from env or JSON 6. [src/config/ServerConfiguration.ts](src/config/ServerConfiguration.ts) - Support loading config from DXT-provided JSON --- ## Testing Plan ### Test 1: Current DXT Package ```bash # Extract and inspect unzip -l mcp-wordpress.dxt | grep -E "(manifest|dxt-entry|config)" # Check version unzip -p mcp-wordpress.dxt manifest.json | jq '.version' # Expected: Old version, multi-site prompts present ``` ### Test 2: Single-Site Installation 1. Install DXT in Claude Desktop 2. Configure one site 3. Verify server starts 4. Check that tools are available 5. Verify only one site is accessible ### Test 3: Multi-Site Attempt 1. Try to configure multiple sites through UI 2. Expected: Not possible with current manifest 3. Document user experience --- ## Additional Issues Found ### Build Script Issues The build script syncs version but **after** the manifest is already copied: ```javascript // Copy manifest FIRST (with old version) await fs.writeJson(path.join(tempDir, 'manifest.json'), manifest, { spaces: 2 }); // THEN update version manifest.version = packageJson.version; // ❌ But it's already written! This doesn't update the file! ``` **Fix needed**: Update manifest version **before** writing. --- ## Waiting for User Log Currently waiting for Claude Desktop log file to identify specific runtime errors. Based on manifest analysis, expected errors: 1. ✅ Server starts successfully (single-site mode works) 2. ⚠️ User confusion about multi-site prompts 3. ⚠️ Version mismatch warnings 4. ❌ Attempts to access multi-site features fail --- ## Next Steps 1. ⏳ **Wait for user to provide Claude Desktop log file** 2. 📝 Analyze log for specific errors 3. 🔧 Implement Phase 1 fixes 4. 🧪 Test rebuilt DXT package 5. 📚 Update documentation 6. 🚀 Evaluate Phase 2 enhancements --- **Status**: Analysis complete, awaiting log file for confirmation **Files to Review**: - ✅ dxt/manifest.json - ✅ src/dxt-entry.ts - ✅ src/config/ServerConfiguration.ts - ✅ scripts/build-dxt-clean.cjs - ⏳ Claude Desktop log (pending from user)