seo-intel 1.5.24 → 1.5.26

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.5.26 (2026-05-16)
+
+### New — MCP server (`seo-intel-mcp`)
+- SEO Intel now ships a Model Context Protocol server. Any MCP-capable AI host (Claude Code, Cursor, Cline, Continue, Zed) can call seo-intel's local SQLite intelligence as native tools — no API keys to manage, no remote servers to host, all data stays on your machine.
+- Install for Claude Code: `claude mcp add seo-intel "npx seo-intel-mcp"`
+- Stdio transport — the host spawns the server as a subprocess; zero infrastructure.
+- Tools shipped in this release:
+  - `list_projects` (**free**) — every configured project on this machine + crawled page count
+  - `get_intel(project, for?)` — wraps `seo-intel intel`. `for=raw` is free; `for=audit|blog|competitor` require an SEO Intel Solo license. When unlicensed, returns a clean MCP error with the upgrade message instead of silent failure.
+- Both tools return structured JSON the agent's LLM can chain — e.g. an agent can call `list_projects` then `get_intel(project=X, for=raw)` and analyse the raw inventory with its own flagship model, no extra prompting needed.
+- New dependency: `@modelcontextprotocol/sdk ^1.29.0`.
+
+## 1.5.25 (2026-05-16)
+
+### New — `seo-intel intel <project>` — canonical agent-facing entry point
+- Returns structured project intelligence as JSON or markdown — the single source of truth that upcoming MCP server, dashboard, and prompt-copy modal will all wrap (one function, four surfaces).
+- Slices:
+  - `--for=raw` (**free**) — page/keyword/heading/schema/sitemap inventory per domain. Pipe into your own AI agent for self-service analysis.
+  - `--for=audit` (paid) — citability scores + active insights ledger
+  - `--for=blog` (paid) — keyword gaps + long tails + drafting hints
+  - `--for=competitor` (paid) — competitor summary + keyword matrix + positioning
+- `--format=json` for agents; `--format=md` for humans / agent context windows
+- Paid slices use the existing `requirePro()` gate — free users see a standard upgrade message; paid users get the data.
+- New library: `lib/intel.js` exports `getIntel(db, project, opts)` + `intelToMarkdown(envelope)` for reuse from any surface.
+
 ## 1.5.24 (2026-05-16)
 
 ### Dashboard — projects with owned subdomains + sitemap data no longer vanish

package/cli.js

@@ -1415,6 +1415,47 @@ program
     process.exit(0);
   });
 
+// ── INTEL (canonical agent-facing entry point) ─────────────────────────────
+// Returns structured intelligence about a project. Same function backs MCP +
+// future surfaces. Free tier gets `raw`; paid slices are license-gated.
+program
+  .command('intel <project>')
+  .description('Structured project intelligence for AI agents (raw=free; audit/blog/competitor=paid)')
+  .option('--for <slice>', 'Slice: raw | audit | blog | competitor', 'raw')
+  .option('--format <fmt>', 'Output format: json | md', 'json')
+  .action(async (project, opts) => {
+    const isJson = opts.format === 'json';
+    const { getIntel, intelToMarkdown, FREE_SLICES, INTEL_SLICES } = await import('./lib/intel.js');
+
+    if (!INTEL_SLICES.includes(opts.for)) {
+      const msg = `Unknown slice "${opts.for}". Available: ${INTEL_SLICES.join(', ')}`;
+      if (isJson) { console.log(JSON.stringify({ error: msg })); process.exit(1); }
+      console.error(chalk.red(msg)); process.exit(1);
+    }
+
+    // Free slices skip the gate; paid slices use the standard requirePro pattern.
+    if (!FREE_SLICES.includes(opts.for)) {
+      if (!requirePro(`intel-${opts.for}`)) return;
+    }
+
+    // Validate project exists (loadConfig will throw with a helpful message otherwise)
+    loadConfig(project);
+    const db = getDb();
+
+    try {
+      const envelope = getIntel(db, project, { for: opts.for });
+      if (isJson) {
+        console.log(JSON.stringify(envelope, null, 2));
+      } else {
+        console.log(intelToMarkdown(envelope));
+      }
+    } catch (err) {
+      if (isJson) { console.log(JSON.stringify({ error: err.message })); process.exit(1); }
+      console.error(chalk.red('intel failed: ') + err.message);
+      process.exit(1);
+    }
+  });
+
 // ── STATUS ─────────────────────────────────────────────────────────────────
 program
   .command('status')

package/lib/gate.js

@@ -60,6 +60,9 @@ const FEATURE_NAMES = {
   'unlimited-pages':  'Unlimited Crawl Pages',
   'unlimited-projects': 'Unlimited Projects',
   'blog-draft':        'AEO Blog Draft Generator',
+  'intel-audit':       'Intel Audit Digest (AI-agent-ready)',
+  'intel-blog':        'Intel Blog Digest (AI-agent-ready)',
+  'intel-competitor':  'Intel Competitor Digest (AI-agent-ready)',
 };
 
 // ── CLI Gate — blocks command and shows upgrade message ──────────────────────

package/lib/intel.js

@@ -0,0 +1,177 @@
+/**
+ * lib/intel.js — Canonical "give me intelligence about this project" entry point.
+ *
+ * Single source of truth backing every agent-facing surface:
+ *   - CLI:  `seo-intel intel <project>` (this file's first consumer)
+ *   - MCP:  `seo-intel-mcp` server (v1.5.26 — wraps this same function)
+ *   - HTTP: dashboard / future REST endpoint
+ *
+ * Slices:
+ *   raw         (free)  — page/keyword/heading inventory, no analysis
+ *   audit       (paid)  — citability + technical + active insights
+ *   blog        (paid)  — gaps + tone hints for drafting
+ *   competitor  (paid)  — competitor summary + schema landscape
+ *
+ * Output is a stable structured object — agents should be able to chain calls
+ * without prompt gymnastics. Keep the schema additive across versions.
+ */
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { getActiveInsights, getCompetitorSummary, getKeywordMatrix } from '../db/db.js';
+import { getCitabilityScores } from '../analyses/aeo/index.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
+
+export const INTEL_SLICES = ['raw', 'audit', 'blog', 'competitor'];
+export const FREE_SLICES = ['raw'];
+
+/**
+ * @param {import('node:sqlite').DatabaseSync} db
+ * @param {string} project
+ * @param {{ for?: string }} [opts]
+ * @returns {object} structured intel digest
+ */
+export function getIntel(db, project, opts = {}) {
+  const slice = opts.for || 'raw';
+  if (!INTEL_SLICES.includes(slice)) {
+    throw new Error(`Unknown intel slice "${slice}". Available: ${INTEL_SLICES.join(', ')}`);
+  }
+
+  const envelope = {
+    project,
+    for: slice,
+    tier: FREE_SLICES.includes(slice) ? 'free' : 'paid',
+    generated_at: new Date().toISOString(),
+    seo_intel_version: VERSION,
+    data: {},
+  };
+
+  if (slice === 'raw')        envelope.data = collectRaw(db, project);
+  if (slice === 'audit')      envelope.data = collectAudit(db, project);
+  if (slice === 'blog')       envelope.data = collectBlog(db, project);
+  if (slice === 'competitor') envelope.data = collectCompetitor(db, project);
+
+  return envelope;
+}
+
+// ── Slice collectors ────────────────────────────────────────────────────────
+
+function collectRaw(db, project) {
+  const domains = db.prepare(
+    `SELECT d.domain, d.role, d.last_crawled,
+            COUNT(p.id) AS pages,
+            SUM(CASE WHEN p.status_code = 200 THEN 1 ELSE 0 END) AS pages_ok
+     FROM domains d
+     LEFT JOIN pages p ON p.domain_id = d.id
+     WHERE d.project = ?
+     GROUP BY d.id
+     ORDER BY d.role, d.domain`
+  ).all(project);
+
+  const totals = db.prepare(
+    `SELECT
+       (SELECT COUNT(*) FROM pages p JOIN domains d ON d.id=p.domain_id WHERE d.project=?)     AS pages,
+       (SELECT COUNT(*) FROM keywords k JOIN pages p ON p.id=k.page_id JOIN domains d ON d.id=p.domain_id WHERE d.project=?) AS keywords,
+       (SELECT COUNT(*) FROM headings h JOIN pages p ON p.id=h.page_id JOIN domains d ON d.id=p.domain_id WHERE d.project=?) AS headings,
+       (SELECT COUNT(*) FROM page_schemas s JOIN pages p ON p.id=s.page_id JOIN domains d ON d.id=p.domain_id WHERE d.project=?) AS schemas,
+       (SELECT COUNT(*) FROM sitemap_urls u JOIN domains d ON d.id=u.domain_id WHERE d.project=?) AS sitemap_urls`
+  ).get(project, project, project, project, project) || {};
+
+  const lastCrawl = domains.reduce((m, d) => Math.max(m, d.last_crawled || 0), 0);
+
+  return {
+    domains: domains.map(d => ({
+      domain: d.domain,
+      role: d.role,
+      pages: d.pages,
+      pages_ok: d.pages_ok,
+      last_crawled: d.last_crawled ? new Date(d.last_crawled).toISOString() : null,
+    })),
+    totals: {
+      pages: totals.pages || 0,
+      keywords: totals.keywords || 0,
+      headings: totals.headings || 0,
+      schemas: totals.schemas || 0,
+      sitemap_urls: totals.sitemap_urls || 0,
+    },
+    last_crawl: lastCrawl ? new Date(lastCrawl).toISOString() : null,
+    note: 'Free tier — raw crawl inventory. Pipe into your own AI for analysis, or upgrade to Solo for citability/gap/competitor intel.',
+  };
+}
+
+function collectAudit(db, project) {
+  const insights = getActiveInsights(db, project);
+  let citability = null;
+  try { citability = getCitabilityScores(db, project); } catch { /* citability_scores table may not exist if AEO never run */ }
+  return {
+    citability,
+    insights: {
+      keyword_gaps: insights.keyword_gaps,
+      content_gaps: insights.content_gaps,
+      technical_gaps: insights.technical_gaps,
+      quick_wins: insights.quick_wins,
+      site_watch: insights.site_watch,
+    },
+    last_insight_at: insights.generated_at ? new Date(insights.generated_at).toISOString() : null,
+  };
+}
+
+function collectBlog(db, project) {
+  const insights = getActiveInsights(db, project);
+  return {
+    keyword_gaps: insights.keyword_gaps,
+    long_tails: insights.long_tails,
+    content_gaps: insights.content_gaps,
+    keyword_inventor: insights.keyword_inventor,
+    positioning: insights.positioning,
+    drafting_hint: 'Each keyword_gap or long_tail is a candidate draft target. Pair with topic clusters from `seo-intel templates <project>` and citability gaps from `--for=audit` for AEO-aware drafts.',
+  };
+}
+
+function collectCompetitor(db, project) {
+  const summary = getCompetitorSummary(db, project);
+  const matrix = getKeywordMatrix(db, project);
+  const insights = getActiveInsights(db, project);
+  return {
+    summary,
+    keyword_matrix: matrix,
+    positioning: insights.positioning,
+    new_pages: insights.new_pages,
+  };
+}
+
+// ── Markdown formatter ──────────────────────────────────────────────────────
+
+export function intelToMarkdown(envelope) {
+  const { project, for: slice, tier, generated_at, data } = envelope;
+  const lines = [
+    `# SEO Intel — ${project}`,
+    `> slice: \`${slice}\` · tier: \`${tier}\` · generated: ${generated_at}`,
+    '',
+  ];
+
+  if (slice === 'raw') {
+    lines.push('## Crawl inventory', '');
+    lines.push(`- **Total pages:** ${data.totals.pages}`);
+    lines.push(`- **Keywords:** ${data.totals.keywords}`);
+    lines.push(`- **Headings:** ${data.totals.headings}`);
+    lines.push(`- **Schemas:** ${data.totals.schemas}`);
+    lines.push(`- **Sitemap URLs:** ${data.totals.sitemap_urls}`);
+    lines.push(`- **Last crawl:** ${data.last_crawl || 'never'}`, '');
+    lines.push('## Domains', '');
+    lines.push('| Domain | Role | Pages (200) | Last crawled |');
+    lines.push('| --- | --- | --- | --- |');
+    for (const d of data.domains) {
+      lines.push(`| ${d.domain} | ${d.role} | ${d.pages_ok}/${d.pages} | ${d.last_crawled || '—'} |`);
+    }
+    lines.push('', `> ${data.note}`);
+  } else {
+    // Generic JSON-in-fence fallback for paid slices — agents can parse either way.
+    lines.push(`## ${slice} (data)`, '', '```json', JSON.stringify(data, null, 2), '```');
+  }
+
+  return lines.join('\n');
+}

package/mcp/server.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * seo-intel MCP server — stdio transport.
+ *
+ * Run as a subprocess by an MCP-capable host (Claude Code, Cursor, Cline,
+ * Continue, Zed, etc.). Exposes seo-intel's local SQLite intelligence to
+ * the host's LLM as native tools.
+ *
+ * Install for Claude Code:
+ *   claude mcp add seo-intel "npx seo-intel-mcp"
+ *
+ * Tools (v1.5.26):
+ *   list_projects  — free  — projects on this machine + page counts
+ *   get_intel      — free `raw` slice / paid `audit|blog|competitor` slices
+ *
+ * IMPORTANT: stdout is reserved for JSON-RPC messages. All logging here goes
+ * to stderr. Never use console.log in this file.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+import { getDb } from '../db/db.js';
+import { getIntel, INTEL_SLICES, FREE_SLICES } from '../lib/intel.js';
+import { isPro } from '../lib/license.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..');
+const VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8')).version;
+const CONFIG_DIR = join(ROOT, 'config');
+
+const server = new McpServer({ name: 'seo-intel', version: VERSION });
+
+function listConfigProjects() {
+  if (!existsSync(CONFIG_DIR)) return [];
+  return readdirSync(CONFIG_DIR)
+    .filter(f => f.endsWith('.json') && f !== 'example.json' && !f.startsWith('setup'))
+    .map(f => {
+      try {
+        const c = JSON.parse(readFileSync(join(CONFIG_DIR, f), 'utf8'));
+        return { project: c.project || f.replace('.json', ''), target: c.target?.domain || null };
+      } catch { return null; }
+    })
+    .filter(Boolean);
+}
+
+// ── Tool: list_projects (free) ────────────────────────────────────────────
+server.registerTool(
+  'list_projects',
+  {
+    description: 'List all SEO Intel projects configured on this machine, each with its target domain and crawled page count. Use this first to discover which projects are available before calling get_intel. Free tier — no license required.',
+  },
+  async () => {
+    const db = getDb();
+    const configs = listConfigProjects();
+    const out = configs.map(c => {
+      const row = db.prepare(
+        'SELECT COUNT(*) AS n FROM pages p JOIN domains d ON d.id=p.domain_id WHERE d.project=?'
+      ).get(c.project);
+      return { ...c, pages: row?.n || 0 };
+    });
+    return {
+      content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+      structuredContent: { projects: out },
+    };
+  }
+);
+
+// ── Tool: get_intel (free raw / paid others) ──────────────────────────────
+server.registerTool(
+  'get_intel',
+  {
+    description: [
+      'Get structured project intelligence as a JSON envelope ready for AI agent consumption.',
+      '',
+      'Slices:',
+      '  raw         (FREE)  page/keyword/heading/schema/sitemap inventory per domain',
+      '  audit       (paid)  citability scores + active insights ledger',
+      '  blog        (paid)  keyword gaps + long tails + drafting hints',
+      '  competitor  (paid)  competitor summary + keyword matrix + positioning',
+      '',
+      'Paid slices require an SEO Intel Solo license (set SEO_INTEL_LICENSE in env, or activate via the CLI). When unlicensed, the tool returns a clear upgrade message — no silent failure.',
+      '',
+      'Output envelope: { project, for, tier, generated_at, seo_intel_version, data }.',
+    ].join('\n'),
+    inputSchema: {
+      project: z.string().describe('Project slug. Call list_projects first to discover available projects.'),
+      for: z.enum(INTEL_SLICES).optional().describe('Slice — defaults to "raw" (free).'),
+    },
+  },
+  async ({ project, for: slice = 'raw' }) => {
+    if (!FREE_SLICES.includes(slice) && !isPro()) {
+      const msg = `The "${slice}" slice requires SEO Intel Solo (€19.99/mo). Free tier supports: ${FREE_SLICES.join(', ')}. Activate at https://ukkometa.fi/en/seo-intel/ — set SEO_INTEL_LICENSE=SI-xxxx-xxxx-xxxx-xxxx in your env.`;
+      return {
+        content: [{ type: 'text', text: msg }],
+        isError: true,
+      };
+    }
+    try {
+      const db = getDb();
+      const envelope = getIntel(db, project, { for: slice });
+      return {
+        content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }],
+        structuredContent: envelope,
+      };
+    } 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.`);
+}
+
+main().catch(err => {
+  console.error('[seo-intel-mcp] fatal:', err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seo-intel",
-  "version": "1.5.24",
+  "version": "1.5.26",
   "description": "Local Ahrefs-style SEO competitor intelligence. Crawl → SQLite → cloud analysis.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -20,7 +20,8 @@
     "local-first"
   ],
   "bin": {
-    "seo-intel": "cli.js"
+    "seo-intel": "cli.js",
+    "seo-intel-mcp": "mcp/server.js"
   },
   "exports": {
     ".": "./cli.js",
@@ -65,6 +66,7 @@
     "analysis/",
     "extractor/",
     "exports/",
+    "mcp/",
     "reports/generate-html.js",
     "reports/generate-site-graph.js",
     "reports/gsc-loader.js",
@@ -87,6 +89,7 @@
     "postinstall": "echo '\\n  SEO Intel installed.\\n  Run: seo-intel setup\\n  Or: seo-intel serve (opens dashboard)\\n'"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "dotenv": "^16.4.5",