content-optimizer-mcp

Instructions

Implementation Reference

• mcp-server/src/index.ts:561-630 (handler)

  The handler function for the optimize_headings tool, which analyzes heading structures and generates improvement recommendations.

  async ({ content, keyword }) => {
    const headings = extractHeadings(content);
    const topics = getKeywordTopics(keyword);
    const keywordLower = keyword.toLowerCase();
  
    const issues: string[] = [];
    const h1s = headings.filter((h) => h.level === 1);
    const h2s = headings.filter((h) => h.level === 2);
    const h3s = headings.filter((h) => h.level === 3);
  
    if (h1s.length === 0) issues.push("Missing H1 heading.");
    if (h1s.length > 1) issues.push(`Multiple H1 headings found (${h1s.length}). Use only one.`);
    if (h1s.length > 0 && !h1s[0].text.toLowerCase().includes(keywordLower)) {
      issues.push("H1 does not contain the target keyword.");
    }
    if (h2s.length < 3) issues.push(`Only ${h2s.length} H2 headings. Aim for 3-8 for comprehensive structure.`);
    if (h2s.length > 0 && !h2s.some((h) => h.text.toLowerCase().includes(keywordLower))) {
      issues.push("No H2 heading contains the target keyword.");
    }
  
    // Check for heading hierarchy issues
    let prevLevel = 0;
    for (const h of headings) {
      if (h.level > prevLevel + 1 && prevLevel > 0) {
        issues.push(`Heading hierarchy skip: H${prevLevel} followed by H${h.level}. Don't skip levels.`);
        break;
      }
      prevLevel = h.level;
    }
  
    // Generate recommended headings
    const kwTitle = keyword.charAt(0).toUpperCase() + keyword.slice(1);
    const recommended: { level: number; text: string }[] = [
      { level: 1, text: `${kwTitle}: Complete Guide` },
    ];
  
    const topicSuggestions = topics.slice(0, 6);
    for (const topic of topicSuggestions) {
      const topicTitle = topic.charAt(0).toUpperCase() + topic.slice(1);
      recommended.push({ level: 2, text: `${kwTitle} ${topicTitle}` });
      if (topic.includes("best practices") || topic.includes("strategies") || topic.includes("tips")) {
        recommended.push({ level: 3, text: `Top ${topicTitle} for Beginners` });
        recommended.push({ level: 3, text: `Advanced ${topicTitle}` });
      }
    }
    recommended.push({ level: 2, text: "Conclusion" });
  
    // Suggest missing heading topics
    const existingTopics = headings.map((h) => h.text.toLowerCase());
    const missingSuggestions = topics
      .filter((t) => !existingTopics.some((et) => et.includes(t.toLowerCase())))
      .slice(0, 5)
      .map((t) => `H2: ${kwTitle} ${t.charAt(0).toUpperCase() + t.slice(1)}`);
  
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            currentHeadings: headings,
            headingCounts: { h1: h1s.length, h2: h2s.length, h3: h3s.length, total: headings.length },
            issues,
            recommendedOutline: recommended,
            missingSuggestions,
            keywordInH1: h1s.some((h) => h.text.toLowerCase().includes(keywordLower)),
            keywordInH2: h2s.some((h) => h.text.toLowerCase().includes(keywordLower)),
          }, null, 2),
        },
      ],
    };

• mcp-server/src/index.ts:557-560 (schema)

  Input schema for the optimize_headings tool.

  {
    content: z.string().describe("The content to analyze"),
    keyword: z.string().describe("The target keyword"),
  },

• mcp-server/src/index.ts:554-560 (registration)

  Registration of the optimize_headings tool.

  server.tool(
    "optimize_headings",
    "Analyze heading structure and suggest improvements. Returns current headings, issues, and recommended heading outline.",
    {
      content: z.string().describe("The content to analyze"),
      keyword: z.string().describe("The target keyword"),
    },