seo-intel 1.5.28 → 1.5.30

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # 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)
+The MCP server now accepts write-back. An agent can read your raw data, do its own analysis with its own flagship LLM, and persist findings into the Intelligence Ledger — surviving across sessions, surfacing in the dashboard, deduplicating against future runs.
+
+- **`ingest_insight(project, type, data, agent_name?)`** — **free tier**. The agent's LLM did the analysis; we just provide storage. Allowed types mirror what `analyze` writes: `keyword_gap`, `long_tail`, `quick_win`, `new_page`, `content_gap`, `technical_gap`, `positioning`.
+- **Dedup contract**: same `(project, type, fingerprint)` returns the existing row with `deduped: true` and bumps `last_seen` — no duplicate accumulation across sessions.
+- **Provenance**: source is stored as `agent:<name>` (e.g. `agent:claude-opus-4-7`) when `agent_name` is supplied, else just `agent`. Also stamped into the `data` JSON blob as `_source` for downstream consumers that only read `data`.
+- **Schema**: idempotent `ALTER TABLE insights ADD COLUMN source TEXT DEFAULT 'cli'` — existing rows backfill to `'cli'`; analyze-time writes stay as `'cli'`; agent writes flip to `'agent:*'`. Safe on existing DBs.
+
+### Logo
+- Updated product logo to the sharp / soft-corners v1 variant. Size dropped 1.46 MB → 953 KB. Dashboard favicon + npm package both pick up the new asset.
+
 ## 1.5.28 (2026-05-17)
 
 ### MCP — agents can now trigger crawls and watch progress

package/db/db.js

@@ -29,6 +29,7 @@ export function getDb(dbPath = './seo-intel.db') {
   try { _db.exec('ALTER TABLE pages ADD COLUMN x_robots_tag TEXT'); } catch { /* already exists */ }
   try { _db.exec('ALTER TABLE analyses ADD COLUMN technical_gaps TEXT'); } catch { /* already exists */ }
   try { _db.exec('ALTER TABLE extractions ADD COLUMN intent_scores TEXT'); } catch { /* already exists */ }
+  try { _db.exec("ALTER TABLE insights ADD COLUMN source TEXT DEFAULT 'cli'"); } catch { /* already exists */ }
 
   // Backfill first_seen_at from crawled_at for existing rows
   _db.exec('UPDATE pages SET first_seen_at = crawled_at WHERE first_seen_at IS NULL');
@@ -225,6 +226,59 @@ export function upsertInsightsFromKeywords(db, project, keywordsReport) {
   }
 }
 
+// ── Agent-ingested insight (write-back from MCP) ────────────────────────────
+
+export const AGENT_INSIGHT_TYPES = ['keyword_gap', 'long_tail', 'quick_win', 'new_page', 'content_gap', 'technical_gap', 'positioning'];
+
+/**
+ * Insert a single insight on behalf of an external agent (e.g. via MCP).
+ * Uses the same dedup contract as analyze-time inserts (UNIQUE on
+ * project + type + fingerprint), so an agent repeating the same finding
+ * across sessions updates `last_seen` instead of duplicating rows.
+ *
+ * Returns { ok, id, fingerprint, deduped } — `deduped: true` when the row
+ * already existed and we only refreshed last_seen.
+ */
+export function insertAgentInsight(db, { project, type, data, agentName }) {
+  if (!AGENT_INSIGHT_TYPES.includes(type)) {
+    return { ok: false, error: `Unsupported type "${type}". Allowed: ${AGENT_INSIGHT_TYPES.join(', ')}` };
+  }
+  if (!project) return { ok: false, error: 'project is required' };
+  if (!data || typeof data !== 'object') return { ok: false, error: 'data must be an object' };
+
+  const fingerprint = _insightFingerprint(type, data);
+  if (!fingerprint) {
+    return { ok: false, error: `data is missing the identifier field this type needs (see _insightFingerprint in db/db.js for the per-type contract)` };
+  }
+
+  const source = agentName ? `agent:${agentName}` : 'agent';
+  const ts = Date.now();
+
+  // Stash provenance inside the data blob too — survives if/when the source
+  // column is ever queried separately, but also keeps it visible to consumers
+  // that only read `data`.
+  const enriched = { ...data, _source: source, _ingested_at: new Date(ts).toISOString() };
+
+  const existing = db.prepare(
+    'SELECT id FROM insights WHERE project = ? AND type = ? AND fingerprint = ?'
+  ).get(project, type, fingerprint);
+
+  db.prepare(`
+    INSERT INTO insights (project, type, status, fingerprint, first_seen, last_seen, source_analysis_id, data, source)
+    VALUES (?, ?, 'active', ?, ?, ?, NULL, ?, ?)
+    ON CONFLICT(project, type, fingerprint) DO UPDATE SET
+      last_seen = excluded.last_seen,
+      data = excluded.data,
+      source = excluded.source
+  `).run(project, type, fingerprint, ts, ts, JSON.stringify(enriched), source);
+
+  const row = db.prepare(
+    'SELECT id FROM insights WHERE project = ? AND type = ? AND fingerprint = ?'
+  ).get(project, type, fingerprint);
+
+  return { ok: true, id: row.id, fingerprint, deduped: !!existing, source, last_seen: ts };
+}
+
 // ── Read active insights (accumulated across all runs) ──────────────────────
 
 export function getActiveInsights(db, project) {

package/mcp/server.js

@@ -25,11 +25,29 @@ import { spawn } from 'child_process';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
-import { getDb } 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;
@@ -307,11 +325,225 @@ server.registerTool(
   }
 );
 
+// ── Tool: ingest_insight (free — write-back closes the loop) ──────────────
+server.registerTool(
+  'ingest_insight',
+  {
+    description: [
+      'Persist an agent-generated insight into the SEO Intel Intelligence Ledger so it shows up in the dashboard and survives across sessions. Free tier — the agent\'s own LLM did the analysis; we just provide storage.',
+      '',
+      'Dedup contract: same (project, type, fingerprint) updates `last_seen` instead of creating a duplicate row. So an agent rediscovering the same finding across sessions cleanly bumps the timestamp.',
+      '',
+      'Allowed types (mirror what the cloud `analyze` command writes):',
+      '  keyword_gap     data: { keyword, ... }       fingerprint = keyword',
+      '  long_tail       data: { phrase, ... }        fingerprint = phrase',
+      '  quick_win       data: { page, issue, ... }   fingerprint = page::issue',
+      '  new_page        data: { target_keyword | title, ... }',
+      '  content_gap     data: { topic, ... }         fingerprint = topic',
+      '  technical_gap   data: { gap, ... }           fingerprint = gap',
+      '  positioning     data: { ...free-form... }    one slot per project',
+      '',
+      'data must include the identifier field above; otherwise the tool returns an error.',
+    ].join('\n'),
+    inputSchema: {
+      project: z.string().describe('Project slug'),
+      type: z.enum(AGENT_INSIGHT_TYPES).describe('Insight type from the allowed set'),
+      data: z.record(z.any()).describe('Insight payload — JSON object. Must include the identifier field for the chosen type.'),
+      agent_name: z.string().optional().describe('Optional provenance tag (e.g. "claude-opus-4-7"). Stored as source="agent:<name>".'),
+    },
+  },
+  async ({ project, type, data, agent_name }) => {
+    try {
+      const db = getDb();
+      const result = insertAgentInsight(db, { project, type, data, agentName: agent_name });
+      if (!result.ok) {
+        return { content: [{ type: 'text', text: `seo-intel ingest error: ${result.error}` }], isError: true };
+      }
+      const payload = {
+        ok: true,
+        project,
+        type,
+        insight_id: result.id,
+        fingerprint: result.fingerprint,
+        deduped: result.deduped,
+        source: result.source,
+        last_seen: new Date(result.last_seen).toISOString(),
+        hint: result.deduped
+          ? 'Insight already existed; last_seen refreshed.'
+          : 'New insight persisted. It will appear in the dashboard ledger and in get_intel(for=audit).',
+      };
+      return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `seo-intel error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── 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.`);
+  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.28",
+  "version": "1.5.30",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",