mcp-wordpress 2.4.2 → 2.5.1

package/dist/src/docs/DocumentationGenerator.js

@@ -0,0 +1,777 @@
+/**
+ * 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";
+import { LoggerFactory } from "../utils/logger.js";
+/**
+ * Main Documentation Generator
+ */
+export class DocumentationGenerator {
+    config;
+    toolCategories = new Map();
+    wordpressEndpoints = new Map();
+    logger = LoggerFactory.api();
+    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() {
+        this.logger.info("🚀 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);
+        this.logger.info(`✅ 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) {
+                this.logger.warn(`⚠️ Failed to extract documentation for ${className}:`, { error: String(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
+        const schemas = components.schemas;
+        for (const type of types) {
+            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));
+        this.logger.info(`📁 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[String(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[String(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