@adsim/wordpress-mcp-server 4.6.0 → 5.3.1

package/src/tools/editorial.js

@@ -0,0 +1,634 @@
+// src/tools/editorial.js — editorial tools (6)
+// Definitions + handlers (v5.0.0 refactor Step B+C)
+
+import { json, strip } from '../shared/utils.js';
+import { rt } from '../shared/context.js';
+
+export const definitions = [
+  { name: 'wp_suggest_content_updates', _category: 'editorial', description: 'Use to find stale posts that need updating. Prioritizes by age, date mentions in content (e.g. "en 2023"), and low word count. Returns actionable update recommendations. Read-only.',
+        inputSchema: { type: 'object', properties: { months: { type: 'number', description: 'default 6' }, post_types: { type: 'array', items: { type: 'string' }, description: 'Post types to scan (default ["post"])' }, per_page: { type: 'number', description: 'default 50' }, min_word_count: { type: 'number', description: 'default 100' } }}},
+  { name: 'wp_audit_author_consistency', _category: 'editorial', description: 'Use to profile each active author: post count, avg word count, publication frequency, readability score (Flesch-Kincaid), media usage. Returns per-author profiles and deviations vs site average. Read-only.',
+        inputSchema: { type: 'object', properties: { post_types: { type: 'array', items: { type: 'string' }, description: 'Post types (default ["post"])' }, min_posts: { type: 'number', description: 'default 3' }, per_page: { type: 'number', description: 'default 100' } }}},
+  { name: 'wp_build_editorial_calendar', _category: 'editorial', description: 'Use to generate a recommended editorial calendar. Analyzes 12 months of publication history for seasonality, crosses with scheduled posts, and suggests optimal publishing slots. Read-only.',
+        inputSchema: { type: 'object', properties: { months_ahead: { type: 'number', description: 'default 3' }, post_types: { type: 'array', items: { type: 'string' }, description: 'Post types (default ["post"])' } }}},
+  { name: 'wp_find_pillar_content_gaps', _category: 'editorial', description: 'Use to identify topics covered by 3+ secondary posts without a dedicated pillar page. Analyzes categories and tags to detect content cluster opportunities. Read-only.',
+        inputSchema: { type: 'object', properties: { min_cluster_size: { type: 'number', description: 'Min posts per topic to qualify (default 3)' }, min_word_count_pillar: { type: 'number', description: 'Min word count to consider as pillar (default 1500)' }, post_types: { type: 'array', items: { type: 'string' }, description: 'Post types (default ["post","page"])' } }}},
+  { name: 'wp_audit_internal_link_equity', _category: 'editorial', description: 'Use to build the internal link graph and identify orphan pages (0 inbound), over-linked pages (>20 inbound), and important content with low link equity. Batch-optimized for large sites. Read-only.',
+        inputSchema: { type: 'object', properties: { post_types: { type: 'array', items: { type: 'string' }, description: 'Post types (default ["post","page"])' }, batch_size: { type: 'number', description: 'default 50, max 100' }, max_posts: { type: 'number', description: 'default 500' } }}},
+  { name: 'wp_suggest_content_cluster', _category: 'editorial', description: 'Use to cluster existing content by semantic similarity using TF-IDF + cosine similarity. Accepts a topic keyword or post_id as seed, returns related clusters with recommended pillar posts. Batch-optimized. Read-only.',
+        inputSchema: { type: 'object', properties: { topic: { type: 'string', description: 'Keyword to seed the cluster' }, post_id: { type: 'number', description: 'Post ID to use as cluster seed (alternative to topic)' }, similarity_threshold: { type: 'number', description: 'default 0.15' }, post_types: { type: 'array', items: { type: 'string' }, description: 'Post types (default ["post","page"])' }, max_posts: { type: 'number', description: 'default 200' } }}}
+];
+
+export const handlers = {};
+
+handlers['wp_suggest_content_updates'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name, countWords } = rt;
+  const staleMonths = args.months || 6;
+  const staleTypes = args.post_types || ['post'];
+  const stalePerPage = Math.min(args.per_page || 50, 100);
+  const staleMinWords = args.min_word_count || 100;
+  const cutoffDate = new Date();
+  cutoffDate.setMonth(cutoffDate.getMonth() - staleMonths);
+  const cutoffISO = cutoffDate.toISOString();
+
+  let allPosts = [];
+  for (const pt of staleTypes) {
+    try {
+      const posts = await wpApiCall(`/${pt === 'post' ? 'posts' : pt === 'page' ? 'pages' : pt}?per_page=${stalePerPage}&status=publish&before=${cutoffISO}&orderby=modified&order=asc`);
+      if (Array.isArray(posts)) allPosts.push(...posts);
+    } catch (_e) { /* skip inaccessible type */ }
+  }
+
+  // Score and prioritize
+  const yearPattern = /\b(20[0-2]\d)\b/g;
+  const datePatterns = /\b(en|depuis|avant|après|janvier|février|mars|avril|mai|juin|juillet|août|septembre|octobre|novembre|décembre|january|february|march|april|may|june|july|august|september|october|november|december)\s+(20[0-2]\d)\b/gi;
+
+  const suggestions = allPosts.map(p => {
+    const content = p.content?.rendered || '';
+    const title = strip(p.title?.rendered || '');
+    const wordCount = countWords(content);
+    if (wordCount < staleMinWords) return null;
+
+    const modified = new Date(p.modified || p.date);
+    const daysSinceUpdate = Math.floor((Date.now() - modified.getTime()) / 86400000);
+    const reasons = [];
+    let priority = 0;
+
+    // Age factor
+    priority += Math.min(daysSinceUpdate / 30, 24); // max 24 pts for 2+ years
+    reasons.push(`Last updated ${daysSinceUpdate} days ago`);
+
+    // Date mentions in content
+    const plainText = strip(content);
+    const yearMatches = [...plainText.matchAll(yearPattern)];
+    const currentYear = new Date().getFullYear();
+    const outdatedYears = yearMatches.filter(m => parseInt(m[1]) < currentYear - 1);
+    if (outdatedYears.length > 0) {
+      const years = [...new Set(outdatedYears.map(m => m[1]))].sort();
+      priority += outdatedYears.length * 3;
+      reasons.push(`Contains outdated date references: ${years.join(', ')}`);
+    }
+
+    // Date expressions
+    const dateExprs = [...plainText.matchAll(datePatterns)];
+    const outdatedExprs = dateExprs.filter(m => parseInt(m[2]) < currentYear - 1);
+    if (outdatedExprs.length > 0 && outdatedYears.length === 0) {
+      priority += outdatedExprs.length * 2;
+      reasons.push(`Contains dated expressions (e.g. "${outdatedExprs[0][0]}")`);
+    }
+
+    // Short content bonus
+    if (wordCount < 300) {
+      priority += 5;
+      reasons.push(`Thin content (${wordCount} words)`);
+    }
+
+    return {
+      post_id: p.id,
+      title,
+      slug: p.slug,
+      link: p.link,
+      word_count: wordCount,
+      last_modified: p.modified,
+      days_since_update: daysSinceUpdate,
+      priority_score: Math.round(priority * 10) / 10,
+      reasons
+    };
+  }).filter(Boolean).sort((a, b) => b.priority_score - a.priority_score);
+
+  result = json({ total_analyzed: allPosts.length, stale_threshold_months: staleMonths, suggestions });
+  auditLog({ tool: name, action: 'suggest_content_updates', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wp_audit_author_consistency'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name, calculateReadabilityScore, countWords } = rt;
+  const acTypes = args.post_types || ['post'];
+  const acMinPosts = args.min_posts || 3;
+  const acPerPage = Math.min(args.per_page || 100, 100);
+
+  // Fetch users (authors)
+  let users = [];
+  try {
+    users = await wpApiCall('/users?per_page=100&who=authors');
+  } catch (_e) {
+    try { users = await wpApiCall('/users?per_page=100'); } catch (_e2) { /* no users */ }
+  }
+  if (!Array.isArray(users)) users = [];
+
+  const authorProfiles = [];
+  const siteStats = { total_words: 0, total_posts: 0, total_media: 0, readability_sum: 0 };
+
+  for (const user of users) {
+    const endpoint = acTypes[0] === 'post' ? 'posts' : acTypes[0] === 'page' ? 'pages' : acTypes[0];
+    let posts = [];
+    try {
+      posts = await wpApiCall(`/${endpoint}?author=${user.id}&per_page=${acPerPage}&status=publish&orderby=date&order=desc`);
+      if (!Array.isArray(posts)) posts = [];
+    } catch (_e) { continue; }
+
+    if (posts.length < acMinPosts) continue;
+
+    let totalWords = 0, totalMediaCount = 0, readabilitySum = 0;
+    const dates = [];
+
+    for (const p of posts) {
+      const content = p.content?.rendered || '';
+      const wc = countWords(content);
+      totalWords += wc;
+
+      // Media count: images in content
+      const imgMatches = content.match(/<img\b/gi);
+      totalMediaCount += imgMatches ? imgMatches.length : 0;
+
+      // Readability
+      if (wc > 50) {
+        const readScore = calculateReadabilityScore(content);
+        readabilitySum += readScore.score;
+      }
+
+      dates.push(new Date(p.date));
+    }
+
+    const avgWords = Math.round(totalWords / posts.length);
+    const avgMedia = Math.round((totalMediaCount / posts.length) * 10) / 10;
+    const avgReadability = posts.filter(p => countWords(p.content?.rendered || '') > 50).length > 0
+      ? Math.round(readabilitySum / posts.filter(p => countWords(p.content?.rendered || '') > 50).length * 10) / 10
+      : null;
+
+    // Publication frequency: posts per month
+    dates.sort((a, b) => a - b);
+    const spanDays = dates.length > 1 ? (dates[dates.length - 1] - dates[0]) / 86400000 : 30;
+    const postsPerMonth = Math.round((posts.length / Math.max(spanDays / 30, 1)) * 10) / 10;
+
+    authorProfiles.push({
+      author_id: user.id,
+      name: user.name,
+      post_count: posts.length,
+      avg_word_count: avgWords,
+      posts_per_month: postsPerMonth,
+      avg_readability_score: avgReadability,
+      avg_media_per_post: avgMedia,
+      last_published: dates[dates.length - 1]?.toISOString() || null
+    });
+
+    siteStats.total_words += totalWords;
+    siteStats.total_posts += posts.length;
+    siteStats.total_media += totalMediaCount;
+    siteStats.readability_sum += readabilitySum;
+  }
+
+  // Site averages
+  const siteAvg = {
+    avg_word_count: siteStats.total_posts > 0 ? Math.round(siteStats.total_words / siteStats.total_posts) : 0,
+    avg_media_per_post: siteStats.total_posts > 0 ? Math.round((siteStats.total_media / siteStats.total_posts) * 10) / 10 : 0,
+    avg_readability: siteStats.total_posts > 0 && siteStats.readability_sum > 0
+      ? Math.round(siteStats.readability_sum / siteStats.total_posts * 10) / 10 : null
+  };
+
+  // Deviation per author
+  for (const ap of authorProfiles) {
+    ap.deviation = {
+      word_count_vs_avg: siteAvg.avg_word_count > 0 ? Math.round(((ap.avg_word_count - siteAvg.avg_word_count) / siteAvg.avg_word_count) * 100) : 0,
+      media_vs_avg: siteAvg.avg_media_per_post > 0 ? Math.round(((ap.avg_media_per_post - siteAvg.avg_media_per_post) / siteAvg.avg_media_per_post) * 100) : 0
+    };
+  }
+
+  result = json({ authors: authorProfiles, site_average: siteAvg, total_authors_analyzed: authorProfiles.length });
+  auditLog({ tool: name, action: 'audit_author_consistency', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wp_build_editorial_calendar'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name } = rt;
+  const calMonthsAhead = args.months_ahead || 3;
+  const calTypes = args.post_types || ['post'];
+
+  // Fetch last 12 months of posts
+  const oneYearAgo = new Date();
+  oneYearAgo.setFullYear(oneYearAgo.getFullYear() - 1);
+  const afterISO = oneYearAgo.toISOString();
+
+  let allPosts = [];
+  for (const pt of calTypes) {
+    const endpoint = pt === 'post' ? 'posts' : pt === 'page' ? 'pages' : pt;
+    let page = 1;
+    while (page <= 10) {
+      try {
+        const batch = await wpApiCall(`/${endpoint}?per_page=100&page=${page}&status=publish&after=${afterISO}&orderby=date&order=asc`);
+        if (!Array.isArray(batch) || batch.length === 0) break;
+        allPosts.push(...batch);
+        if (batch.length < 100) break;
+        page++;
+      } catch (_e) { break; }
+    }
+  }
+
+  // Analyze by month and weekday
+  const monthCounts = {};
+  const weekdayCounts = [0, 0, 0, 0, 0, 0, 0]; // Sun-Sat
+  const categoryCount = {};
+
+  for (const p of allPosts) {
+    const d = new Date(p.date);
+    const monthKey = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+    monthCounts[monthKey] = (monthCounts[monthKey] || 0) + 1;
+    weekdayCounts[d.getDay()]++;
+
+    // Track categories for topic suggestions
+    if (Array.isArray(p.categories)) {
+      for (const catId of p.categories) {
+        categoryCount[catId] = (categoryCount[catId] || 0) + 1;
+      }
+    }
+  }
+
+  // Average posts per month
+  const monthKeys = Object.keys(monthCounts).sort();
+  const avgPerMonth = monthKeys.length > 0 ? Math.round((allPosts.length / monthKeys.length) * 10) / 10 : 0;
+
+  // Best publishing days (top 3)
+  const dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+  const bestDays = weekdayCounts
+    .map((c, i) => ({ day: dayNames[i], count: c }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 3)
+    .map(d => d.day);
+
+  // Seasonal pattern: months with above-average output
+  const peakMonths = monthKeys.filter(k => monthCounts[k] > avgPerMonth).map(k => {
+    const [y, m] = k.split('-');
+    return parseInt(m);
+  });
+  const peakMonthNames = [...new Set(peakMonths)].sort((a, b) => a - b);
+
+  // Scheduled posts
+  let scheduledPosts = [];
+  for (const pt of calTypes) {
+    const endpoint = pt === 'post' ? 'posts' : pt === 'page' ? 'pages' : pt;
+    try {
+      const scheduled = await wpApiCall(`/${endpoint}?per_page=100&status=future&orderby=date&order=asc`);
+      if (Array.isArray(scheduled)) scheduledPosts.push(...scheduled);
+    } catch (_e) { /* no access */ }
+  }
+
+  // Build recommended calendar
+  const calendar = [];
+  const now = new Date();
+  for (let m = 0; m < calMonthsAhead; m++) {
+    const targetDate = new Date(now.getFullYear(), now.getMonth() + m + 1, 1);
+    const monthNum = targetDate.getMonth() + 1;
+    const monthLabel = `${targetDate.getFullYear()}-${String(monthNum).padStart(2, '0')}`;
+
+    // Recommended post count based on historical average
+    const recommendedCount = Math.max(Math.round(avgPerMonth), 1);
+    const scheduledInMonth = scheduledPosts.filter(p => {
+      const sd = new Date(p.date);
+      return sd.getFullYear() === targetDate.getFullYear() && sd.getMonth() + 1 === monthNum;
+    });
+
+    const gap = Math.max(0, recommendedCount - scheduledInMonth.length);
+
+    calendar.push({
+      month: monthLabel,
+      recommended_posts: recommendedCount,
+      already_scheduled: scheduledInMonth.length,
+      gap,
+      best_days: bestDays,
+      scheduled_titles: scheduledInMonth.map(p => ({ id: p.id, title: strip(p.title?.rendered || ''), date: p.date }))
+    });
+  }
+
+  // Top categories for topic suggestions
+  const topCategories = Object.entries(categoryCount)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, 10)
+    .map(([catId, count]) => ({ category_id: parseInt(catId), post_count: count }));
+
+  result = json({
+    analysis_period: { from: afterISO, posts_analyzed: allPosts.length },
+    publishing_pattern: { avg_posts_per_month: avgPerMonth, best_days: bestDays, peak_months: peakMonthNames, monthly_breakdown: monthCounts },
+    calendar,
+    top_categories: topCategories
+  });
+  auditLog({ tool: name, action: 'build_editorial_calendar', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wp_find_pillar_content_gaps'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, auditLog, sanitizeParams, name, countWords } = rt;
+  const gapMinCluster = args.min_cluster_size || 3;
+  const gapMinPillarWords = args.min_word_count_pillar || 1500;
+  const gapTypes = args.post_types || ['post', 'page'];
+
+  // Fetch categories with post counts
+  let categories = [];
+  try {
+    categories = await wpApiCall('/categories?per_page=100&hide_empty=true');
+    if (!Array.isArray(categories)) categories = [];
+  } catch (_e) { /* no access */ }
+
+  // Fetch tags with post counts
+  let tags = [];
+  try {
+    tags = await wpApiCall('/tags?per_page=100&hide_empty=true&orderby=count&order=desc');
+    if (!Array.isArray(tags)) tags = [];
+  } catch (_e) { /* no access */ }
+
+  const gaps = [];
+
+  // Analyze categories
+  for (const cat of categories) {
+    if ((cat.count || 0) < gapMinCluster) continue;
+
+    // Fetch posts in this category
+    let catPosts = [];
+    try {
+      catPosts = await wpApiCall(`/posts?categories=${cat.id}&per_page=100&status=publish`);
+      if (!Array.isArray(catPosts)) catPosts = [];
+    } catch (_e) { continue; }
+
+    // Check if any post qualifies as pillar (long-form)
+    const hasPillar = catPosts.some(p => countWords(p.content?.rendered || '') >= gapMinPillarWords);
+
+    if (!hasPillar) {
+      const satellites = catPosts.map(p => ({
+        post_id: p.id,
+        title: strip(p.title?.rendered || ''),
+        word_count: countWords(p.content?.rendered || ''),
+        link: p.link
+      }));
+
+      gaps.push({
+        type: 'category',
+        taxonomy_id: cat.id,
+        name: cat.name,
+        slug: cat.slug,
+        post_count: catPosts.length,
+        description: cat.description || null,
+        satellite_posts: satellites,
+        recommendation: `Create a comprehensive pillar page (${gapMinPillarWords}+ words) for "${cat.name}" to anchor ${catPosts.length} existing posts.`
+      });
+    }
+  }
+
+  // Analyze tags (top tags only)
+  for (const tag of tags.slice(0, 30)) {
+    if ((tag.count || 0) < gapMinCluster) continue;
+
+    let tagPosts = [];
+    try {
+      tagPosts = await wpApiCall(`/posts?tags=${tag.id}&per_page=100&status=publish`);
+      if (!Array.isArray(tagPosts)) tagPosts = [];
+    } catch (_e) { continue; }
+
+    const hasPillar = tagPosts.some(p => countWords(p.content?.rendered || '') >= gapMinPillarWords);
+
+    if (!hasPillar) {
+      // Don't duplicate if same posts already covered by a category gap
+      const existingPostIds = new Set(gaps.flatMap(g => g.satellite_posts.map(s => s.post_id)));
+      const uniquePosts = tagPosts.filter(p => !existingPostIds.has(p.id));
+      if (uniquePosts.length < gapMinCluster) continue;
+
+      gaps.push({
+        type: 'tag',
+        taxonomy_id: tag.id,
+        name: tag.name,
+        slug: tag.slug,
+        post_count: tagPosts.length,
+        satellite_posts: tagPosts.map(p => ({
+          post_id: p.id,
+          title: strip(p.title?.rendered || ''),
+          word_count: countWords(p.content?.rendered || ''),
+          link: p.link
+        })),
+        recommendation: `Create a pillar page for topic "${tag.name}" linking ${tagPosts.length} related posts.`
+      });
+    }
+  }
+
+  // Sort by post count (biggest opportunity first)
+  gaps.sort((a, b) => b.post_count - a.post_count);
+
+  result = json({ total_gaps: gaps.length, min_cluster_size: gapMinCluster, min_pillar_words: gapMinPillarWords, gaps });
+  auditLog({ tool: name, action: 'find_pillar_content_gaps', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wp_audit_internal_link_equity'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, getActiveAuth, auditLog, sanitizeParams, name, extractInternalLinksHtml, countWords } = rt;
+  const linkTypes = args.post_types || ['post', 'page'];
+  const linkBatchSize = Math.min(args.batch_size || 50, 100);
+  const linkMaxPosts = args.max_posts || 500;
+
+  // Fetch all published posts in batches
+  const allContent = [];
+  for (const pt of linkTypes) {
+    const endpoint = pt === 'post' ? 'posts' : pt === 'page' ? 'pages' : pt;
+    let page = 1;
+    while (allContent.length < linkMaxPosts && page <= Math.ceil(linkMaxPosts / linkBatchSize)) {
+      try {
+        const batch = await wpApiCall(`/${endpoint}?per_page=${linkBatchSize}&page=${page}&status=publish`);
+        if (!Array.isArray(batch) || batch.length === 0) break;
+        allContent.push(...batch);
+        if (batch.length < linkBatchSize) break;
+        page++;
+      } catch (_e) { break; }
+    }
+  }
+
+  // Build link graph
+  const { url: siteUrl } = getActiveAuth();
+  const inbound = {}; // url -> Set of source post IDs
+  const outbound = {}; // post ID -> urls[]
+  const postMap = {}; // url -> { id, title, link, word_count }
+
+  for (const p of allContent) {
+    const pLink = p.link || '';
+    const pId = p.id;
+    const content = p.content?.rendered || '';
+    const title = strip(p.title?.rendered || '');
+    const wc = countWords(content);
+
+    postMap[pLink] = { id: pId, title, link: pLink, word_count: wc };
+    if (!inbound[pLink]) inbound[pLink] = new Set();
+
+    // Extract internal links from this post's content
+    const links = extractInternalLinksHtml(content, siteUrl);
+    outbound[pId] = links;
+
+    for (const target of links) {
+      if (!inbound[target]) inbound[target] = new Set();
+      inbound[target].add(pId);
+    }
+  }
+
+  // Analyze: orphans, over-linked, under-linked important pages
+  const orphans = [];
+  const overLinked = [];
+  const underLinked = [];
+
+  for (const [url, meta] of Object.entries(postMap)) {
+    const inCount = inbound[url] ? inbound[url].size : 0;
+    const outCount = outbound[meta.id] ? outbound[meta.id].length : 0;
+
+    if (inCount === 0) {
+      orphans.push({ ...meta, outbound_links: outCount });
+    }
+    if (inCount > 20) {
+      overLinked.push({ ...meta, inbound_links: inCount });
+    }
+    // Important but under-linked: >800 words, <3 inbound links
+    if (meta.word_count > 800 && inCount < 3) {
+      underLinked.push({ ...meta, inbound_links: inCount, outbound_links: outCount });
+    }
+  }
+
+  orphans.sort((a, b) => b.word_count - a.word_count);
+  overLinked.sort((a, b) => b.inbound_links - a.inbound_links);
+  underLinked.sort((a, b) => b.word_count - a.word_count);
+
+  // Distribution score: 0-100
+  const totalPages = Object.keys(postMap).length;
+  const orphanRatio = totalPages > 0 ? orphans.length / totalPages : 0;
+  const distributionScore = Math.round(Math.max(0, (1 - orphanRatio) * 100));
+
+  result = json({
+    total_pages_analyzed: totalPages,
+    distribution_score: distributionScore,
+    orphan_pages: { count: orphans.length, pages: orphans.slice(0, 20) },
+    over_linked_pages: { count: overLinked.length, pages: overLinked.slice(0, 10) },
+    under_linked_important: { count: underLinked.length, pages: underLinked.slice(0, 20) },
+    recommendations: [
+      orphans.length > 0 ? `${orphans.length} orphan page(s) with zero inbound links — add internal links from related content.` : null,
+      overLinked.length > 0 ? `${overLinked.length} page(s) with >20 inbound links — consider distributing link equity more evenly.` : null,
+      underLinked.length > 0 ? `${underLinked.length} important page(s) (>800 words) have fewer than 3 inbound links.` : null
+    ].filter(Boolean)
+  });
+  auditLog({ tool: name, action: 'audit_internal_link_equity', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};
+handlers['wp_suggest_content_cluster'] = async (args) => {
+  const t0 = Date.now();
+  let result;
+  const { wpApiCall, fetch, auditLog, sanitizeParams, name, buildTFIDFVectors, computeCosineSimilarity, countWords } = rt;
+  const clusterTopic = args.topic || null;
+  const clusterPostId = args.post_id || null;
+  const clusterThreshold = args.similarity_threshold || 0.15;
+  const clusterTypes = args.post_types || ['post', 'page'];
+  const clusterMaxPosts = args.max_posts || 200;
+
+  if (!clusterTopic && !clusterPostId) {
+    throw new Error('Either "topic" or "post_id" parameter is required.');
+  }
+
+  // Fetch posts in batches
+  const allPosts = [];
+  for (const pt of clusterTypes) {
+    const endpoint = pt === 'post' ? 'posts' : pt === 'page' ? 'pages' : pt;
+    let page = 1;
+    while (allPosts.length < clusterMaxPosts && page <= Math.ceil(clusterMaxPosts / 50)) {
+      try {
+        const batch = await wpApiCall(`/${endpoint}?per_page=50&page=${page}&status=publish`);
+        if (!Array.isArray(batch) || batch.length === 0) break;
+        allPosts.push(...batch);
+        if (batch.length < 50) break;
+        page++;
+      } catch (_e) { break; }
+    }
+  }
+
+  // Build document corpus for TF-IDF
+  const documents = allPosts.map(p => {
+    const title = strip(p.title?.rendered || '');
+    const excerpt = strip(p.excerpt?.rendered || '');
+    const tags = (p.tag_names || []).join(' ');
+    return { id: p.id, text: `${title} ${title} ${excerpt} ${tags}` }; // title weighted 2x
+  });
+
+  const { vectors } = buildTFIDFVectors(documents);
+
+  // Find seed vector
+  let seedVector = null;
+  let seedId = null;
+
+  if (clusterPostId) {
+    seedVector = vectors.get(clusterPostId);
+    seedId = clusterPostId;
+    if (!seedVector) {
+      // Try to fetch the specific post
+      try {
+        const seedPost = await wpApiCall(`/posts/${clusterPostId}`);
+        const seedTitle = strip(seedPost.title?.rendered || '');
+        const seedExcerpt = strip(seedPost.excerpt?.rendered || '');
+        const seedDoc = [{ id: clusterPostId, text: `${seedTitle} ${seedTitle} ${seedExcerpt}` }, ...documents];
+        const recomputed = buildTFIDFVectors(seedDoc);
+        seedVector = recomputed.vectors.get(clusterPostId);
+      } catch (_e) {
+        throw new Error(`Post ${clusterPostId} not found.`);
+      }
+    }
+  } else {
+    // Create a synthetic document from the topic keyword
+    seedId = '__topic__';
+    const syntheticDocs = [{ id: seedId, text: `${clusterTopic} ${clusterTopic} ${clusterTopic}` }, ...documents];
+    const recomputed = buildTFIDFVectors(syntheticDocs);
+    seedVector = recomputed.vectors.get(seedId);
+    // Re-extract all vectors from recomputed
+    for (const [id, vec] of recomputed.vectors) {
+      if (id !== seedId) vectors.set(id, vec);
+    }
+  }
+
+  if (!seedVector) {
+    result = json({ clusters: [], message: 'Could not build seed vector.' });
+    return result;
+  }
+
+  // Compute similarity of all posts to seed
+  const similarities = [];
+  for (const [id, vec] of vectors) {
+    if (id === seedId) continue;
+    const sim = computeCosineSimilarity(seedVector, vec);
+    if (sim >= clusterThreshold) {
+      const post = allPosts.find(p => p.id === id);
+      similarities.push({
+        post_id: id,
+        title: post ? strip(post.title?.rendered || '') : `Post #${id}`,
+        link: post?.link || null,
+        word_count: post ? countWords(post.content?.rendered || '') : 0,
+        similarity: Math.round(sim * 1000) / 1000
+      });
+    }
+  }
+
+  similarities.sort((a, b) => b.similarity - a.similarity);
+
+  // Suggest pillar: highest word count in cluster
+  const pillarCandidate = [...similarities].sort((a, b) => b.word_count - a.word_count)[0] || null;
+
+  // Sub-cluster by similarity bands
+  const highSim = similarities.filter(s => s.similarity >= 0.4);
+  const medSim = similarities.filter(s => s.similarity >= 0.25 && s.similarity < 0.4);
+  const lowSim = similarities.filter(s => s.similarity < 0.25);
+
+  result = json({
+    seed: clusterTopic ? { type: 'keyword', topic: clusterTopic } : { type: 'post', post_id: clusterPostId },
+    cluster_size: similarities.length,
+    suggested_pillar: pillarCandidate,
+    related_posts: similarities.slice(0, 30),
+    similarity_bands: {
+      high: { threshold: '>=0.4', count: highSim.length },
+      medium: { threshold: '0.25-0.4', count: medSim.length },
+      low: { threshold: `${clusterThreshold}-0.25`, count: lowSim.length }
+    }
+  });
+  auditLog({ tool: name, action: 'suggest_content_cluster', status: 'success', latency_ms: Date.now() - t0, params: sanitizeParams(args) });
+  return result;
+};