@respira/wordpress-mcp-server 1.4.0

package/dist/server.js

@@ -0,0 +1,729 @@
+/**
+ * Respira WordPress MCP Server
+ *
+ * Provides tools for AI coding assistants to interact with WordPress sites
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { WordPressClient } from './wordpress-client.js';
+export class RespiraWordPressServer {
+    server;
+    currentSite = null;
+    sites = new Map();
+    constructor(siteConfigs) {
+        this.server = new Server({
+            name: 'respira-wordpress',
+            version: '1.0.0',
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        // Initialize WordPress clients for each site
+        siteConfigs.forEach((config) => {
+            const client = new WordPressClient(config);
+            this.sites.set(config.id, client);
+            // Set default site
+            if (config.default || this.currentSite === null) {
+                this.currentSite = client;
+            }
+        });
+        this.setupHandlers();
+    }
+    setupHandlers() {
+        // List available tools
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => {
+            return {
+                tools: this.getTools(),
+            };
+        });
+        // Handle tool calls
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            if (!this.currentSite) {
+                throw new Error('No WordPress site configured');
+            }
+            try {
+                const result = await this.handleToolCall(name, args || {});
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const errorMessage = error?.message || error?.toString() || String(error) || 'Unknown error';
+                const errorStack = error?.stack ? `\n\nStack trace:\n${error.stack}` : '';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: ${errorMessage}${errorStack}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+    }
+    getTools() {
+        return [
+            {
+                name: 'wordpress_get_site_context',
+                description: 'Get comprehensive information about the WordPress site including version, theme, plugins, custom post types, and page builder.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'wordpress_get_theme_docs',
+                description: 'Get theme documentation and available template files.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'wordpress_get_builder_info',
+                description: 'Get information about the active page builder including available modules/widgets.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'wordpress_list_pages',
+                description: 'List all pages with optional filtering.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: {
+                            type: 'string',
+                            description: 'Filter by status (publish, draft, pending)',
+                        },
+                        search: {
+                            type: 'string',
+                            description: 'Search term',
+                        },
+                        page: {
+                            type: 'number',
+                            description: 'Page number for pagination',
+                        },
+                        perPage: {
+                            type: 'number',
+                            description: 'Number of items per page',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'wordpress_read_page',
+                description: 'Get full content of a specific page including meta data and builder information.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Page ID',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'wordpress_create_page_duplicate',
+                description: 'Create a duplicate of an existing page for safe editing. IMPORTANT: Always use this before making changes to an original page. After creating a duplicate, edit the duplicate using wordpress_update_page. The user must then approve the duplicate in WordPress admin (Respira → Page Approvals) to replace the original page.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        originalId: {
+                            type: 'number',
+                            description: 'ID of the original page to duplicate',
+                        },
+                        suffix: {
+                            type: 'string',
+                            description: 'Optional suffix for the duplicated page title',
+                        },
+                    },
+                    required: ['originalId'],
+                },
+            },
+            {
+                name: 'wordpress_update_page',
+                description: 'Update a page. ⚠️ SAFETY: Respira ALWAYS creates duplicates automatically before editing live pages. If you try to edit an original page, Respira will automatically create a duplicate and edit that instead. After editing, the user must approve the duplicate in WordPress admin (Respira → Approve Edits) to replace the original. The force parameter requires 3 separate confirmations and only works if "Allow Direct Editing" is enabled in Respira settings (disabled by default for safety).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Page ID (Respira automatically creates a duplicate if editing an original page)',
+                        },
+                        title: {
+                            type: 'string',
+                            description: 'New page title',
+                        },
+                        content: {
+                            type: 'string',
+                            description: 'New page content (HTML)',
+                        },
+                        status: {
+                            type: 'string',
+                            description: 'Page status (publish, draft, pending)',
+                        },
+                        meta: {
+                            type: 'object',
+                            description: 'Post meta data',
+                        },
+                        force: {
+                            type: 'boolean',
+                            description: '⚠️ DANGEROUS: Force direct edit of live page (requires 3 confirmations and "Allow Direct Editing" enabled). NOT RECOMMENDED - duplicates are created automatically for safety.',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'wordpress_delete_page',
+                description: 'Delete a page. IMPORTANT: By default, this only works on Respira-created duplicates. The force parameter only works if "Allow Direct Editing" is enabled in Respira settings (disabled by default for safety).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Page ID',
+                        },
+                        force: {
+                            type: 'boolean',
+                            description: 'Force delete even if not a duplicate',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'wordpress_list_posts',
+                description: 'List all blog posts with optional filtering.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        status: {
+                            type: 'string',
+                            description: 'Filter by status',
+                        },
+                        search: {
+                            type: 'string',
+                            description: 'Search term',
+                        },
+                        page: {
+                            type: 'number',
+                            description: 'Page number',
+                        },
+                        perPage: {
+                            type: 'number',
+                            description: 'Items per page',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'wordpress_read_post',
+                description: 'Get full content of a specific post.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Post ID',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'wordpress_create_post_duplicate',
+                description: 'Create a duplicate of an existing post for safe editing. IMPORTANT: Always use this before making changes to an original post. After creating a duplicate, edit the duplicate using wordpress_update_post. The user must then approve the duplicate in WordPress admin (Respira → Page Approvals) to replace the original post.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        originalId: {
+                            type: 'number',
+                            description: 'Original post ID',
+                        },
+                        suffix: {
+                            type: 'string',
+                            description: 'Optional suffix',
+                        },
+                    },
+                    required: ['originalId'],
+                },
+            },
+            {
+                name: 'wordpress_update_post',
+                description: 'Update a post. ⚠️ SAFETY: Respira ALWAYS creates duplicates automatically before editing live posts. If you try to edit an original post, Respira will automatically create a duplicate and edit that instead. After editing, the user must approve the duplicate in WordPress admin (Respira → Approve Edits) to replace the original. The force parameter requires 3 separate confirmations and only works if "Allow Direct Editing" is enabled in Respira settings (disabled by default for safety).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Post ID (Respira automatically creates a duplicate if editing an original post)',
+                        },
+                        title: {
+                            type: 'string',
+                            description: 'New post title',
+                        },
+                        content: {
+                            type: 'string',
+                            description: 'New post content (HTML)',
+                        },
+                        status: {
+                            type: 'string',
+                            description: 'Post status (publish, draft, pending)',
+                        },
+                        meta: {
+                            type: 'object',
+                            description: 'Post meta data',
+                        },
+                        force: {
+                            type: 'boolean',
+                            description: '⚠️ DANGEROUS: Force direct edit of live post (requires 3 confirmations and "Allow Direct Editing" enabled). NOT RECOMMENDED - duplicates are created automatically for safety.',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'wordpress_delete_post',
+                description: 'Delete a post. IMPORTANT: By default, this only works on Respira-created duplicates. The force parameter only works if "Allow Direct Editing" is enabled in Respira settings (disabled by default for safety).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: {
+                            type: 'number',
+                            description: 'Post ID',
+                        },
+                        force: {
+                            type: 'boolean',
+                            description: 'Force delete even if not a duplicate',
+                        },
+                    },
+                    required: ['id'],
+                },
+            },
+            {
+                name: 'wordpress_list_media',
+                description: 'List all media files (images, videos, etc.).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        search: {
+                            type: 'string',
+                            description: 'Search term',
+                        },
+                        page: {
+                            type: 'number',
+                            description: 'Page number',
+                        },
+                        perPage: {
+                            type: 'number',
+                            description: 'Items per page',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'wordpress_extract_builder_content',
+                description: 'Extract structured content from a page builder (Divi, Elementor, etc.).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        builder: {
+                            type: 'string',
+                            description: 'Builder name (gutenberg, divi, elementor, etc.)',
+                        },
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID',
+                        },
+                    },
+                    required: ['builder', 'pageId'],
+                },
+            },
+            {
+                name: 'wordpress_inject_builder_content',
+                description: 'Inject structured content into a page builder.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        builder: {
+                            type: 'string',
+                            description: 'Builder name',
+                        },
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID',
+                        },
+                        content: {
+                            type: 'object',
+                            description: 'Structured content to inject',
+                        },
+                    },
+                    required: ['builder', 'pageId', 'content'],
+                },
+            },
+            {
+                name: 'wordpress_validate_security',
+                description: 'Validate content for security issues before saving.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        content: {
+                            type: 'string',
+                            description: 'Content to validate',
+                        },
+                    },
+                    required: ['content'],
+                },
+            },
+            {
+                name: 'wordpress_switch_site',
+                description: 'Switch to a different WordPress site (for multi-site setups).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        siteId: {
+                            type: 'string',
+                            description: 'Site ID from configuration',
+                        },
+                    },
+                    required: ['siteId'],
+                },
+            },
+            // Page Speed Analysis tools
+            {
+                name: 'wordpress_analyze_performance',
+                description: 'Analyze page performance metrics including load time, image optimization, CSS/JS optimization, caching, and plugin performance impact.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            {
+                name: 'wordpress_get_core_web_vitals',
+                description: 'Get Core Web Vitals metrics (LCP, FID, CLS) for a page.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            {
+                name: 'wordpress_analyze_images',
+                description: 'Analyze image optimization opportunities including missing alt text, large files, and unoptimized formats.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            // SEO Analysis tools
+            {
+                name: 'wordpress_analyze_seo',
+                description: 'Comprehensive SEO analysis including meta tags, heading structure, image alt text, internal linking, content quality, and schema markup.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            {
+                name: 'wordpress_check_seo_issues',
+                description: 'Check for common SEO issues and get quick recommendations.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            {
+                name: 'wordpress_analyze_readability',
+                description: 'Analyze content readability including Flesch Reading Ease score, sentence length, and paragraph structure.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            // AEO (AI Engine Optimization) tools
+            {
+                name: 'wordpress_analyze_aeo',
+                description: 'Analyze content for AI Engine Optimization (optimizing for AI search engines like Perplexity, ChatGPT). Checks structured data, content clarity, semantic HTML, entities, content depth, and FAQ opportunities.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            {
+                name: 'wordpress_check_structured_data',
+                description: 'Check schema markup and structured data (JSON-LD, microdata) for AI parsing.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pageId: {
+                            type: 'number',
+                            description: 'Page ID to analyze',
+                        },
+                    },
+                    required: ['pageId'],
+                },
+            },
+            // Plugin Management tools (EXPERIMENTAL)
+            {
+                name: 'wordpress_list_plugins',
+                description: 'EXPERIMENTAL: List all installed plugins with their status, version, and update availability. Requires plugin management to be enabled in Respira settings.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'wordpress_install_plugin',
+                description: 'EXPERIMENTAL: Install a plugin from WordPress.org or a ZIP URL. Requires plugin management to be enabled in Respira settings. Use with caution.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slugOrUrl: {
+                            type: 'string',
+                            description: 'Plugin slug (from WordPress.org) or ZIP file URL',
+                        },
+                        source: {
+                            type: 'string',
+                            description: 'Source type: "wordpress.org" or "url"',
+                            enum: ['wordpress.org', 'url'],
+                        },
+                    },
+                    required: ['slugOrUrl'],
+                },
+            },
+            {
+                name: 'wordpress_activate_plugin',
+                description: 'EXPERIMENTAL: Activate a plugin. Requires plugin management to be enabled in Respira settings. Monitor the site after activation.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slug: {
+                            type: 'string',
+                            description: 'Plugin slug',
+                        },
+                    },
+                    required: ['slug'],
+                },
+            },
+            {
+                name: 'wordpress_deactivate_plugin',
+                description: 'EXPERIMENTAL: Deactivate a plugin. Requires plugin management to be enabled in Respira settings.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slug: {
+                            type: 'string',
+                            description: 'Plugin slug',
+                        },
+                    },
+                    required: ['slug'],
+                },
+            },
+            {
+                name: 'wordpress_update_plugin',
+                description: 'EXPERIMENTAL: Update a plugin to the latest version. Requires plugin management to be enabled in Respira settings. Make sure you have backups before updating.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slug: {
+                            type: 'string',
+                            description: 'Plugin slug',
+                        },
+                    },
+                    required: ['slug'],
+                },
+            },
+            {
+                name: 'wordpress_delete_plugin',
+                description: 'EXPERIMENTAL: Permanently delete a plugin. Requires plugin management to be enabled in Respira settings. The plugin must be deactivated first.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        slug: {
+                            type: 'string',
+                            description: 'Plugin slug',
+                        },
+                    },
+                    required: ['slug'],
+                },
+            },
+        ];
+    }
+    async handleToolCall(name, args) {
+        if (!this.currentSite) {
+            throw new Error('No WordPress site configured');
+        }
+        switch (name) {
+            case 'wordpress_get_site_context':
+                return this.currentSite.getSiteContext();
+            case 'wordpress_get_theme_docs':
+                return this.currentSite.getThemeDocs();
+            case 'wordpress_get_builder_info':
+                return this.currentSite.getBuilderInfo();
+            case 'wordpress_list_pages':
+                return this.currentSite.listPages(args);
+            case 'wordpress_read_page':
+                return this.currentSite.getPage(args.id);
+            case 'wordpress_create_page_duplicate':
+                return this.currentSite.duplicatePage(args.originalId, args.suffix);
+            case 'wordpress_update_page': {
+                const page = await this.currentSite.updatePage(args.id, args);
+                // Check if Respira created a duplicate
+                if (page.__respira_duplicate_info) {
+                    const info = page.__respira_duplicate_info;
+                    return {
+                        ...page,
+                        respira_message: info.message,
+                        respira_instructions: info.instructions,
+                        duplicate_created: true,
+                        duplicate_id: info.duplicate_id,
+                        original_id: info.original_id,
+                        approval_url: info.approval_url,
+                    };
+                }
+                return page;
+            }
+            case 'wordpress_delete_page':
+                return this.currentSite.deletePage(args.id, args.force);
+            case 'wordpress_list_posts':
+                return this.currentSite.listPosts(args);
+            case 'wordpress_read_post':
+                return this.currentSite.getPost(args.id);
+            case 'wordpress_create_post_duplicate':
+                return this.currentSite.duplicatePost(args.originalId, args.suffix);
+            case 'wordpress_update_post': {
+                const post = await this.currentSite.updatePost(args.id, args);
+                // Check if Respira created a duplicate
+                if (post.__respira_duplicate_info) {
+                    const info = post.__respira_duplicate_info;
+                    return {
+                        ...post,
+                        respira_message: info.message,
+                        respira_instructions: info.instructions,
+                        duplicate_created: true,
+                        duplicate_id: info.duplicate_id,
+                        original_id: info.original_id,
+                        approval_url: info.approval_url,
+                    };
+                }
+                return post;
+            }
+            case 'wordpress_delete_post':
+                return this.currentSite.deletePost(args.id, args.force);
+            case 'wordpress_list_media':
+                return this.currentSite.listMedia(args);
+            case 'wordpress_extract_builder_content':
+                return this.currentSite.extractBuilderContent(args.builder, args.pageId);
+            case 'wordpress_inject_builder_content':
+                return this.currentSite.injectBuilderContent(args.builder, args.pageId, args.content);
+            case 'wordpress_validate_security':
+                return this.currentSite.validateSecurity(args.content);
+            case 'wordpress_switch_site':
+                const newSite = this.sites.get(args.siteId);
+                if (!newSite) {
+                    throw new Error(`Site with ID "${args.siteId}" not found in configuration`);
+                }
+                this.currentSite = newSite;
+                return {
+                    success: true,
+                    message: `Switched to site: ${newSite.getSiteName()}`,
+                    url: newSite.getSiteUrl(),
+                };
+            // Page Speed Analysis
+            case 'wordpress_analyze_performance':
+                return this.currentSite.analyzePerformance(args.pageId);
+            case 'wordpress_get_core_web_vitals':
+                return this.currentSite.getCoreWebVitals(args.pageId);
+            case 'wordpress_analyze_images':
+                return this.currentSite.analyzeImages(args.pageId);
+            // SEO Analysis
+            case 'wordpress_analyze_seo':
+                return this.currentSite.analyzeSEO(args.pageId);
+            case 'wordpress_check_seo_issues':
+                return this.currentSite.checkSEOIssues(args.pageId);
+            case 'wordpress_analyze_readability':
+                return this.currentSite.analyzeReadability(args.pageId);
+            // AEO Analysis
+            case 'wordpress_analyze_aeo':
+                return this.currentSite.analyzeAEO(args.pageId);
+            case 'wordpress_check_structured_data':
+                return this.currentSite.checkStructuredData(args.pageId);
+            // Plugin Management (EXPERIMENTAL)
+            case 'wordpress_list_plugins':
+                return this.currentSite.listPlugins();
+            case 'wordpress_install_plugin':
+                return this.currentSite.installPlugin(args.slugOrUrl, args.source || 'wordpress.org');
+            case 'wordpress_activate_plugin':
+                return this.currentSite.activatePlugin(args.slug);
+            case 'wordpress_deactivate_plugin':
+                return this.currentSite.deactivatePlugin(args.slug);
+            case 'wordpress_update_plugin':
+                return this.currentSite.updatePlugin(args.slug);
+            case 'wordpress_delete_plugin':
+                return this.currentSite.deletePlugin(args.slug);
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Respira WordPress MCP Server running on stdio');
+    }
+}
+//# sourceMappingURL=server.js.map