mcp-wordpress 1.4.0 → 1.5.0

package/docs/developer/CONTRIBUTING.md

@@ -138,7 +138,7 @@ export class PostTools {
   constructor(private client: WordPressClient) {}
 
   async createPost(params: CreatePostParams): Promise<PostResult> {
-    return toolWrapper(this.client, 'create_post', params, async () => {
+    return toolWrapper(this.client, "create_post", params, async () => {
       const validatedParams = createPostSchema.parse(params);
       return await this.client.posts.create(validatedParams);
     });
@@ -191,31 +191,33 @@ async function listPosts(params: any) {
 
 ```typescript
 // ✅ Good: Comprehensive test coverage
-describe('PostTools', () => {
-  describe('createPost', () => {
-    test('should create post with valid parameters', async () => {
+describe("PostTools", () => {
+  describe("createPost", () => {
+    test("should create post with valid parameters", async () => {
       const params = {
-        title: 'Test Post',
-        content: 'Test content',
-        status: 'publish' as PostStatus
+        title: "Test Post",
+        content: "Test content",
+        status: "publish" as PostStatus,
       };
-      
+
       const result = await postTools.createPost(params);
-      
+
       expect(result.success).toBe(true);
-      expect(result.data.title).toBe('Test Post');
+      expect(result.data.title).toBe("Test Post");
     });
 
-    test('should handle invalid parameters', async () => {
-      const params = { title: '' }; // Invalid empty title
-      
+    test("should handle invalid parameters", async () => {
+      const params = { title: "" }; // Invalid empty title
+
       await expect(postTools.createPost(params)).rejects.toThrow();
     });
 
-    test('should handle API errors gracefully', async () => {
-      mockClient.posts.create.mockRejectedValue(new Error('API Error'));
-      
-      await expect(postTools.createPost(validParams)).rejects.toThrow('API Error');
+    test("should handle API errors gracefully", async () => {
+      mockClient.posts.create.mockRejectedValue(new Error("API Error"));
+
+      await expect(postTools.createPost(validParams)).rejects.toThrow(
+        "API Error",
+      );
     });
   });
 });
@@ -246,9 +248,9 @@ describe('PostTools', () => {
 const createPostSchema = z.object({
   title: z.string().min(1).max(200),
   content: z.string().optional(),
-  status: z.enum(['draft', 'publish', 'private', 'pending']).optional(),
+  status: z.enum(["draft", "publish", "private", "pending"]).optional(),
   author: z.number().positive().optional(),
-  site: z.string().optional()
+  site: z.string().optional(),
 });
 
 // Always validate before processing
@@ -286,10 +288,10 @@ getAuthHeaders(): Record<string, string> {
 
 ### Code Documentation
 
-```typescript
+````typescript
 /**
  * Creates a new WordPress post with the specified parameters.
- * 
+ *
  * @param params - The post creation parameters
  * @param params.title - The post title (required)
  * @param params.content - The post content (optional)
@@ -297,7 +299,7 @@ getAuthHeaders(): Record<string, string> {
  * @param params.site - The target site ID for multi-site setups (optional)
  * @returns Promise resolving to the created post information
  * @throws {Error} When post creation fails or parameters are invalid
- * 
+ *
  * @example
  * ```typescript
  * const post = await postTools.createPost({
@@ -310,7 +312,7 @@ getAuthHeaders(): Record<string, string> {
 async createPost(params: CreatePostParams): Promise<PostResult> {
   // Implementation
 }
-```
+````
 
 ### Update Documentation
 
@@ -350,9 +352,11 @@ When requesting features:
 
 ```markdown
 ## Description
+
 Brief description of the changes made.
 
 ## Type of Change
+
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
@@ -361,6 +365,7 @@ Brief description of the changes made.
 - [ ] Security improvement
 
 ## Testing
+
 - [ ] Unit tests added/updated
 - [ ] Integration tests added/updated
 - [ ] Security tests added/updated
@@ -368,6 +373,7 @@ Brief description of the changes made.
 - [ ] Performance tests pass (if applicable)
 
 ## Checklist
+
 - [ ] Code follows the established patterns
 - [ ] Self-review completed
 - [ ] Code is commented where necessary

package/docs/developer/DXT-DEBUG-BEST-PRACTICES.md

@@ -0,0 +1,212 @@
+# DXT Extension Debugging Guide
+
+## Quick Start Debugging
+
+**Extension failing? Run this first:**
+
+```bash
+# 1. Check if it's a valid zip
+unzip -t extension.dxt
+
+# 2. Extract and inspect structure
+unzip extension.dxt -d temp/ && ls -la temp/
+
+# 3. Validate manifest
+cat temp/manifest.json | jq .
+
+# 4. Check for nested directories (common issue!)
+unzip -l extension.dxt | head -5
+```
+
+## Common Error Patterns & Solutions
+
+### 1. "Invalid zip data" / "Failed to unzip"
+
+```bash
+# Verify file integrity
+file extension.dxt
+zip -T extension.dxt
+
+# Fix: Repackage correctly
+cd extension-source/
+zip -r ../extension.dxt * # NOT the directory itself!
+```
+
+### 2. "Invalid manifest" errors
+
+```bash
+# Install DXT CLI first
+npm install -g @anthropic-ai/dxt
+
+# Validate manifest
+dxt validate manifest.json
+
+# Common fixes:
+# - Missing required fields (name, version, description, type, main)
+# - Invalid JSON syntax
+# - Wrong structure for prompts/tools
+```
+
+### 3. "Module not found" / Missing dependencies
+
+```bash
+# For Node.js extensions
+npm install
+zip -r extension.dxt manifest.json server.js package*.json node_modules/
+
+# For Python extensions
+pip install -r requirements.txt -t lib/
+zip -r extension.dxt manifest.json main.py lib/
+```
+
+## Manifest Structure (MCP Type)
+
+```json
+{
+  "name": "extension-name",
+  "version": "1.0.0",
+  "description": "Clear description",
+  "type": "mcp",
+  "main": "server.js",
+  "mcp": {
+    "command": "node",
+    "args": ["server.js"],
+    "env": {}
+  },
+  "user_config": {
+    "api_key": {
+      "type": "string",
+      "title": "API Key",
+      "description": "Your service API key",
+      "sensitive": true,
+      "required": true
+    }
+  },
+  "prompts": {
+    "example_prompt": {
+      "name": "example_prompt",
+      "description": "What this prompt does",
+      "arguments": {
+        "input": {
+          "type": "string",
+          "description": "Input parameter",
+          "required": true
+        }
+      }
+    }
+  }
+}
+```
+
+## Development Workflow
+
+### 1. Initialize Extension
+
+```bash
+mkdir my-extension && cd my-extension
+dxt init  # Interactive setup
+# OR
+dxt init --yes  # Quick defaults
+```
+
+### 2. Develop & Test Locally
+
+```bash
+# Test your server directly
+node server.js  # or python main.py
+
+# Validate manifest frequently
+dxt validate .
+```
+
+### 3. Package Extension
+
+```bash
+# From extension directory
+dxt pack . my-extension.dxt
+
+# Manual packaging (if needed)
+zip -r ../my-extension.dxt manifest.json server.js package*.json node_modules/
+```
+
+### 4. Debug Installation Issues
+
+```bash
+# Test the package
+unzip -t my-extension.dxt
+
+# Verify structure (no nested dirs!)
+unzip -l my-extension.dxt | grep -E "manifest.json|server.js|main.py"
+
+# Should show files at root:
+# 0  2024-01-01 12:00   manifest.json
+# 0  2024-01-01 12:00   server.js
+# NOT: my-extension/manifest.json
+```
+
+## Quick Fixes
+
+### Fix Nested Directory Structure
+
+```bash
+unzip bad.dxt
+cd extracted-folder/
+zip -r ../fixed.dxt *
+```
+
+### Fix Invalid JSON
+
+```bash
+# Pretty print and validate
+jq . manifest.json > manifest-fixed.json
+mv manifest-fixed.json manifest.json
+```
+
+### Add Missing Dependencies
+
+```bash
+# Node.js
+npm install
+npm list --depth=0  # Verify
+
+# Python
+pip freeze > requirements.txt
+```
+
+### Debug MCP Communication
+
+```javascript
+// Add logging to your server
+console.error('[DEBUG]', JSON.stringify(request, null, 2));
+
+// Test with stdio
+echo '{"jsonrpc":"2.0","method":"initialize","id":1}' | node server.js
+```
+
+## Best Practices
+
+1. **Always validate before packaging**: `dxt validate .`
+2. **Test locally first**: Run your server standalone
+3. **Use semantic versioning**: Update version on changes
+4. **Include all dependencies**: Bundle everything needed
+5. **Handle errors gracefully**: Don't crash on bad input
+6. **Use user_config for secrets**: Mark sensitive fields
+7. **Keep file structure flat**: No nested directories
+
+## Debugging Checklist
+
+- [ ] Valid zip file? (`unzip -t`)
+- [ ] Correct structure? (files at root)
+- [ ] Valid JSON? (`jq . manifest.json`)
+- [ ] All required fields? (`dxt validate`)
+- [ ] Dependencies included? (`node_modules/` or `lib/`)
+- [ ] Main file exists? (`server.js` or as specified)
+- [ ] MCP protocol implemented? (initialize, tools/prompts)
+- [ ] Error handling in place?
+
+## Need Help?
+
+1. Check examples: <https://github.com/anthropics/dxt/tree/main/examples>
+2. Use `dxt init` for correct structure
+3. Test with `dxt validate` before packaging
+4. Enable debug logs in Claude Desktop settings

package/docs/developer/README.md

@@ -5,21 +5,25 @@ This directory contains comprehensive documentation for developers contributing
 ## 📋 Developer Guides
 
 ### Getting Started
+
 - **[Development Setup](DEVELOPMENT_SETUP.md)** - Local development environment setup
 - **[Architecture Overview](ARCHITECTURE.md)** - System architecture and design patterns
 - **[Contributing Guidelines](CONTRIBUTING.md)** - How to contribute to the project
 
 ### Technical Reference
+
 - **[API Reference](API_REFERENCE.md)** - Complete technical API documentation
 - **[Testing Guide](TESTING.md)** - Test suite, CI/CD, and testing best practices
 - **[Performance Guide](PERFORMANCE_DEVELOPMENT.md)** - Performance optimization and monitoring
 
 ### Build & Deployment
+
 - **[Build System](BUILD_SYSTEM.md)** - TypeScript compilation and build process
 - **[Release Process](RELEASE_PROCESS.md)** - Semantic versioning and automated releases
 - **[CI/CD Pipeline](CI_CD_PIPELINE.md)** - GitHub Actions workflows and automation
 
 ### Maintenance & Operations
+
 - **[Maintenance Guide](MAINTENANCE.md)** - Ongoing maintenance and updates
 - **[Migration Guide](MIGRATION_GUIDE.md)** - Breaking changes and migration paths
 - **[Security Guidelines](SECURITY_DEVELOPMENT.md)** - Security best practices for development
@@ -53,12 +57,14 @@ mcp-wordpress/
 ## 🔧 Development Environment
 
 ### Prerequisites
+
 - **Node.js 18+** - Runtime environment
 - **TypeScript 5+** - Primary development language
 - **Docker** - For containerization and testing
 - **Git** - Version control
 
 ### Quick Setup
+
 ```bash
 # Clone the repository
 git clone https://github.com/docdyhr/mcp-wordpress.git
@@ -78,6 +84,7 @@ npm run dev
 ```
 
 ### Development Commands
+
 ```bash
 # Build and compilation
 npm run build              # Compile TypeScript
@@ -103,6 +110,7 @@ npm run status             # Check connection status
 ## 🧪 Testing Infrastructure
 
 ### Test Categories
+
 - **Unit Tests** - Individual component testing
 - **Integration Tests** - WordPress API integration
 - **Security Tests** - Vulnerability and penetration testing
@@ -111,6 +119,7 @@ npm run status             # Check connection status
 - **Property-Based Tests** - Generative testing with edge cases
 
 ### Current Test Status ✅
+
 - **Main Test Suite**: 207/207 passed (100%)
 - **Security Tests**: 40/40 passed (100%)
 - **Performance Tests**: 8/8 passed (100%)
@@ -119,18 +128,21 @@ npm run status             # Check connection status
 ## 🏛️ Architecture Highlights
 
 ### Modular Client Architecture
+
 - **Manager Pattern** - Composition over inheritance
 - **Authentication Manager** - Multiple auth method support
 - **Request Manager** - HTTP operations with retry logic
 - **Cache Manager** - Multi-layer caching system
 
 ### Tool System
+
 - **Class-Based Tools** - Consistent tool implementation pattern
 - **Type-Safe Parameters** - Comprehensive Zod validation
 - **Error Handling** - Standardized error patterns
 - **Multi-Site Support** - Site-specific tool execution
 
 ### Performance Systems
+
 - **Intelligent Caching** - 50-70% performance improvement
 - **Real-Time Monitoring** - Comprehensive metrics collection
 - **Performance Analytics** - Trend analysis and optimization
@@ -139,12 +151,14 @@ npm run status             # Check connection status
 ## 📚 Documentation System
 
 ### Auto-Generated Documentation
+
 - **Tool Documentation** - Extracted from TypeScript definitions
 - **OpenAPI Specification** - Machine-readable API spec
 - **Markdown Generation** - User-friendly documentation
 - **CI/CD Integration** - Automatic updates on code changes
 
 ### Documentation Standards
+
 - **JSDoc Comments** - Comprehensive code documentation
 - **Type Annotations** - Complete TypeScript typing
 - **Usage Examples** - Practical implementation examples
@@ -153,6 +167,7 @@ npm run status             # Check connection status
 ## 🔒 Security Framework
 
 ### Security Measures
+
 - **Input Validation** - Comprehensive Zod schema validation
 - **Authentication Security** - Multiple secure auth methods
 - **Rate Limiting** - API abuse prevention
@@ -160,6 +175,7 @@ npm run status             # Check connection status
 - **HTTPS Enforcement** - Secure communication
 
 ### Security Testing
+
 - **Penetration Tests** - Automated vulnerability testing
 - **Input Validation Tests** - Edge case and injection testing
 - **Authentication Tests** - Security validation for all auth methods
@@ -168,12 +184,14 @@ npm run status             # Check connection status
 ## 🚀 Release & Publishing
 
 ### Automated Release Pipeline
+
 - **Semantic Versioning** - Conventional commit-based versioning
 - **Multi-Platform Publishing** - NPM and Docker Hub
 - **Security Scanning** - Automated vulnerability detection
 - **Performance Validation** - Regression testing before release
 
 ### Distribution Channels
+
 - **NPM Package** - Node.js package manager
 - **Docker Images** - Multi-architecture container images
 - **GitHub Releases** - Source code and release notes
@@ -181,6 +199,7 @@ npm run status             # Check connection status
 ## 🤝 Contributing
 
 ### Development Workflow
+
 1. **Fork & Clone** - Create your development environment
 2. **Feature Branch** - Create feature branches from main
 3. **Development** - Implement changes with tests
@@ -189,6 +208,7 @@ npm run status             # Check connection status
 6. **Pull Request** - Submit for review
 
 ### Code Standards
+
 - **TypeScript** - Strict mode with comprehensive typing
 - **ESLint** - Consistent code style and best practices
 - **Prettier** - Automated code formatting
@@ -196,6 +216,7 @@ npm run status             # Check connection status
 - **Conventional Commits** - Semantic commit messages
 
 ### Review Process
+
 - **Automated Testing** - CI/CD pipeline validation
 - **Security Scanning** - Automated vulnerability detection
 - **Performance Testing** - Regression detection
@@ -205,15 +226,17 @@ npm run status             # Check connection status
 ## 📞 Getting Help
 
 ### Development Support
+
 - **GitHub Issues** - Bug reports and feature requests
 - **GitHub Discussions** - Development questions and community
 - **Security Issues** - Responsible disclosure process
 
 ### Resources
+
 - **WordPress REST API** - Official WordPress API documentation
 - **Model Context Protocol** - MCP specification and guidelines
 - **TypeScript Handbook** - TypeScript language reference
 
 ---
 
-**Ready to contribute?** Start with the [Development Setup](DEVELOPMENT_SETUP.md) guide and join our community of contributors!
+**Ready to contribute?** Start with the [Development Setup](DEVELOPMENT_SETUP.md) guide and join our community of contributors!

package/docs/developer/RELEASE_PROCESS.md

@@ -52,7 +52,7 @@ fix: resolve authentication header issue in POST requests
 fix(auth): handle JWT token expiration gracefully
 fix(cache): fix cache invalidation for multi-site setups
 
-# MINOR version bump  
+# MINOR version bump
 feat: add new WordPress plugin management tool
 feat(tools): add bulk comment moderation functionality
 feat(api): add support for custom post types
@@ -111,11 +111,11 @@ on:
   workflow_dispatch:
     inputs:
       release_type:
-        description: 'Release type'
+        description: "Release type"
         required: true
-        default: 'patch'
+        default: "patch"
         type: choice
-        options: ['patch', 'minor', 'major', 'prerelease']
+        options: ["patch", "minor", "major", "prerelease"]
 
 jobs:
   release:
@@ -127,25 +127,25 @@ jobs:
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
-      
+
       - name: 📦 Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'npm'
-      
+          node-version: "20"
+          cache: "npm"
+
       - name: 📦 Install Dependencies
         run: npm ci
-      
+
       - name: 🧪 Run Tests
         run: npm test
-      
+
       - name: 🔒 Security Audit
         run: npm audit --audit-level=high
-      
+
       - name: 🏗️ Build Project
         run: npm run build
-      
+
       - name: 🚀 Semantic Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -244,17 +244,17 @@ jobs:
 {
   "preset": "conventionalcommits",
   "releaseRules": [
-    {"type": "feat", "release": "minor"},
-    {"type": "fix", "release": "patch"},
-    {"type": "perf", "release": "patch"},
-    {"type": "docs", "release": false},
-    {"type": "style", "release": false},
-    {"type": "refactor", "release": "patch"},
-    {"type": "test", "release": false},
-    {"type": "build", "release": "patch"},
-    {"type": "ci", "release": false},
-    {"type": "chore", "release": false},
-    {"breaking": true, "release": "major"}
+    { "type": "feat", "release": "minor" },
+    { "type": "fix", "release": "patch" },
+    { "type": "perf", "release": "patch" },
+    { "type": "docs", "release": false },
+    { "type": "style", "release": false },
+    { "type": "refactor", "release": "patch" },
+    { "type": "test", "release": false },
+    { "type": "build", "release": "patch" },
+    { "type": "ci", "release": false },
+    { "type": "chore", "release": false },
+    { "breaking": true, "release": "major" }
   ]
 }
 ```
@@ -421,26 +421,30 @@ npm dist-tag add mcp-wordpress@1.2.3 latest
 # [1.3.0](https://github.com/docdyhr/mcp-wordpress/compare/v1.2.0...v1.3.0) (2024-01-15)
 
 ### Features
-* add new WordPress plugin management tool ([abc123](https://github.com/docdyhr/mcp-wordpress/commit/abc123))
-* improve authentication system ([def456](https://github.com/docdyhr/mcp-wordpress/commit/def456))
+
+- add new WordPress plugin management tool ([abc123](https://github.com/docdyhr/mcp-wordpress/commit/abc123))
+- improve authentication system ([def456](https://github.com/docdyhr/mcp-wordpress/commit/def456))
 
 ### Bug Fixes
-* resolve cache invalidation issue ([ghi789](https://github.com/docdyhr/mcp-wordpress/commit/ghi789))
+
+- resolve cache invalidation issue ([ghi789](https://github.com/docdyhr/mcp-wordpress/commit/ghi789))
 
 ### BREAKING CHANGES
-* authentication configuration format has changed
+
+- authentication configuration format has changed
 ```
 
 ### Migration Guides
 
 For breaking changes, create migration guides in `docs/developer/MIGRATION_GUIDE.md`:
 
-```markdown
+````markdown
 ## Migrating from v1.x to v2.x
 
 ### Authentication Configuration Changes
 
 **Before (v1.x)**:
+
 ```javascript
 {
   auth: {
@@ -449,6 +453,7 @@ For breaking changes, create migration guides in `docs/developer/MIGRATION_GUIDE
   }
 }
 ```
+````
 
 **After (v2.x)**: