seo-intel 1.5.29 → 1.5.30

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.5.30 (2026-05-17)
+
+### MCP — paid analysis tools (the full Solo surface for AI agents)
+Solo subscribers can now reach the full analysis layer from any MCP host, not just the dashboard. Four new tools, all paid, all wrap existing `analyses/*` modules — same library-first pattern.
+
+- **`run_citability_audit(project, include_competitors?)`** — Run AEO scoring across all crawled pages (6 signals: entity authority, structured claims, answer density, Q&A proximity, freshness, schema coverage). Persists scores to `citability_scores` and upserts `citability_gap` insights into the ledger. Pure function — fast, no LLM calls. Returns target/competitor page counts, average score, top 20 low-score pages.
+- **`get_competitor_positioning(project)`** — Latest positioning analysis (from analyze runs or agent ingests) + per-competitor crawl stats (page counts, keyword counts, last crawl). The strategic narrative + the raw coverage in one envelope.
+- **`prescore_draft(draft_md)`** — Pre-publish AEO scorer for agent-written content. Same scorer the dashboard uses; takes markdown (frontmatter-aware) and returns 0–100 score, tier, signal breakdown, AI intents. Includes revision hints for sub-60 drafts. Pair with `draft_blog_prompt` for a write→score→revise loop.
+- **`draft_blog_prompt(project, topic?, lang?, content_type?)`** — Assemble an AEO-aware prompt seeded with the project's keyword gaps, citability gaps, entities, brand voice, and competitor heading patterns. The agent's own flagship LLM (Opus 4.7 / GPT-4o / Gemini) writes the draft. Supports `en` and `fi`. Topic optional — if omitted, prompt asks the LLM to pick the highest-leverage topic from gap data.
+
+**MCP surface now:** 12 tools total — 8 free (read raw data, trigger crawls, persist findings) + 4 paid (`get_intel` audit/blog/competitor slices, `run_citability_audit`, `get_competitor_positioning`, `prescore_draft`, `draft_blog_prompt`). Paid tools share a unified gate message that surfaces the Ahrefs/Semrush price comparison.
+
+A Solo agent session now looks like: `run_citability_audit` → `get_competitor_positioning` → `draft_blog_prompt(topic)` → agent's LLM writes the draft → `prescore_draft(output)` → revise if < 60 → `ingest_insight` to persist the gap that motivated the draft. Closed loop, all via MCP, no dashboard required.
+
+### Deferred
+- `run_gap_intel` (Ollama-based, long-running) — deferred to v1.5.31 where it'll use the detached-spawn pattern from `run_crawl`.
+
 ## 1.5.29 (2026-05-17)
 
 ### MCP — `ingest_insight` closes the loop (agents become collaborators, not consumers)

package/mcp/server.js

@@ -25,11 +25,29 @@ import { spawn } from 'child_process';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
-import { getDb, insertAgentInsight, AGENT_INSIGHT_TYPES } from '../db/db.js';
+import { getDb, insertAgentInsight, AGENT_INSIGHT_TYPES, getActiveInsights, getCompetitorSummary } from '../db/db.js';
 import { getIntel, INTEL_SLICES, FREE_SLICES } from '../lib/intel.js';
 import { isPro } from '../lib/license.js';
 import { readProgress } from '../lib/progress.js';
 
+import { runAeoAnalysis, persistAeoScores, upsertCitabilityInsights } from '../analyses/aeo/index.js';
+import { prescore } from '../analyses/blog-draft/prescorer.js';
+import { gatherBlogDraftContext, buildBlogDraftPrompt } from '../analyses/blog-draft/index.js';
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+function paidGate(toolName) {
+  return {
+    content: [{ type: 'text', text: `The "${toolName}" tool requires SEO Intel Solo (€19.99/mo — vs Ahrefs ~$129/mo or Semrush ~$140/mo). Free tier already covers list_projects, get_intel(raw), get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight. Activate at https://ukkometa.fi/en/seo-intel/ — set SEO_INTEL_LICENSE=SI-xxxx-xxxx-xxxx-xxxx in your env.` }],
+    isError: true,
+  };
+}
+
+function loadProjectConfig(project) {
+  const p = join(CONFIG_DIR, `${project}.json`);
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
+}
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
 const VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
@@ -364,11 +382,168 @@ server.registerTool(
   }
 );
 
+// ── Tool: run_citability_audit (PAID) ─────────────────────────────────────
+server.registerTool(
+  'run_citability_audit',
+  {
+    description: 'Run AEO citability scoring across all crawled pages (6 signals: entity authority, structured claims, answer density, Q&A proximity, freshness, schema coverage). Persists scores to citability_scores and upserts citability_gap insights into the ledger. Pure function — fast, no LLM calls. Paid tier.',
+    inputSchema: {
+      project: z.string(),
+      include_competitors: z.boolean().optional().describe('Score competitor pages too (default true)'),
+    },
+  },
+  async ({ project, include_competitors = true }) => {
+    if (!isPro()) return paidGate('run_citability_audit');
+    if (!loadProjectConfig(project)) {
+      return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
+    }
+    try {
+      const db = getDb();
+      const results = runAeoAnalysis(db, project, { includeCompetitors: include_competitors, log: () => {} });
+      persistAeoScores(db, results);
+      upsertCitabilityInsights(db, project, results.target);
+      const competitorPageCount = [...results.competitors.values()].reduce((a, list) => a + list.length, 0);
+      const avgTargetScore = results.target.length
+        ? Math.round(results.target.reduce((s, p) => s + p.score, 0) / results.target.length)
+        : 0;
+      const lowScorePages = results.target
+        .filter(p => p.score < 40)
+        .sort((a, b) => a.score - b.score)
+        .slice(0, 20)
+        .map(p => ({ url: p.url, score: p.score, tier: p.tier }));
+      const summary = {
+        ok: true,
+        project,
+        target_pages_scored: results.target.length,
+        competitor_pages_scored: competitorPageCount,
+        avg_target_score: avgTargetScore,
+        low_score_target_pages: lowScorePages,
+        hint: 'Scores persisted to DB. Call get_intel(project, for=audit) to see the full citability matrix + insights ledger.',
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+        structuredContent: summary,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: get_competitor_positioning (PAID) ───────────────────────────────
+server.registerTool(
+  'get_competitor_positioning',
+  {
+    description: 'Return the latest positioning analysis for a project + per-competitor crawl stats. Combines the positioning insight from the ledger (from `analyze` or agent ingests) with raw competitor coverage (page counts, keyword counts, last crawl). Paid tier.',
+    inputSchema: {
+      project: z.string(),
+    },
+  },
+  async ({ project }) => {
+    if (!isPro()) return paidGate('get_competitor_positioning');
+    if (!loadProjectConfig(project)) {
+      return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
+    }
+    try {
+      const db = getDb();
+      const insights = getActiveInsights(db, project);
+      const competitorSummary = getCompetitorSummary(db, project);
+      const out = {
+        project,
+        positioning: insights.positioning,  // null if never analysed
+        competitor_summary: competitorSummary,
+        last_insight_at: insights.generated_at ? new Date(insights.generated_at).toISOString() : null,
+        hint: insights.positioning ? 'Positioning is from the most recent analyze run or agent ingest.' : 'No positioning insight yet — run `seo-intel analyze <project>` or ingest one via ingest_insight(type=positioning).',
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+        structuredContent: out,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: prescore_draft (PAID) ───────────────────────────────────────────
+server.registerTool(
+  'prescore_draft',
+  {
+    description: 'Run the AEO scorer on a markdown draft before publishing. Returns the same 6-signal breakdown the dashboard uses (entity authority, structured claims, answer density, Q&A proximity, freshness, schema coverage) plus the overall 0-100 score and tier (excellent / good / fair / poor). Use this as a pre-publish gate when drafting via draft_blog_prompt — score < 60 means revise. Paid tier.',
+    inputSchema: {
+      draft_md: z.string().describe('Full markdown of the draft, including YAML frontmatter if present. The scorer extracts headings, word count, schema_type from frontmatter, etc.'),
+    },
+  },
+  async ({ draft_md }) => {
+    if (!isPro()) return paidGate('prescore_draft');
+    try {
+      const score = prescore(draft_md);
+      const out = {
+        ok: true,
+        score: score.score,
+        tier: score.tier,
+        signals: score.signals,
+        ai_intents: score.ai_intents,
+        hint: score.score >= 60
+          ? 'Draft scores well. Safe to publish.'
+          : 'Below 60 — consider strengthening: add FAQ schema for Q&A proximity, increase entity authority via named experts/citations, shorten paragraphs for answer density, add structured claims (numbers/dates).',
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+        structuredContent: out,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Tool: draft_blog_prompt (PAID) ────────────────────────────────────────
+server.registerTool(
+  'draft_blog_prompt',
+  {
+    description: 'Generate an AEO-aware blog draft prompt seeded with full project context — keyword gaps, citability gaps, top entities, brand voice notes, competitor heading patterns. The agent\'s own LLM writes the draft using this prompt. Pair with prescore_draft for a write→score→revise loop. Paid tier.',
+    inputSchema: {
+      project: z.string(),
+      topic: z.string().optional().describe('Specific topic to draft about. If omitted, the prompt asks the LLM to pick the highest-leverage topic from the gap data.'),
+      lang: z.enum(['en', 'fi']).optional().describe('Output language (default en)'),
+      content_type: z.enum(['blog', 'article', 'guide']).optional().describe('Content type framing (default blog)'),
+    },
+  },
+  async ({ project, topic, lang = 'en', content_type = 'blog' }) => {
+    if (!isPro()) return paidGate('draft_blog_prompt');
+    const config = loadProjectConfig(project);
+    if (!config) {
+      return { content: [{ type: 'text', text: `Project "${project}" not found. Use list_projects to discover.` }], isError: true };
+    }
+    try {
+      const db = getDb();
+      const context = gatherBlogDraftContext(db, project, topic);
+      const prompt = buildBlogDraftPrompt(context, { config, lang, topic, contentType: content_type });
+      const out = {
+        project,
+        topic: topic || '(LLM to pick from gap data)',
+        lang,
+        content_type,
+        prompt_length_chars: prompt.length,
+        prompt,
+        hint: 'Pass `prompt` to your flagship LLM (Opus 4.7 / GPT-4o / etc) to generate the draft. Then run prescore_draft on the output to AEO-score before publishing.',
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+        structuredContent: out,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
   // stderr is fine; the host typically surfaces this in its MCP logs panel.
-  console.error(`[seo-intel-mcp] v${VERSION} ready on stdio. Tools: list_projects, get_intel, get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight.`);
+  console.error(`[seo-intel-mcp] v${VERSION} ready on stdio. 12 tools — free: list_projects, get_intel(raw), get_pages, list_keywords, get_headings, run_crawl, get_crawl_status, ingest_insight; paid: get_intel(audit/blog/competitor), run_citability_audit, get_competitor_positioning, prescore_draft, draft_blog_prompt.`);
 }
 
 main().catch(err => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-intel",
-  "version": "1.5.29",
+  "version": "1.5.30",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",