MCP WordPress Server

/** * 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 type { ToolDefinition } from "@/server/ToolRegistry.js"; import { LoggerFactory } from "@/utils/logger.js"; export interface DocumentationConfig { outputDir: string; includeExamples: boolean; includeWordPressMapping: boolean; generateOpenAPI: boolean; generateInteractiveHtml: boolean; validateExamples: boolean; } export interface ToolDocumentation { name: string; category: string; description: string; parameters: ParameterDocumentation[]; examples: ExampleUsage[]; wordpressEndpoint: string | undefined; requiredPermissions: string[] | undefined; returnType: string; errorCodes: ErrorDocumentation[]; relatedTools: string[]; } export interface ParameterDocumentation { name: string; type: string; required: boolean; description: string; defaultValue: unknown; allowedValues: string[] | undefined; examples: string[]; } export interface ExampleUsage { title: string; description: string; command: string; parameters: Record<string, unknown>; expectedResponse: unknown; errorExample?: { scenario: string; error: unknown; }; } export interface ErrorDocumentation { code: string; message: string; description: string; resolution: string; } export interface DocumentationOutput { tools: ToolDocumentation[]; categories: CategoryDocumentation[]; types: TypeDocumentation[]; openApiSpec: OpenAPISpecification | undefined; summary: DocumentationSummary; } export interface CategoryDocumentation { name: string; description: string; toolCount: number; tools: string[]; usagePatterns: string[]; } export interface TypeDocumentation { name: string; description: string; properties: PropertyDocumentation[]; examples: unknown[]; wordpressSource?: string; } export interface PropertyDocumentation { name: string; type: string; required: boolean; description: string; format?: string; } export interface OpenAPISpecification { openapi: string; info: Record<string, unknown>; paths: Record<string, unknown>; components: Record<string, unknown>; } export interface DocumentationSummary { totalTools: number; totalCategories: number; totalTypes: number; lastUpdated: string; version: string; coverage: { toolsWithExamples: number; toolsWithWordPressMapping: number; typesDocumented: number; }; } /** * Main Documentation Generator */ export class DocumentationGenerator { private config: DocumentationConfig; private toolCategories: Map<string, string[]> = new Map(); private wordpressEndpoints: Map<string, string> = new Map(); private logger = LoggerFactory.api(); constructor(config: Partial<DocumentationConfig> = {}) { 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(): Promise<DocumentationOutput> { this.logger.info("🚀 Starting API documentation generation..."); const tools = await this.extractAllToolDocumentation(); const categories = this.generateCategoryDocumentation(tools); const types = await this.extractTypeDocumentation(); let openApiSpec: OpenAPISpecification | undefined = undefined; if (this.config.generateOpenAPI) { openApiSpec = this.generateOpenAPISpecification(tools, types); } const summary = this.generateDocumentationSummary(tools, categories, types); const output: DocumentationOutput = { 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 */ private async extractAllToolDocumentation(): Promise<ToolDocumentation[]> { const toolDocs: ToolDocumentation[] = []; // Iterate through all tool classes for (const [className, ToolClass] of Object.entries(Tools)) { try { // Create tool instance let toolInstance: { getTools(): unknown[] }; 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 as new () => { getTools(): unknown[] })(); } const toolDefinitions = toolInstance.getTools(); const category = this.extractCategoryFromClassName(className); for (const toolDef of toolDefinitions) { const doc = await this.extractToolDocumentation(toolDef as ToolDefinition, 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 */ private async extractToolDocumentation( toolDef: ToolDefinition, category: string, className: string, ): Promise<ToolDocumentation> { 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 */ private extractParameterDocumentation( parameters: Array<{ name: string; type?: string; description?: string; required?: boolean; [key: string]: unknown; }>, ): ParameterDocumentation[] { 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 */ private generateToolExamples(toolDef: ToolDefinition, category: string): ExampleUsage[] { const examples: ExampleUsage[] = []; // 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 */ private generateBasicExample(toolDef: ToolDefinition, category: string): ExampleUsage | null { const toolName = toolDef.name; const basicParams: Record<string, unknown> = {}; // 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 */ private generateMultiSiteExample(toolDef: ToolDefinition, category: string): ExampleUsage | null { 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 */ private generateAdvancedExample(toolDef: ToolDefinition, category: string): ExampleUsage | null { 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 */ private generateCategoryDocumentation(tools: ToolDocumentation[]): CategoryDocumentation[] { const categories = new Map<string, ToolDocumentation[]>(); // 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 */ private async extractTypeDocumentation(): Promise<TypeDocumentation[]> { // 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 */ private generateOpenAPISpecification(tools: ToolDocumentation[], types: TypeDocumentation[]): OpenAPISpecification { const paths: Record<string, unknown> = {}; const components: Record<string, unknown> = { 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 as Record<string, unknown>; 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 */ private async writeDocumentationFiles(output: DocumentationOutput): Promise<void> { 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... private extractCategoryFromClassName(className: string): string { return className.replace("Tools", "").toLowerCase(); } private initializeWordPressMapping(): void { // 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... } private initializeToolCategories(): void { 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... } private generateDocumentationSummary( tools: ToolDocumentation[], categories: CategoryDocumentation[], types: TypeDocumentation[], ): DocumentationSummary { 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 */ private getDefaultValue(param: { [key: string]: unknown }): unknown { const defaults: Record<string, unknown> = { per_page: 10, page: 1, order: "desc", orderby: "date", status: "publish", format: "summary", category: "all", includeExamples: true, includeTrends: true, }; return defaults[String(param.name)]; } private getAllowedValues(param: { [key: string]: unknown }): string[] | undefined { const allowedValues: Record<string, string[]> = { 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)]; } private generateParameterExamples(param: { name: string; type?: string; [key: string]: unknown }): string[] { const examples: Record<string, string[]> = { 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"]; } private supportsMultiSite(toolDef: ToolDefinition): boolean { // All tools support multi-site via the site parameter return toolDef.parameters?.some((p) => p.name === "site") ?? true; } private generateExampleValue(param: { name: string; type?: string; [key: string]: unknown }): unknown { const exampleValues: Record<string, unknown> = { 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"; } private generateExpectedResponse(toolName: string, category: string, type: string): unknown { 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`, }; } private getExampleParameters(toolDef: ToolDefinition, type: string | number): Record<string, unknown> { const params: Record<string, unknown> = {}; 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; } private getCategoryDescription(categoryName: string): string { const descriptions: Record<string, string> = { 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`; } private generateUsagePatterns(categoryName: string, tools: ToolDocumentation[]): string[] { const patterns: Record<string, string[]> = { 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()}`, ] ); } private generateWordPressPostExample(): Record<string, unknown> { 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", }; } private generateParameterSchema(parameters: ParameterDocumentation[]): Record<string, unknown> { const properties: Record<string, unknown> = {}; const required: string[] = []; for (const param of parameters) { properties[param.name] = { type: param.type, description: param.description, }; if (param.allowedValues) { (properties[param.name] as Record<string, unknown>).enum = param.allowedValues; } if (param.defaultValue !== undefined) { (properties[param.name] as Record<string, unknown>).default = param.defaultValue; } if (param.required) { required.push(param.name); } } return { type: "object", properties, required: required.length > 0 ? required : undefined, }; } private convertTypeToJsonSchema(type: TypeDocumentation): Record<string, unknown> { const properties: Record<string, unknown> = {}; const required: string[] = []; for (const prop of type.properties) { properties[prop.name] = { type: prop.type, description: prop.description, }; if (prop.format) { (properties[prop.name] as Record<string, unknown>).format = prop.format; } if (prop.required) { required.push(prop.name); } } return { type: "object", description: type.description, properties, required: required.length > 0 ? required : undefined, }; } private inferReturnType(toolName: string, category: string): string { 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"; } private generateErrorDocumentation(toolName: string): ErrorDocumentation[] { 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", }, ]; } private findRelatedTools(toolName: string, category: string): string[] { // Find tools in the same category const categoryTools = this.toolCategories.get(category) || []; return categoryTools.filter((tool) => tool !== toolName).slice(0, 3); } private getRequiredPermissions(toolName: string): string[] | undefined { const permissions: Record<string, string[]> = { 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 */ private async writeApiOverview(output: DocumentationOutput): Promise<void> { 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); } private async writeToolDocumentation(tool: ToolDocumentation): Promise<void> { 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); } private async writeCategoryDocumentation(category: CategoryDocumentation): Promise<void> { 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, ); } private async writeTypeDocumentation(type: TypeDocumentation): Promise<void> { 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); } }