mcp-wordpress 2.6.3 → 2.7.0

package/dist/client/SEOWordPressClient.js

@@ -0,0 +1,674 @@
+/**
+ * SEO WordPress Client
+ *
+ * Extended WordPress REST API client with enhanced SEO capabilities.
+ * Provides specialized methods for SEO metadata management, schema markup,
+ * and integration with popular WordPress SEO plugins like Yoast and RankMath.
+ *
+ * Features:
+ * - SEO metadata retrieval and updates via REST API
+ * - Integration with Yoast SEO and RankMath plugin APIs
+ * - Schema markup management through WordPress custom fields
+ * - Bulk SEO operations with progress tracking
+ * - SEO-specific data normalization and validation
+ * - Plugin-agnostic metadata handling
+ *
+ * @since 2.7.0
+ */
+import { WordPressClient } from "./api.js";
+import { LoggerFactory } from "../utils/logger.js";
+import { handleToolError } from "../utils/error.js";
+/**
+ * Extended WordPress client with SEO capabilities
+ */
+export class SEOWordPressClient extends WordPressClient {
+    logger = LoggerFactory.tool("seo_client");
+    detectedPlugin = "none";
+    pluginFields;
+    constructor(config) {
+        super(config);
+        // Define field mappings for different SEO plugins
+        this.pluginFields = {
+            yoast: {
+                title: "_yoast_wpseo_title",
+                description: "_yoast_wpseo_metadesc",
+                focusKeyword: "_yoast_wpseo_focuskw",
+                canonical: "_yoast_wpseo_canonical",
+                noindex: "_yoast_wpseo_meta-robots-noindex",
+                nofollow: "_yoast_wpseo_meta-robots-nofollow",
+                schema: "_yoast_wpseo_schema_page_type",
+            },
+            rankmath: {
+                title: "rank_math_title",
+                description: "rank_math_description",
+                focusKeyword: "rank_math_focus_keyword",
+                canonical: "rank_math_canonical_url",
+                robots: "rank_math_robots",
+                schema: "rank_math_rich_snippet",
+            },
+            seopress: {
+                title: "_seopress_titles_title",
+                description: "_seopress_titles_desc",
+                targetKeyword: "_seopress_analysis_target_kw",
+                canonical: "_seopress_robots_canonical",
+                robots: "_seopress_robots_index",
+            },
+            none: {
+                title: "meta_title",
+                description: "meta_description",
+                focusKeyword: "focus_keyword",
+                canonical: "canonical_url",
+                noindex: "robots_noindex",
+                nofollow: "robots_nofollow",
+                schema: "schema_markup",
+            },
+        };
+    }
+    /**
+     * Initialize and detect SEO plugins
+     */
+    async initializeSEO() {
+        this.logger.debug("Initializing SEO client and detecting plugins");
+        try {
+            // Detect active SEO plugins
+            await this.detectSEOPlugins();
+            this.logger.info("SEO client initialized", {
+                detectedPlugin: this.detectedPlugin,
+            });
+        }
+        catch (_error) {
+            this.logger.warn("SEO plugin detection failed, using generic approach", {
+                _error: _error instanceof Error ? _error.message : String(_error),
+            });
+        }
+    }
+    /**
+     * Detect active SEO plugins on the WordPress site
+     */
+    async detectSEOPlugins() {
+        try {
+            // Get list of installed plugins
+            const plugins = await this.get("/wp/v2/plugins");
+            if (!Array.isArray(plugins)) {
+                this.logger.debug("Could not retrieve plugins list");
+                return;
+            }
+            // Check for active SEO plugins in order of preference
+            const activePlugins = plugins.filter((plugin) => plugin.status === "active");
+            // Check for Yoast SEO
+            if (activePlugins.some((plugin) => plugin.slug === "wordpress-seo")) {
+                this.detectedPlugin = "yoast";
+                return;
+            }
+            // Check for RankMath
+            if (activePlugins.some((plugin) => plugin.slug === "seo-by-rank-math")) {
+                this.detectedPlugin = "rankmath";
+                return;
+            }
+            // Check for SEOPress
+            if (activePlugins.some((plugin) => plugin.slug === "wp-seopress")) {
+                this.detectedPlugin = "seopress";
+                return;
+            }
+            this.logger.debug("No SEO plugins detected, using generic metadata approach");
+        }
+        catch (_error) {
+            this.logger.error("Plugin detection failed", {
+                _error: _error instanceof Error ? _error.message : String(_error),
+            });
+        }
+    }
+    /**
+     * Get SEO metadata for a post or page
+     */
+    async getSEOMetadata(postId, type = "post") {
+        this.logger.debug("Fetching SEO metadata", { postId, type, plugin: this.detectedPlugin });
+        try {
+            // Get the post/page with meta fields
+            const content = type === "post"
+                ? await this.getPost(postId, "edit") // edit context includes meta
+                : await this.getPage(postId, "edit");
+            if (!content) {
+                throw new Error(`${type} with ID ${postId} not found`);
+            }
+            // Extract SEO metadata based on detected plugin
+            const metadata = this.extractSEOMetadata(content);
+            // Extract schema markup if available
+            const schema = this.extractSchemaMarkup(content);
+            // Get raw plugin data for debugging
+            const raw = this.getRawPluginData(content);
+            // For malformed plugin data (detected plugin but no actual data), return null for title/description
+            const pluginDetected = this.detectedPlugin !== "none";
+            const pluginDataMalformed = pluginDetected && !this.hasPluginData(content);
+            return {
+                postId: postId,
+                plugin: this.detectedPlugin,
+                title: pluginDataMalformed ? null : metadata.title,
+                description: pluginDataMalformed ? null : metadata.description,
+                canonical: metadata.canonical || null,
+                focusKeyword: metadata.focusKeyword || null,
+                openGraph: metadata.openGraph || { title: null, description: null },
+                twitter: metadata.twitterCard ? {
+                    title: metadata.twitterCard.title || null,
+                    description: metadata.twitterCard.description || null
+                } : { title: null, description: null },
+                schema,
+                raw,
+                lastModified: content.modified || content.date || new Date().toISOString(),
+            };
+        }
+        catch (_error) {
+            handleToolError(_error, "get SEO metadata", { postId, type });
+            throw _error;
+        }
+    }
+    /**
+     * Update SEO metadata for a post or page
+     */
+    async updateSEOMetadata(postId, metadata, type = "post") {
+        this.logger.debug("Updating SEO metadata", { postId, type, plugin: this.detectedPlugin });
+        try {
+            // Check if SEO plugin is available
+            if (this.detectedPlugin === "none") {
+                return {
+                    success: false,
+                    message: "No SEO plugin detected. Cannot update SEO metadata.",
+                    postId,
+                    plugin: this.detectedPlugin,
+                    title: null,
+                    description: null,
+                    focusKeyword: null,
+                    canonical: null,
+                    openGraph: { title: null, description: null },
+                    twitter: { title: null, description: null },
+                    schema: undefined,
+                    raw: {},
+                    lastModified: new Date().toISOString(),
+                };
+            }
+            // Prepare meta fields based on detected plugin
+            const metaFields = this.prepareSEOMetaFields(metadata);
+            // Update the post/page with new meta fields
+            const updateData = {
+                id: postId,
+                meta: metaFields,
+            };
+            const _updatedContent = type === "post" ? await this.updatePost(updateData) : await this.updatePage(updateData);
+            // Return updated SEO data
+            return await this.getSEOMetadata(postId, type);
+        }
+        catch (_error) {
+            handleToolError(_error, "update SEO metadata", { postId, type });
+            throw _error;
+        }
+    }
+    /**
+     * Bulk get SEO metadata for multiple posts
+     */
+    async bulkGetSEOMetadata(params) {
+        this.logger.info("Starting bulk SEO metadata retrieval", {
+            postCount: params.postIds.length,
+            batchSize: params.batchSize || 10,
+        });
+        const results = [];
+        const batchSize = params.batchSize || 10;
+        const total = params.postIds.length;
+        // Process in batches
+        for (let i = 0; i < params.postIds.length; i += batchSize) {
+            const batch = params.postIds.slice(i, i + batchSize);
+            const batchPromises = batch.map(async (postId) => {
+                try {
+                    return await this.getSEOMetadata(postId);
+                }
+                catch (_error) {
+                    this.logger.warn("Failed to get SEO metadata for post", {
+                        postId,
+                        _error: _error instanceof Error ? _error.message : String(_error),
+                    });
+                    return null;
+                }
+            });
+            const batchResults = await Promise.all(batchPromises);
+            results.push(...batchResults.filter((r) => r !== null));
+            // Report progress
+            const processed = Math.min(i + batchSize, total);
+            if (params.progressCallback) {
+                params.progressCallback(processed, total);
+            }
+            // Small delay between batches to avoid overwhelming the server
+            if (i + batchSize < params.postIds.length) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        }
+        this.logger.info("Bulk SEO metadata retrieval completed", {
+            requested: total,
+            successful: results.length,
+            failed: total - results.length,
+        });
+        return results;
+    }
+    /**
+     * Bulk update SEO metadata for multiple posts
+     */
+    async bulkUpdateSEOMetadata(params) {
+        this.logger.info("Starting bulk SEO metadata update", {
+            postCount: params.postIds.length,
+            batchSize: params.batchSize || 5, // Smaller batches for updates
+        });
+        const results = [];
+        const batchSize = params.batchSize || 5;
+        const total = params.postIds.length;
+        // Process in smaller batches for updates
+        for (let i = 0; i < params.postIds.length; i += batchSize) {
+            const batch = params.postIds.slice(i, i + batchSize);
+            const batchPromises = batch.map(async (postId) => {
+                try {
+                    return await this.updateSEOMetadata(postId, params.metadata);
+                }
+                catch (_error) {
+                    this.logger.warn("Failed to update SEO metadata for post", {
+                        postId,
+                        _error: _error instanceof Error ? _error.message : String(_error),
+                    });
+                    return null;
+                }
+            });
+            const batchResults = await Promise.all(batchPromises);
+            results.push(...batchResults.filter((r) => r !== null));
+            // Report progress
+            const processed = Math.min(i + batchSize, total);
+            if (params.progressCallback) {
+                params.progressCallback(processed, total);
+            }
+            // Longer delay between update batches
+            if (i + batchSize < params.postIds.length) {
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+        }
+        this.logger.info("Bulk SEO metadata update completed", {
+            requested: total,
+            successful: results.length,
+            failed: total - results.length,
+        });
+        return results;
+    }
+    /**
+     * Get all posts with SEO metadata for site audit
+     */
+    async getAllPostsWithSEO(params = {}) {
+        this.logger.debug("Fetching all posts with SEO data for audit", params);
+        const maxPosts = params.maxPosts || 100;
+        const results = [];
+        try {
+            // Get posts
+            const posts = await this.getPosts({
+                per_page: maxPosts,
+                status: ["publish"],
+                context: "edit", // Include meta fields
+            });
+            // Get pages if requested
+            let pages = [];
+            if (params.includePages) {
+                pages = await this.getPages({
+                    per_page: Math.max(20, Math.floor(maxPosts / 5)), // 20% allocation for pages
+                    status: ["publish"],
+                    context: "edit",
+                });
+            }
+            // Process posts
+            for (const post of posts || []) {
+                try {
+                    const seoData = await this.getSEOMetadata(post.id, "post");
+                    results.push({ ...post, seoData });
+                }
+                catch (_error) {
+                    // Include post without SEO data if metadata fetch fails
+                    results.push(post);
+                    this.logger.debug("Failed to get SEO data for post", { postId: post.id });
+                }
+            }
+            // Process pages
+            for (const page of pages) {
+                try {
+                    const seoData = await this.getSEOMetadata(page.id, "page");
+                    results.push({ ...page, seoData });
+                }
+                catch (_error) {
+                    // Include page without SEO data if metadata fetch fails
+                    results.push(page);
+                    this.logger.debug("Failed to get SEO data for page", { pageId: page.id });
+                }
+            }
+            this.logger.info("Retrieved posts with SEO data", {
+                totalPosts: posts?.length || 0,
+                totalPages: pages.length,
+                withSEOData: results.filter((r) => r.seoData).length,
+            });
+            return results;
+        }
+        catch (_error) {
+            handleToolError(_error, "get all posts with SEO data", params);
+            throw _error;
+        }
+    }
+    /**
+     * Extract SEO metadata from WordPress post/page object
+     */
+    extractSEOMetadata(content) {
+        const meta = (Array.isArray(content.meta) ? {} : content.meta || {});
+        const fields = this.pluginFields[this.detectedPlugin];
+        // Extract basic metadata with plugin-specific field handling
+        const focusKeyword = this.getPluginFocusKeyword(meta, fields);
+        const canonical = this.extractMetaValue(meta, fields?.canonical);
+        const metadata = {
+            title: this.extractMetaValue(meta, fields?.title) || content.title?.rendered || "",
+            description: this.extractMetaValue(meta, fields?.description) || content.excerpt?.rendered || "",
+            ...(focusKeyword && { focusKeyword }),
+            ...(canonical && { canonical }),
+        };
+        // Extract robots directives based on plugin
+        if (this.detectedPlugin === "yoast" && "noindex" in fields && "nofollow" in fields) {
+            metadata.robots = {
+                index: this.extractMetaValue(meta, fields.noindex) !== "1",
+                follow: this.extractMetaValue(meta, fields.nofollow) !== "1",
+            };
+        }
+        else if (this.detectedPlugin === "rankmath" && "robots" in fields) {
+            const robotsValue = this.extractMetaValue(meta, fields.robots) || "";
+            metadata.robots = {
+                index: !robotsValue.includes("noindex"),
+                follow: !robotsValue.includes("nofollow"),
+            };
+        }
+        // Extract OpenGraph and Twitter data based on plugin
+        if (this.detectedPlugin === "yoast" && meta.yoast_head_json) {
+            const yoastData = meta.yoast_head_json;
+            metadata.openGraph = {
+                title: yoastData.og_title || metadata.title,
+                description: yoastData.og_description || metadata.description,
+                type: content.type === "page" ? "website" : "article",
+                url: content.link,
+            };
+            const twitterTitle = yoastData.twitter_title;
+            const twitterDescription = yoastData.twitter_description;
+            metadata.twitterCard = {
+                card: "summary",
+                ...(twitterTitle && { title: twitterTitle }),
+                ...(twitterDescription && { description: twitterDescription }),
+            };
+        }
+        else {
+            // Default OpenGraph data
+            metadata.openGraph = {
+                title: metadata.title,
+                description: metadata.description,
+                type: content.type === "page" ? "website" : "article",
+                url: content.link,
+            };
+        }
+        return metadata;
+    }
+    /**
+     * Extract schema markup from post meta
+     */
+    extractSchemaMarkup(content) {
+        const meta = (Array.isArray(content.meta) ? {} : content.meta || {});
+        const fields = this.pluginFields[this.detectedPlugin];
+        const schemaData = this.getPluginSchemaData(meta, fields);
+        if (!schemaData) {
+            return undefined;
+        }
+        try {
+            // Try to parse JSON-LD schema
+            if (typeof schemaData === "string" && schemaData.startsWith("{")) {
+                return JSON.parse(schemaData);
+            }
+            // Handle Yoast schema page types
+            if (this.detectedPlugin === "yoast" && schemaData) {
+                return {
+                    "@context": "https://schema.org",
+                    "@type": schemaData,
+                };
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Prepare meta fields for SEO metadata update
+     */
+    prepareSEOMetaFields(metadata) {
+        const fields = this.pluginFields[this.detectedPlugin];
+        const metaFields = {};
+        // Map metadata to plugin-specific fields
+        if (metadata.title && fields?.title) {
+            metaFields[fields.title] = metadata.title;
+        }
+        if (metadata.description && fields?.description) {
+            metaFields[fields.description] = metadata.description;
+        }
+        if (metadata.focusKeyword) {
+            const focusKeywordField = this.getPluginFocusKeywordField(fields);
+            if (focusKeywordField) {
+                metaFields[focusKeywordField] = metadata.focusKeyword;
+            }
+        }
+        if (metadata.canonical && fields?.canonical) {
+            metaFields[fields.canonical] = metadata.canonical;
+        }
+        // Handle robots directives
+        if (metadata.robots && this.detectedPlugin === "yoast" && "noindex" in fields && "nofollow" in fields) {
+            if (fields.noindex) {
+                metaFields[fields.noindex] = metadata.robots.index ? "0" : "1";
+            }
+            if (fields.nofollow) {
+                metaFields[fields.nofollow] = metadata.robots.follow ? "0" : "1";
+            }
+        }
+        else if (metadata.robots && this.detectedPlugin === "rankmath" && "robots" in fields) {
+            const robotsArray = [];
+            if (!metadata.robots.index)
+                robotsArray.push("noindex");
+            if (!metadata.robots.follow)
+                robotsArray.push("nofollow");
+            metaFields[fields.robots] = robotsArray.join(",");
+        }
+        return metaFields;
+    }
+    /**
+     * Extract meta value with array handling
+     */
+    extractMetaValue(meta, fieldName) {
+        if (!fieldName) {
+            return null;
+        }
+        // For Yoast, check yoast_head_json first
+        if (this.detectedPlugin === "yoast" && meta.yoast_head_json) {
+            const yoastData = meta.yoast_head_json;
+            // Map field names to yoast_head_json properties
+            const yoastFieldMap = {
+                '_yoast_wpseo_title': 'title',
+                '_yoast_wpseo_metadesc': 'description',
+                '_yoast_wpseo_canonical': 'canonical',
+                '_yoast_wpseo_focuskw': 'focuskw'
+            };
+            const yoastField = yoastFieldMap[fieldName];
+            if (yoastField && yoastData[yoastField]) {
+                return yoastData[yoastField];
+            }
+        }
+        // Fallback to direct meta field lookup
+        if (!meta[fieldName]) {
+            return null;
+        }
+        const value = meta[fieldName];
+        // WordPress meta values can be arrays
+        if (Array.isArray(value)) {
+            return value[0] || null;
+        }
+        return value || null;
+    }
+    /**
+     * Get plugin-specific focus keyword field
+     */
+    getPluginFocusKeyword(meta, fields) {
+        if (this.detectedPlugin === "seopress" && "targetKeyword" in fields) {
+            return this.extractMetaValue(meta, fields.targetKeyword) || undefined;
+        }
+        else if ("focusKeyword" in fields) {
+            return this.extractMetaValue(meta, fields.focusKeyword) || undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Get plugin-specific schema data field
+     */
+    getPluginSchemaData(meta, fields) {
+        if ("schema" in fields) {
+            return this.extractMetaValue(meta, fields.schema) || undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Get plugin-specific focus keyword field name
+     */
+    getPluginFocusKeywordField(fields) {
+        if (this.detectedPlugin === "seopress" && "targetKeyword" in fields) {
+            return fields.targetKeyword;
+        }
+        else if ("focusKeyword" in fields) {
+            return fields.focusKeyword;
+        }
+        return undefined;
+    }
+    /**
+     * Test SEO plugin integration
+     */
+    async testSEOIntegration() {
+        this.logger.info("Testing SEO integration");
+        const result = {
+            pluginDetected: this.detectedPlugin,
+            canReadMetadata: false,
+            canWriteMetadata: false,
+            samplePostsWithSEO: 0,
+            errors: [],
+        };
+        try {
+            // Test reading metadata from recent posts
+            const testPosts = await this.getPosts({ per_page: 5, status: ["publish"] });
+            if (testPosts && testPosts.length > 0) {
+                let postsWithSEO = 0;
+                for (const post of testPosts) {
+                    try {
+                        const seoData = await this.getSEOMetadata(post.id);
+                        if (seoData.title || seoData.description) {
+                            postsWithSEO++;
+                        }
+                    }
+                    catch (_error) {
+                        result.errors?.push(`Failed to read SEO data for post ${post.id}: ${_error.message}`);
+                    }
+                }
+                result.samplePostsWithSEO = postsWithSEO;
+                result.canReadMetadata = true;
+            }
+            // Test writing metadata (if we have posts to test with)
+            if (testPosts && testPosts.length > 0 && result.canReadMetadata) {
+                try {
+                    const testPost = testPosts[0];
+                    const originalSEO = await this.getSEOMetadata(testPost.id);
+                    // Make a small test update
+                    const testMetadata = {
+                        description: (originalSEO.description || "") + " [TEST]",
+                    };
+                    await this.updateSEOMetadata(testPost.id, testMetadata);
+                    // Restore original data
+                    await this.updateSEOMetadata(testPost.id, {
+                        description: originalSEO.description || "",
+                    });
+                    result.canWriteMetadata = true;
+                }
+                catch (_error) {
+                    result.errors?.push(`Failed to write SEO data: ${_error.message}`);
+                }
+            }
+            this.logger.info("SEO integration test completed", result);
+            return result;
+        }
+        catch (_error) {
+            result.errors?.push(`SEO integration test failed: ${_error.message}`);
+            return result;
+        }
+    }
+    /**
+     * Get integration status for SEO features
+     */
+    getIntegrationStatus() {
+        const hasPlugin = this.detectedPlugin !== "none";
+        return {
+            hasPlugin,
+            plugin: this.detectedPlugin,
+            canReadMetadata: hasPlugin,
+            canWriteMetadata: hasPlugin,
+            features: {
+                metaTags: hasPlugin,
+                schema: hasPlugin,
+                socialMedia: hasPlugin,
+                xmlSitemap: false, // Would need additional API calls
+                breadcrumbs: false,
+            },
+        };
+    }
+    /**
+     * Check if content has plugin-specific SEO data
+     */
+    hasPluginData(content) {
+        const meta = (Array.isArray(content.meta) ? {} : content.meta || {});
+        switch (this.detectedPlugin) {
+            case "yoast":
+                // Check for yoast_head_json or individual meta fields
+                return (meta.yoast_head_json !== null && meta.yoast_head_json !== undefined) ||
+                    (meta._yoast_wpseo_title !== null && meta._yoast_wpseo_title !== undefined);
+            case "rankmath":
+                return meta.rank_math_title !== null && meta.rank_math_title !== undefined;
+            case "seopress":
+                return meta._seopress_titles_title !== null && meta._seopress_titles_title !== undefined;
+            default:
+                return false;
+        }
+    }
+    /**
+     * Get raw plugin data for debugging purposes
+     */
+    getRawPluginData(content) {
+        const meta = (Array.isArray(content.meta) ? {} : content.meta || {});
+        // Return the raw plugin-specific data based on detected plugin
+        switch (this.detectedPlugin) {
+            case "yoast":
+                return meta.yoast_head_json || {};
+            case "rankmath":
+                // Extract RankMath specific fields
+                const rankMathData = {};
+                Object.keys(meta).forEach(key => {
+                    if (key.startsWith('rank_math_')) {
+                        rankMathData[key] = meta[key];
+                    }
+                });
+                return rankMathData;
+            case "seopress":
+                // Extract SEOPress specific fields
+                const seopressData = {};
+                Object.keys(meta).forEach(key => {
+                    if (key.startsWith('_seopress_')) {
+                        seopressData[key] = meta[key];
+                    }
+                });
+                return seopressData;
+            default:
+                return {};
+        }
+    }
+}
+//# sourceMappingURL=SEOWordPressClient.js.map