mcp-wordpress 2.6.3 → 2.7.0

package/src/tools/seo/SEOHandlers.ts

@@ -0,0 +1,296 @@
+/**
+ * SEO Tool Handlers
+ *
+ * Implements the handler functions for all SEO-related MCP tools.
+ * These handlers bridge the gap between MCP protocol requests and
+ * the SEO toolkit implementation.
+ *
+ * @since 2.7.0
+ */
+
+import { WordPressClient } from "@/client/api.js";
+import { SEOTools } from "./SEOTools.js";
+import { LoggerFactory } from "@/utils/logger.js";
+import type { SEOToolParams, SEOAnalysisType, SEOMetadata, SchemaType } from "@/types/seo.js";
+
+// Single instance of SEOTools to be reused
+let seoToolsInstance: SEOTools | null = null;
+
+/**
+ * Get or create SEOTools instance
+ */
+function getSEOToolsInstance(): SEOTools {
+  if (!seoToolsInstance) {
+    seoToolsInstance = new SEOTools();
+  }
+  return seoToolsInstance;
+}
+
+/**
+ * Handle content analysis request
+ */
+export async function handleAnalyzeContent(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_analyze_content");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      postId: args.postId as number,
+      analysisType: args.analysisType as SEOAnalysisType,
+      focusKeywords: args.focusKeywords as string[],
+      site: args.site as string,
+    };
+
+    return await seoTools.analyzeContent(params);
+  } catch (error) {
+    logger.error("Failed to analyze content", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle metadata generation request
+ */
+export async function handleGenerateMetadata(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_generate_metadata");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      postId: args.postId as number,
+      site: args.site as string,
+    };
+
+    // Add custom title/description if provided
+    if (args.title) {
+      params.title = args.title as string;
+    }
+    if (args.description) {
+      params.description = args.description as string;
+    }
+    if (args.focusKeyword) {
+      params.focusKeywords = [args.focusKeyword as string];
+    }
+
+    return await seoTools.generateMetadata(params);
+  } catch (error) {
+    logger.error("Failed to generate metadata", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle bulk metadata update request
+ */
+export async function handleBulkUpdateMetadata(
+  client: WordPressClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_bulk_update_metadata");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      postIds: args.postIds as number[],
+      updates: args.updates as Partial<SEOMetadata>,
+      dryRun: args.dryRun as boolean,
+      site: args.site as string,
+    };
+
+    return await seoTools.bulkUpdateMetadata(params);
+  } catch (error) {
+    logger.error("Failed to bulk update metadata", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle schema generation request
+ */
+export async function handleGenerateSchema(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_generate_schema");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      postId: args.postId as number,
+      schemaType: args.schemaType as SchemaType,
+      site: args.site as string,
+    };
+
+    // Add custom data if provided
+    if (args.customData) {
+      params.customData = args.customData;
+    }
+
+    return await seoTools.generateSchema(params);
+  } catch (error) {
+    logger.error("Failed to generate schema", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle schema validation request
+ */
+export async function handleValidateSchema(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_validate_schema");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      schema: args.schema,
+      schemaType: args.schemaType as SchemaType,
+      site: args.site as string,
+    };
+
+    // Add Google validator flag if provided
+    if (args.useGoogleValidator) {
+      params.useGoogleValidator = args.useGoogleValidator as boolean;
+    }
+
+    return await seoTools.validateSchema(params);
+  } catch (error) {
+    logger.error("Failed to validate schema", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle internal linking suggestions request
+ */
+export async function handleSuggestInternalLinks(
+  client: WordPressClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_suggest_internal_links");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      postId: args.postId as number,
+      site: args.site as string,
+    };
+
+    // Add optional parameters
+    if (args.maxSuggestions) {
+      params.maxSuggestions = args.maxSuggestions as number;
+    }
+    if (args.minimumRelevance) {
+      params.minimumRelevance = args.minimumRelevance as number;
+    }
+
+    return await seoTools.suggestInternalLinks(params);
+  } catch (error) {
+    logger.error("Failed to suggest internal links", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle site audit request
+ */
+export async function handlePerformSiteAudit(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_site_audit");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      auditType: args.auditType as "content" | "performance" | "full" | "technical",
+      force: args.force as boolean,
+      site: args.site as string,
+    };
+
+    // Add optional parameters
+    if (args.maxPages) {
+      params.maxPages = args.maxPages as number;
+    }
+    if (args.includeExternalLinks) {
+      params.includeExternalLinks = args.includeExternalLinks as boolean;
+    }
+
+    return await seoTools.performSiteAudit(params);
+  } catch (error) {
+    logger.error("Failed to perform site audit", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle SERP tracking request
+ */
+export async function handleTrackSERPPositions(
+  client: WordPressClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_track_serp");
+
+  try {
+    // This would need implementation in SEOTools
+    throw new Error("SERP tracking not yet implemented");
+  } catch (error) {
+    logger.error("Failed to track SERP positions", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle keyword research request
+ */
+export async function handleKeywordResearch(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_keyword_research");
+
+  try {
+    // This would need implementation in SEOTools
+    throw new Error("Keyword research not yet implemented");
+  } catch (error) {
+    logger.error("Failed to perform keyword research", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle SEO integration test request
+ */
+export async function handleTestSEOIntegration(
+  client: WordPressClient,
+  args: Record<string, unknown>,
+): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_test_integration");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      checkPlugins: args.checkPlugins as boolean,
+      testMetadataAccess: args.testMetadataAccess as boolean,
+      site: args.site as string,
+    };
+
+    return await seoTools.testSEOIntegration(params);
+  } catch (error) {
+    logger.error("Failed to test SEO integration", { error, args });
+    throw error;
+  }
+}
+
+/**
+ * Handle get live SEO data request
+ */
+export async function handleGetLiveSEOData(client: WordPressClient, args: Record<string, unknown>): Promise<unknown> {
+  const logger = LoggerFactory.tool("wp_seo_get_live_data");
+
+  try {
+    const seoTools = getSEOToolsInstance();
+    const params: SEOToolParams = {
+      postId: args.postId as number,
+      includeAnalysis: args.includeAnalysis as boolean,
+      includeRecommendations: args.includeRecommendations as boolean,
+      site: args.site as string,
+    };
+
+    return await seoTools.getLiveSEOData(params);
+  } catch (error) {
+    logger.error("Failed to get live SEO data", { error, args });
+    throw error;
+  }
+}

package/src/tools/seo/SEOToolDefinitions.ts

@@ -0,0 +1,402 @@
+/**
+ * SEO Tool Definitions for MCP Registration
+ *
+ * Defines all SEO-related tools with their schemas, descriptions,
+ * and handler functions for the Model Context Protocol.
+ *
+ * @since 2.7.0
+ */
+
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * Analyze content for SEO optimization opportunities
+ */
+export const analyzeContentTool: Tool = {
+  name: "wp_seo_analyze_content",
+  description:
+    "Analyze WordPress post content for SEO optimization opportunities including readability, keyword density, structure, and technical factors",
+  inputSchema: {
+    type: "object",
+    properties: {
+      postId: {
+        type: "number",
+        description: "WordPress post ID to analyze",
+      },
+      analysisType: {
+        type: "string",
+        enum: ["readability", "keywords", "structure", "full"],
+        description: "Type of SEO analysis to perform (default: full)",
+      },
+      focusKeywords: {
+        type: "array",
+        items: { type: "string" },
+        description: "Primary keywords to analyze for optimization",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["postId"],
+  },
+};
+
+/**
+ * Generate optimized metadata for posts
+ */
+export const generateMetadataTool: Tool = {
+  name: "wp_seo_generate_metadata",
+  description:
+    "Generate SEO-optimized metadata including title tags, meta descriptions, OpenGraph, and Twitter Card data",
+  inputSchema: {
+    type: "object",
+    properties: {
+      postId: {
+        type: "number",
+        description: "WordPress post ID",
+      },
+      title: {
+        type: "string",
+        description: "Custom title to optimize (optional, uses post title if not provided)",
+      },
+      description: {
+        type: "string",
+        description: "Custom description to optimize (optional, uses excerpt if not provided)",
+      },
+      focusKeyword: {
+        type: "string",
+        description: "Primary keyword to include in metadata",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["postId"],
+  },
+};
+
+/**
+ * Bulk update metadata for multiple posts
+ */
+export const bulkUpdateMetadataTool: Tool = {
+  name: "wp_seo_bulk_update_metadata",
+  description: "Update SEO metadata for multiple posts with progress tracking and error handling",
+  inputSchema: {
+    type: "object",
+    properties: {
+      postIds: {
+        type: "array",
+        items: { type: "number" },
+        description: "Array of WordPress post IDs to update",
+      },
+      updates: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          description: { type: "string" },
+          focusKeyword: { type: "string" },
+          canonical: { type: "string" },
+        },
+        description: "Metadata fields to update for all posts",
+      },
+      dryRun: {
+        type: "boolean",
+        description: "Perform a dry run without making actual changes",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["postIds", "updates"],
+  },
+};
+
+/**
+ * Generate structured data schema markup
+ */
+export const generateSchemaTool: Tool = {
+  name: "wp_seo_generate_schema",
+  description: "Generate JSON-LD structured data schema for enhanced search results",
+  inputSchema: {
+    type: "object",
+    properties: {
+      postId: {
+        type: "number",
+        description: "WordPress post ID",
+      },
+      schemaType: {
+        type: "string",
+        enum: [
+          "Article",
+          "Product",
+          "FAQ",
+          "HowTo",
+          "Organization",
+          "Website",
+          "BreadcrumbList",
+          "Event",
+          "Recipe",
+          "Course",
+          "LocalBusiness",
+          "Person",
+          "Review",
+          "VideoObject",
+        ],
+        description: "Type of schema.org structured data to generate",
+      },
+      customData: {
+        type: "object",
+        description: "Additional custom data for the schema",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["postId", "schemaType"],
+  },
+};
+
+/**
+ * Validate schema markup
+ */
+export const validateSchemaTool: Tool = {
+  name: "wp_seo_validate_schema",
+  description: "Validate JSON-LD schema markup for correctness and compliance",
+  inputSchema: {
+    type: "object",
+    properties: {
+      schema: {
+        type: "object",
+        description: "JSON-LD schema object to validate",
+      },
+      schemaType: {
+        type: "string",
+        description: "Expected schema type for validation",
+      },
+      useGoogleValidator: {
+        type: "boolean",
+        description: "Use Google's Rich Results Test API for validation",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["schema"],
+  },
+};
+
+/**
+ * Suggest internal linking opportunities
+ */
+export const suggestInternalLinksTool: Tool = {
+  name: "wp_seo_suggest_internal_links",
+  description: "Analyze content and suggest relevant internal linking opportunities for better SEO",
+  inputSchema: {
+    type: "object",
+    properties: {
+      postId: {
+        type: "number",
+        description: "WordPress post ID to analyze for linking opportunities",
+      },
+      maxSuggestions: {
+        type: "number",
+        description: "Maximum number of link suggestions (default: 5)",
+      },
+      minimumRelevance: {
+        type: "number",
+        description: "Minimum relevance score (0-100) for suggestions",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["postId"],
+  },
+};
+
+/**
+ * Perform comprehensive site audit
+ */
+export const performSiteAuditTool: Tool = {
+  name: "wp_seo_site_audit",
+  description:
+    "Perform comprehensive SEO audit of the WordPress site including technical, content, and performance analysis",
+  inputSchema: {
+    type: "object",
+    properties: {
+      auditType: {
+        type: "string",
+        enum: ["technical", "content", "performance", "full"],
+        description: "Type of audit to perform (default: full)",
+      },
+      maxPages: {
+        type: "number",
+        description: "Maximum number of pages to audit (default: 100)",
+      },
+      includeExternalLinks: {
+        type: "boolean",
+        description: "Include external link validation in audit",
+      },
+      force: {
+        type: "boolean",
+        description: "Force refresh, bypassing cached audit results",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * Track SERP positions
+ */
+export const trackSERPPositionsTool: Tool = {
+  name: "wp_seo_track_serp",
+  description: "Track search engine result page positions for target keywords",
+  inputSchema: {
+    type: "object",
+    properties: {
+      keywords: {
+        type: "array",
+        items: { type: "string" },
+        description: "Keywords to track positions for",
+      },
+      url: {
+        type: "string",
+        description: "Specific URL to track (optional, uses site home if not provided)",
+      },
+      searchEngine: {
+        type: "string",
+        enum: ["google", "bing", "yahoo"],
+        description: "Search engine to track positions on",
+      },
+      location: {
+        type: "string",
+        description: "Geographic location for localized results",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["keywords"],
+  },
+};
+
+/**
+ * Keyword research and suggestions
+ */
+export const keywordResearchTool: Tool = {
+  name: "wp_seo_keyword_research",
+  description: "Research keywords and get suggestions based on topic and competition analysis",
+  inputSchema: {
+    type: "object",
+    properties: {
+      seedKeyword: {
+        type: "string",
+        description: "Seed keyword or topic to research",
+      },
+      includeVariations: {
+        type: "boolean",
+        description: "Include keyword variations and long-tail keywords",
+      },
+      includeQuestions: {
+        type: "boolean",
+        description: "Include question-based keywords",
+      },
+      maxResults: {
+        type: "number",
+        description: "Maximum number of keyword suggestions",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["seedKeyword"],
+  },
+};
+
+/**
+ * Test SEO integration with WordPress
+ */
+export const testSEOIntegrationTool: Tool = {
+  name: "wp_seo_test_integration",
+  description: "Test SEO plugin integration and detect available SEO plugins on the WordPress site",
+  inputSchema: {
+    type: "object",
+    properties: {
+      checkPlugins: {
+        type: "boolean",
+        description: "Check which SEO plugins are installed and active",
+      },
+      testMetadataAccess: {
+        type: "boolean",
+        description: "Test ability to read/write SEO metadata",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: [],
+  },
+};
+
+/**
+ * Get live SEO data from WordPress
+ */
+export const getLiveSEODataTool: Tool = {
+  name: "wp_seo_get_live_data",
+  description: "Retrieve live SEO data from WordPress including plugin-specific metadata and configurations",
+  inputSchema: {
+    type: "object",
+    properties: {
+      postId: {
+        type: "number",
+        description: "WordPress post ID to get SEO data for",
+      },
+      includeAnalysis: {
+        type: "boolean",
+        description: "Include SEO analysis of the live data",
+      },
+      includeRecommendations: {
+        type: "boolean",
+        description: "Include optimization recommendations",
+      },
+      site: {
+        type: "string",
+        description: "Site identifier for multi-site setups",
+      },
+    },
+    required: ["postId"],
+  },
+};
+
+/**
+ * Export all SEO tool definitions
+ */
+export const seoToolDefinitions: Tool[] = [
+  analyzeContentTool,
+  generateMetadataTool,
+  bulkUpdateMetadataTool,
+  generateSchemaTool,
+  validateSchemaTool,
+  suggestInternalLinksTool,
+  performSiteAuditTool,
+  trackSERPPositionsTool,
+  keywordResearchTool,
+  testSEOIntegrationTool,
+  getLiveSEODataTool,
+];
+
+export default seoToolDefinitions;