mcp-wordpress 1.1.7 → 1.2.2

package/dist/docs/DocumentationGenerator.js

@@ -0,0 +1,735 @@
+/**
+ * Comprehensive API Documentation Auto-Generation System
+ * Extracts documentation from tool classes, types, and WordPress mappings
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as Tools from '../tools/index.js';
+/**
+ * Main Documentation Generator
+ */
+export class DocumentationGenerator {
+    config;
+    toolCategories = new Map();
+    wordpressEndpoints = new Map();
+    constructor(config = {}) {
+        this.config = {
+            outputDir: 'docs/api',
+            includeExamples: true,
+            includeWordPressMapping: true,
+            generateOpenAPI: true,
+            generateInteractiveHtml: true,
+            validateExamples: false,
+            ...config
+        };
+        this.initializeWordPressMapping();
+        this.initializeToolCategories();
+    }
+    /**
+     * Generate complete documentation for all tools and types
+     */
+    async generateFullDocumentation() {
+        console.log('🚀 Starting API documentation generation...');
+        const tools = await this.extractAllToolDocumentation();
+        const categories = this.generateCategoryDocumentation(tools);
+        const types = await this.extractTypeDocumentation();
+        let openApiSpec = undefined;
+        if (this.config.generateOpenAPI) {
+            openApiSpec = this.generateOpenAPISpecification(tools, types);
+        }
+        const summary = this.generateDocumentationSummary(tools, categories, types);
+        const output = {
+            tools,
+            categories,
+            types,
+            openApiSpec,
+            summary
+        };
+        // Write documentation to files
+        await this.writeDocumentationFiles(output);
+        console.log(`✅ Documentation generation complete! ${tools.length} tools documented.`);
+        return output;
+    }
+    /**
+     * Extract documentation from all tool classes
+     */
+    async extractAllToolDocumentation() {
+        const toolDocs = [];
+        // Iterate through all tool classes
+        for (const [className, ToolClass] of Object.entries(Tools)) {
+            try {
+                // Create tool instance
+                let toolInstance;
+                if (className === 'CacheTools' || className === 'PerformanceTools') {
+                    // These tools need client map - use empty map for doc generation
+                    toolInstance = new ToolClass(new Map());
+                }
+                else {
+                    toolInstance = new ToolClass();
+                }
+                const toolDefinitions = toolInstance.getTools();
+                const category = this.extractCategoryFromClassName(className);
+                for (const toolDef of toolDefinitions) {
+                    const doc = await this.extractToolDocumentation(toolDef, category, className);
+                    toolDocs.push(doc);
+                }
+            }
+            catch (error) {
+                console.warn(`⚠️ Failed to extract documentation for ${className}:`, error);
+            }
+        }
+        return toolDocs.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Extract documentation for a single tool
+     */
+    async extractToolDocumentation(toolDef, category, className) {
+        const parameters = this.extractParameterDocumentation(toolDef.parameters || []);
+        const examples = this.generateToolExamples(toolDef, category);
+        const wordpressEndpoint = this.wordpressEndpoints.get(toolDef.name);
+        const returnType = this.inferReturnType(toolDef.name, category);
+        const errorCodes = this.generateErrorDocumentation(toolDef.name);
+        const relatedTools = this.findRelatedTools(toolDef.name, category);
+        return {
+            name: toolDef.name,
+            category,
+            description: toolDef.description || `${category} tool: ${toolDef.name}`,
+            parameters,
+            examples,
+            wordpressEndpoint,
+            requiredPermissions: this.getRequiredPermissions(toolDef.name),
+            returnType,
+            errorCodes,
+            relatedTools
+        };
+    }
+    /**
+     * Extract parameter documentation
+     */
+    extractParameterDocumentation(parameters) {
+        return parameters.map(param => ({
+            name: param.name,
+            type: param.type || 'string',
+            required: param.required || false,
+            description: param.description || `${param.name} parameter`,
+            defaultValue: this.getDefaultValue(param),
+            allowedValues: this.getAllowedValues(param) || undefined,
+            examples: this.generateParameterExamples(param)
+        }));
+    }
+    /**
+     * Generate usage examples for tools
+     */
+    generateToolExamples(toolDef, category) {
+        const examples = [];
+        // Basic usage example
+        const basicExample = this.generateBasicExample(toolDef, category);
+        if (basicExample) {
+            examples.push(basicExample);
+        }
+        // Multi-site example (if applicable)
+        if (this.supportsMultiSite(toolDef)) {
+            const multiSiteExample = this.generateMultiSiteExample(toolDef, category);
+            if (multiSiteExample) {
+                examples.push(multiSiteExample);
+            }
+        }
+        // Advanced example with all parameters
+        const advancedExample = this.generateAdvancedExample(toolDef, category);
+        if (advancedExample) {
+            examples.push(advancedExample);
+        }
+        return examples;
+    }
+    /**
+     * Generate basic usage example
+     */
+    generateBasicExample(toolDef, category) {
+        const toolName = toolDef.name;
+        const basicParams = {};
+        // Add essential parameters
+        const requiredParams = (toolDef.parameters || []).filter(p => p.required);
+        for (const param of requiredParams.slice(0, 2)) { // Limit to 2 for basic example
+            basicParams[param.name] = this.generateExampleValue(param);
+        }
+        return {
+            title: `Basic ${category} Usage`,
+            description: `Simple example of using ${toolName}`,
+            command: toolName,
+            parameters: basicParams,
+            expectedResponse: this.generateExpectedResponse(toolName, category, 'basic'),
+            errorExample: {
+                scenario: 'Authentication failure',
+                error: {
+                    error: 'Authentication failed',
+                    message: 'Invalid credentials or insufficient permissions'
+                }
+            }
+        };
+    }
+    /**
+     * Generate multi-site example
+     */
+    generateMultiSiteExample(toolDef, category) {
+        const params = { site: 'site1', ...this.getExampleParameters(toolDef, 1) };
+        return {
+            title: `Multi-Site ${category} Usage`,
+            description: `Using ${toolDef.name} with specific site targeting`,
+            command: toolDef.name,
+            parameters: params,
+            expectedResponse: this.generateExpectedResponse(toolDef.name, category, 'multisite')
+        };
+    }
+    /**
+     * Generate advanced example with all parameters
+     */
+    generateAdvancedExample(toolDef, category) {
+        const allParams = this.getExampleParameters(toolDef, 'all');
+        if (Object.keys(allParams).length <= 2) {
+            return null; // Skip if not enough parameters for advanced example
+        }
+        return {
+            title: `Advanced ${category} Configuration`,
+            description: 'Comprehensive example using all available parameters',
+            command: toolDef.name,
+            parameters: allParams,
+            expectedResponse: this.generateExpectedResponse(toolDef.name, category, 'advanced')
+        };
+    }
+    /**
+     * Generate category documentation
+     */
+    generateCategoryDocumentation(tools) {
+        const categories = new Map();
+        // Group tools by category
+        for (const tool of tools) {
+            if (!categories.has(tool.category)) {
+                categories.set(tool.category, []);
+            }
+            categories.get(tool.category).push(tool);
+        }
+        return Array.from(categories.entries()).map(([categoryName, categoryTools]) => ({
+            name: categoryName,
+            description: this.getCategoryDescription(categoryName),
+            toolCount: categoryTools.length,
+            tools: categoryTools.map(t => t.name).sort(),
+            usagePatterns: this.generateUsagePatterns(categoryName, categoryTools)
+        }));
+    }
+    /**
+     * Extract type documentation from TypeScript definitions
+     */
+    async extractTypeDocumentation() {
+        // This would analyze TypeScript files to extract type information
+        // For now, we'll provide key WordPress and MCP types
+        return [
+            {
+                name: 'WordPressPost',
+                description: 'WordPress blog post object',
+                properties: [
+                    { name: 'id', type: 'number', required: true, description: 'Unique identifier' },
+                    { name: 'title', type: 'string', required: true, description: 'Post title' },
+                    { name: 'content', type: 'string', required: true, description: 'Post content' },
+                    { name: 'status', type: 'string', required: true, description: 'Publication status' }
+                ],
+                examples: [this.generateWordPressPostExample()],
+                wordpressSource: '/wp-json/wp/v2/posts'
+            }
+            // Add more types as needed
+        ];
+    }
+    /**
+     * Generate OpenAPI specification
+     */
+    generateOpenAPISpecification(tools, types) {
+        const paths = {};
+        const components = {
+            schemas: {},
+            parameters: {},
+            responses: {}
+        };
+        // Convert tools to OpenAPI paths
+        for (const tool of tools) {
+            const path = `/tools/${tool.name}`;
+            paths[path] = {
+                post: {
+                    summary: tool.description,
+                    description: `Execute ${tool.name} MCP tool`,
+                    tags: [tool.category],
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: this.generateParameterSchema(tool.parameters)
+                            }
+                        }
+                    },
+                    responses: {
+                        '200': {
+                            description: 'Successful response',
+                            content: {
+                                'application/json': {
+                                    schema: { type: 'object' }
+                                }
+                            }
+                        },
+                        '400': {
+                            description: 'Bad request - invalid parameters'
+                        },
+                        '401': {
+                            description: 'Authentication failed'
+                        },
+                        '500': {
+                            description: 'Internal server error'
+                        }
+                    }
+                }
+            };
+        }
+        // Add type schemas to components
+        for (const type of types) {
+            components.schemas[type.name] = this.convertTypeToJsonSchema(type);
+        }
+        return {
+            openapi: '3.0.3',
+            info: {
+                title: 'WordPress MCP Server API',
+                description: 'Model Context Protocol server for WordPress management',
+                version: '1.2.0',
+                contact: {
+                    name: 'MCP WordPress',
+                    url: 'https://github.com/docdyhr/mcp-wordpress'
+                },
+                license: {
+                    name: 'MIT',
+                    url: 'https://opensource.org/licenses/MIT'
+                }
+            },
+            paths,
+            components
+        };
+    }
+    /**
+     * Write all documentation files
+     */
+    async writeDocumentationFiles(output) {
+        const outputDir = this.config.outputDir;
+        // Ensure output directory exists
+        await fs.promises.mkdir(outputDir, { recursive: true });
+        await fs.promises.mkdir(path.join(outputDir, 'tools'), { recursive: true });
+        await fs.promises.mkdir(path.join(outputDir, 'types'), { recursive: true });
+        await fs.promises.mkdir(path.join(outputDir, 'examples'), { recursive: true });
+        await fs.promises.mkdir(path.join(outputDir, 'categories'), { recursive: true });
+        // Write main API documentation
+        await this.writeApiOverview(output);
+        // Write individual tool documentation
+        for (const tool of output.tools) {
+            await this.writeToolDocumentation(tool);
+        }
+        // Write category documentation
+        for (const category of output.categories) {
+            await this.writeCategoryDocumentation(category);
+        }
+        // Write type documentation
+        for (const type of output.types) {
+            await this.writeTypeDocumentation(type);
+        }
+        // Write OpenAPI specification
+        if (output.openApiSpec) {
+            await fs.promises.writeFile(path.join(outputDir, 'openapi.json'), JSON.stringify(output.openApiSpec, null, 2));
+        }
+        // Write summary
+        await fs.promises.writeFile(path.join(outputDir, 'summary.json'), JSON.stringify(output.summary, null, 2));
+        console.log(`📁 Documentation written to ${outputDir}/`);
+    }
+    // Helper methods for specific documentation tasks...
+    extractCategoryFromClassName(className) {
+        return className.replace('Tools', '').toLowerCase();
+    }
+    initializeWordPressMapping() {
+        // Map MCP tools to WordPress REST API endpoints
+        this.wordpressEndpoints.set('wp_list_posts', '/wp-json/wp/v2/posts');
+        this.wordpressEndpoints.set('wp_get_post', '/wp-json/wp/v2/posts/{id}');
+        this.wordpressEndpoints.set('wp_create_post', '/wp-json/wp/v2/posts');
+        this.wordpressEndpoints.set('wp_update_post', '/wp-json/wp/v2/posts/{id}');
+        this.wordpressEndpoints.set('wp_delete_post', '/wp-json/wp/v2/posts/{id}');
+        // Add more mappings...
+    }
+    initializeToolCategories() {
+        this.toolCategories.set('Posts', ['wp_list_posts', 'wp_get_post', 'wp_create_post', 'wp_update_post', 'wp_delete_post', 'wp_search_posts']);
+        this.toolCategories.set('Pages', ['wp_list_pages', 'wp_get_page', 'wp_create_page', 'wp_update_page', 'wp_delete_page', 'wp_search_pages']);
+        // Add more categories...
+    }
+    generateDocumentationSummary(tools, categories, types) {
+        return {
+            totalTools: tools.length,
+            totalCategories: categories.length,
+            totalTypes: types.length,
+            lastUpdated: new Date().toISOString(),
+            version: '1.2.0',
+            coverage: {
+                toolsWithExamples: tools.filter(t => t.examples.length > 0).length,
+                toolsWithWordPressMapping: tools.filter(t => t.wordpressEndpoint).length,
+                typesDocumented: types.length
+            }
+        };
+    }
+    /**
+     * Helper methods for documentation generation
+     */
+    getDefaultValue(param) {
+        const defaults = {
+            'per_page': 10,
+            'page': 1,
+            'order': 'desc',
+            'orderby': 'date',
+            'status': 'publish',
+            'format': 'summary',
+            'category': 'all',
+            'includeExamples': true,
+            'includeTrends': true
+        };
+        return defaults[param.name];
+    }
+    getAllowedValues(param) {
+        const allowedValues = {
+            'status': ['publish', 'draft', 'private', 'pending', 'future'],
+            'order': ['asc', 'desc'],
+            'orderby': ['date', 'title', 'author', 'modified'],
+            'format': ['summary', 'detailed', 'raw'],
+            'category': ['overview', 'requests', 'cache', 'system', 'tools', 'all'],
+            'timeframe': ['1h', '6h', '12h', '24h', '7d', '30d'],
+            'priority': ['quick_wins', 'medium_term', 'long_term', 'all'],
+            'focus': ['speed', 'reliability', 'efficiency', 'scaling']
+        };
+        return allowedValues[param.name];
+    }
+    generateParameterExamples(param) {
+        const examples = {
+            'id': ['123', '456'],
+            'title': ['My Blog Post', 'Hello World'],
+            'content': ['<p>Post content here</p>', 'This is my post content'],
+            'site': ['site1', 'production', 'staging'],
+            'per_page': ['10', '20', '50'],
+            'search': ['wordpress', 'tutorial'],
+            'author': ['1', '2'],
+            'email': ['user@example.com', 'admin@site.com'],
+            'username': ['john_doe', 'admin'],
+            'limit': ['10', '20', '50'],
+            'timeframe': ['24h', '7d', '1h']
+        };
+        return examples[param.name] || ['example'];
+    }
+    supportsMultiSite(toolDef) {
+        // All tools support multi-site via the site parameter
+        return toolDef.parameters?.some(p => p.name === 'site') ?? true;
+    }
+    generateExampleValue(param) {
+        const exampleValues = {
+            'id': 123,
+            'title': 'Example Post Title',
+            'content': 'This is example content for the post.',
+            'site': 'site1',
+            'per_page': 10,
+            'page': 1,
+            'search': 'wordpress',
+            'author': 1,
+            'email': 'user@example.com',
+            'username': 'john_doe',
+            'status': 'publish',
+            'order': 'desc',
+            'orderby': 'date',
+            'limit': 20,
+            'timeframe': '24h',
+            'format': 'summary',
+            'category': 'overview'
+        };
+        return exampleValues[param.name] || 'example_value';
+    }
+    generateExpectedResponse(toolName, category, type) {
+        if (toolName.includes('list')) {
+            return {
+                success: true,
+                data: [
+                    { id: 1, title: `Example ${category} 1`, status: 'publish' },
+                    { id: 2, title: `Example ${category} 2`, status: 'draft' }
+                ],
+                total: 2,
+                pages: 1
+            };
+        }
+        if (toolName.includes('get')) {
+            return {
+                success: true,
+                data: {
+                    id: 123,
+                    title: `Example ${category}`,
+                    content: 'Example content',
+                    status: 'publish',
+                    date: '2024-01-01T00:00:00Z'
+                }
+            };
+        }
+        if (toolName.includes('create') || toolName.includes('update')) {
+            return {
+                success: true,
+                data: {
+                    id: 123,
+                    title: 'Created/Updated successfully',
+                    status: 'publish'
+                }
+            };
+        }
+        if (toolName.includes('delete')) {
+            return {
+                success: true,
+                data: {
+                    deleted: true,
+                    id: 123
+                }
+            };
+        }
+        if (toolName.includes('performance')) {
+            return {
+                success: true,
+                data: {
+                    overview: {
+                        overallHealth: 'Good',
+                        performanceScore: 85,
+                        averageResponseTime: '245ms',
+                        cacheHitRate: '87.5%'
+                    }
+                }
+            };
+        }
+        return {
+            success: true,
+            data: {},
+            message: `${toolName} executed successfully`
+        };
+    }
+    getExampleParameters(toolDef, type) {
+        const params = {};
+        const parameters = toolDef.parameters || [];
+        if (type === 'all') {
+            // Include all parameters
+            for (const param of parameters) {
+                params[param.name] = this.generateExampleValue(param);
+            }
+        }
+        else if (typeof type === 'number') {
+            // Include limited number of parameters
+            for (const param of parameters.slice(0, type)) {
+                params[param.name] = this.generateExampleValue(param);
+            }
+        }
+        return params;
+    }
+    getCategoryDescription(categoryName) {
+        const descriptions = {
+            'posts': 'Blog post creation, editing, and management tools',
+            'pages': 'Static page creation and management tools',
+            'media': 'File upload, management, and media library tools',
+            'users': 'User account management and authentication tools',
+            'comments': 'Comment moderation and management tools',
+            'taxonomies': 'Category and tag management tools',
+            'site': 'Site settings and configuration tools',
+            'auth': 'Authentication testing and management tools',
+            'cache': 'Performance caching and optimization tools',
+            'performance': 'Performance monitoring and analytics tools'
+        };
+        return descriptions[categoryName.toLowerCase()] || `${categoryName} management tools`;
+    }
+    generateUsagePatterns(categoryName, tools) {
+        const patterns = {
+            'posts': [
+                'Create and publish blog posts',
+                'Bulk edit multiple posts',
+                'Search and filter posts by criteria',
+                'Schedule posts for future publication'
+            ],
+            'media': [
+                'Upload images and files',
+                'Organize media library',
+                'Generate thumbnails and variants',
+                'Bulk media operations'
+            ],
+            'users': [
+                'Manage user accounts and roles',
+                'User authentication and permissions',
+                'Bulk user operations',
+                'User profile management'
+            ],
+            'performance': [
+                'Monitor real-time performance metrics',
+                'Analyze historical performance trends',
+                'Generate optimization recommendations',
+                'Export performance reports'
+            ]
+        };
+        return patterns[categoryName.toLowerCase()] || [
+            `Manage ${categoryName.toLowerCase()} efficiently`,
+            `Bulk ${categoryName.toLowerCase()} operations`,
+            `Search and filter ${categoryName.toLowerCase()}`
+        ];
+    }
+    generateWordPressPostExample() {
+        return {
+            id: 123,
+            title: 'Welcome to WordPress',
+            content: '<p>This is your first post. Edit or delete it to get started!</p>',
+            status: 'publish',
+            date: '2024-01-01T00:00:00Z',
+            author: 1,
+            categories: [1],
+            tags: [1, 2],
+            featured_media: 0,
+            excerpt: 'A sample WordPress post',
+            slug: 'welcome-to-wordpress'
+        };
+    }
+    generateParameterSchema(parameters) {
+        const properties = {};
+        const required = [];
+        for (const param of parameters) {
+            properties[param.name] = {
+                type: param.type,
+                description: param.description
+            };
+            if (param.allowedValues) {
+                properties[param.name].enum = param.allowedValues;
+            }
+            if (param.defaultValue !== undefined) {
+                properties[param.name].default = param.defaultValue;
+            }
+            if (param.required) {
+                required.push(param.name);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined
+        };
+    }
+    convertTypeToJsonSchema(type) {
+        const properties = {};
+        const required = [];
+        for (const prop of type.properties) {
+            properties[prop.name] = {
+                type: prop.type,
+                description: prop.description
+            };
+            if (prop.format) {
+                properties[prop.name].format = prop.format;
+            }
+            if (prop.required) {
+                required.push(prop.name);
+            }
+        }
+        return {
+            type: 'object',
+            description: type.description,
+            properties,
+            required: required.length > 0 ? required : undefined
+        };
+    }
+    inferReturnType(toolName, category) {
+        if (toolName.includes('list'))
+            return `${category}[]`;
+        if (toolName.includes('get'))
+            return category;
+        if (toolName.includes('create'))
+            return category;
+        if (toolName.includes('update'))
+            return category;
+        if (toolName.includes('delete'))
+            return 'DeleteResult';
+        if (toolName.includes('search'))
+            return `${category}[]`;
+        if (toolName.includes('performance'))
+            return 'PerformanceMetrics';
+        if (toolName.includes('cache'))
+            return 'CacheStats';
+        return 'object';
+    }
+    generateErrorDocumentation(toolName) {
+        return [
+            {
+                code: 'AUTHENTICATION_FAILED',
+                message: 'Authentication failed',
+                description: 'Invalid credentials or insufficient permissions',
+                resolution: 'Check your authentication credentials and user permissions'
+            },
+            {
+                code: 'VALIDATION_ERROR',
+                message: 'Parameter validation failed',
+                description: 'One or more required parameters are missing or invalid',
+                resolution: 'Review the required parameters and their formats'
+            },
+            {
+                code: 'NOT_FOUND',
+                message: 'Resource not found',
+                description: 'The requested resource does not exist',
+                resolution: 'Verify the resource ID and ensure it exists'
+            },
+            {
+                code: 'PERMISSION_DENIED',
+                message: 'Insufficient permissions',
+                description: 'The user does not have permission to perform this action',
+                resolution: 'Contact an administrator to grant the necessary permissions'
+            }
+        ];
+    }
+    findRelatedTools(toolName, category) {
+        // Find tools in the same category
+        const categoryTools = this.toolCategories.get(category) || [];
+        return categoryTools.filter(tool => tool !== toolName).slice(0, 3);
+    }
+    getRequiredPermissions(toolName) {
+        const permissions = {
+            'wp_create_post': ['publish_posts', 'edit_posts'],
+            'wp_update_post': ['edit_posts'],
+            'wp_delete_post': ['delete_posts'],
+            'wp_create_page': ['publish_pages', 'edit_pages'],
+            'wp_update_page': ['edit_pages'],
+            'wp_delete_page': ['delete_pages'],
+            'wp_upload_media': ['upload_files'],
+            'wp_delete_media': ['delete_files'],
+            'wp_create_user': ['create_users'],
+            'wp_update_user': ['edit_users'],
+            'wp_delete_user': ['delete_users'],
+            'wp_moderate_comment': ['moderate_comments'],
+            'wp_get_site_settings': ['manage_options']
+        };
+        return permissions[toolName];
+    }
+    /**
+     * File writing implementations
+     */
+    async writeApiOverview(output) {
+        const { MarkdownFormatter } = await import('./MarkdownFormatter.js');
+        const formatter = new MarkdownFormatter();
+        const content = formatter.generateApiOverview(output);
+        await fs.promises.writeFile(path.join(this.config.outputDir, 'README.md'), content);
+    }
+    async writeToolDocumentation(tool) {
+        const { MarkdownFormatter } = await import('./MarkdownFormatter.js');
+        const formatter = new MarkdownFormatter();
+        const content = formatter.generateToolDocumentation(tool);
+        await fs.promises.writeFile(path.join(this.config.outputDir, 'tools', `${tool.name}.md`), content);
+    }
+    async writeCategoryDocumentation(category) {
+        const { MarkdownFormatter } = await import('./MarkdownFormatter.js');
+        const formatter = new MarkdownFormatter();
+        const content = formatter.generateCategoryDocumentation(category);
+        await fs.promises.writeFile(path.join(this.config.outputDir, 'categories', `${category.name.toLowerCase()}.md`), content);
+    }
+    async writeTypeDocumentation(type) {
+        const { MarkdownFormatter } = await import('./MarkdownFormatter.js');
+        const formatter = new MarkdownFormatter();
+        const content = formatter.generateTypeDocumentation(type);
+        await fs.promises.writeFile(path.join(this.config.outputDir, 'types', `${type.name}.md`), content);
+    }
+}
+//# sourceMappingURL=DocumentationGenerator.js.map