wp_seo_suggest_internal_links

Instructions

Implementation Reference

• src/tools/seo/SEOHandlers.ts:162-188 (handler)

  MCP handler function for the wp_seo_suggest_internal_links tool. Processes input arguments, constructs parameters, and delegates to SEOTools.suggestInternalLinks.

  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;
    }
  }

• src/tools/seo/optimizers/InternalLinkingSuggester.ts:157-211 (helper)

  Core implementation of internal linking suggestion generation, including content analysis, candidate post selection, relevance scoring, filtering, ranking, and contextual placement enhancement.

  async generateSuggestions(sourcePost: WordPressPost, params: SEOToolParams): Promise<InternalLinkSuggestion[]> {
    this.logger.debug("Generating internal linking suggestions", {
      postId: sourcePost.id,
      title: sourcePost.title?.rendered?.substring(0, 50),
      maxSuggestions: this.config.maxSuggestions,
    });
  
    try {
      // Analyze source post content
      const sourceAnalysis = await this.analyzePostContent(sourcePost);
  
      // Get candidate posts for linking
      const candidatePosts = await this.getCandidatePosts(sourcePost, params);
  
      // Analyze candidate posts
      const candidateAnalyses = await Promise.all(candidatePosts.map((post) => this.analyzePostContent(post)));
  
      // Calculate relevance scores
      const scoredSuggestions = this.calculateRelevanceScores(
        sourcePost,
        sourceAnalysis,
        candidatePosts,
        candidateAnalyses,
      );
  
      // Filter and rank suggestions
      const filteredSuggestions = scoredSuggestions
        .filter((suggestion) => suggestion.relevance >= this.config.minRelevanceScore)
        .sort((a, b) => b.relevance - a.relevance)
        .slice(0, this.config.maxSuggestions);
  
      // Add contextual placement information
      const enhancedSuggestions = await Promise.all(
        filteredSuggestions.map((suggestion) => this.enhanceWithContextualPlacement(sourcePost, suggestion)),
      );
  
      this.logger.info("Generated internal linking suggestions", {
        sourcePostId: sourcePost.id,
        candidatesAnalyzed: candidatePosts.length,
        suggestionsFound: enhancedSuggestions.length,
        avgRelevanceScore:
          enhancedSuggestions.length > 0
            ? (enhancedSuggestions.reduce((sum, s) => sum + s.relevance, 0) / enhancedSuggestions.length).toFixed(1)
            : 0,
      });
  
      return enhancedSuggestions;
    } catch (_error) {
      this.logger.error("Failed to generate internal linking suggestions", {
        postId: sourcePost.id,
        _error: _error instanceof Error ? _error.message : String(_error),
      });
      throw _error;
    }
  }

• src/tools/seo/SEOToolDefinitions.ts:196-221 (schema)

  Tool schema definition for wp_seo_suggest_internal_links, including input schema with postId (required), maxSuggestions, minimumRelevance, and site.

  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"],
    },
  };

• src/tools/seo/SEOTools.ts:378-399 (registration)

  Tool handler registration mapping in SEOTools.getHandlerForTool method, where 'wp_seo_suggest_internal_links' is mapped to the handleSuggestInternalLinks function. Used by getTools() for MCP registration.

  private getHandlerForTool(toolName: string): unknown {
    const handlers: Record<string, unknown> = {
      wp_seo_analyze_content: handleAnalyzeContent,
      wp_seo_generate_metadata: handleGenerateMetadata,
      wp_seo_bulk_update_metadata: handleBulkUpdateMetadata,
      wp_seo_generate_schema: handleGenerateSchema,
      wp_seo_validate_schema: handleValidateSchema,
      wp_seo_suggest_internal_links: handleSuggestInternalLinks,
      wp_seo_site_audit: handlePerformSiteAudit,
      wp_seo_track_serp: handleTrackSERPPositions,
      wp_seo_keyword_research: handleKeywordResearch,
      wp_seo_test_integration: handleTestSEOIntegration,
      wp_seo_get_live_data: handleGetLiveSEOData,
    };
  
    return (
      handlers[toolName] ||
      (() => {
        throw new Error(`Unknown SEO tool: ${toolName}`);
      })
    );
  }