seo-intel 1.5.25 → 1.5.27

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.5.27 (2026-05-16)
+
+### MCP — three new free-tier read tools
+The MCP server (`seo-intel-mcp`) now exposes individual records, not just summaries. AI agents can drill from inventory into actual pages, keywords, and heading structures without leaving the agent chat.
+
+- **`get_pages(project, role?, limit?, offset?)`** — paginated page list with url, title, word count, status, click depth, and domain role. Filterable by role (target / owned / competitor). Returns total count for pagination math.
+- **`list_keywords(project, domain?, limit?)`** — top extracted keywords grouped by domain + location (title / h1 / h2 / meta / body). Use to surface what each site is targeting before running gap analysis.
+- **`get_headings(project, url, limit?)`** — heading structure (H1–H6) for a specific page. Returns ordered `{ level, text }` list. Useful for content-architecture comparisons between target and competitor pages.
+
+All three are **free tier** — no license required. Pairs naturally with the existing `list_projects` and `get_intel(raw)` to give AI agents a complete free-tier read surface: list projects → inspect inventory → drill into pages → read headings → analyze with the agent's own flagship LLM.
+
+Errors are returned as proper MCP `isError: true` responses with helpful guidance (e.g. `get_headings` on an unknown URL points the agent at `get_pages`).
+
+## 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

package/mcp/server.js

@@ -0,0 +1,246 @@
+#!/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,
+      };
+    }
+  }
+);
+
+// ── Tool: get_pages (free) ────────────────────────────────────────────────
+server.registerTool(
+  'get_pages',
+  {
+    description: 'Paginated list of crawled pages for a project, with url, title, word count, status, and domain role. Use this to drill into individual pages after seeing the inventory summary from get_intel. Free tier.',
+    inputSchema: {
+      project: z.string().describe('Project slug'),
+      role: z.enum(['target', 'owned', 'competitor']).optional().describe('Filter by domain role'),
+      limit: z.number().int().positive().max(500).optional().describe('Max pages to return (default 50, max 500)'),
+      offset: z.number().int().nonnegative().optional().describe('Offset for pagination (default 0)'),
+    },
+  },
+  async ({ project, role, limit = 50, offset = 0 }) => {
+    try {
+      const db = getDb();
+      const whereParams = role ? [project, role] : [project];
+      const where = role ? 'd.project = ? AND d.role = ?' : 'd.project = ?';
+      const rows = db.prepare(
+        `SELECT p.url, p.title, p.word_count, p.status_code, p.click_depth,
+                d.domain, d.role
+         FROM pages p JOIN domains d ON d.id = p.domain_id
+         WHERE ${where}
+         ORDER BY d.role, d.domain, p.url
+         LIMIT ? OFFSET ?`
+      ).all(...whereParams, limit, offset);
+      const total = db.prepare(
+        `SELECT COUNT(*) AS n FROM pages p JOIN domains d ON d.id = p.domain_id WHERE ${where}`
+      ).get(...whereParams)?.n || 0;
+      const out = { project, role: role || 'any', total, returned: rows.length, offset, pages: rows };
+      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: list_keywords (free) ────────────────────────────────────────────
+server.registerTool(
+  'list_keywords',
+  {
+    description: 'Top extracted keywords for a project, grouped by domain. Each keyword has frequency, location (title/h1/h2/meta/body), and source domain. Use this to surface what each site is targeting before running gap analysis. Free tier.',
+    inputSchema: {
+      project: z.string().describe('Project slug'),
+      domain: z.string().optional().describe('Optional: filter to a single domain'),
+      limit: z.number().int().positive().max(1000).optional().describe('Max keywords to return (default 100, max 1000)'),
+    },
+  },
+  async ({ project, domain, limit = 100 }) => {
+    try {
+      const db = getDb();
+      const params = [project];
+      let where = 'd.project = ?';
+      if (domain) { where += ' AND d.domain = ?'; params.push(domain); }
+      params.push(limit);
+      const rows = db.prepare(
+        `SELECT k.keyword, k.location, d.domain, d.role, COUNT(*) AS freq
+         FROM keywords k
+           JOIN pages p ON p.id = k.page_id
+           JOIN domains d ON d.id = p.domain_id
+         WHERE ${where}
+         GROUP BY k.keyword, k.location, d.domain
+         ORDER BY freq DESC
+         LIMIT ?`
+      ).all(...params);
+      const out = { project, domain: domain || 'all', returned: rows.length, keywords: rows };
+      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: get_headings (free) ─────────────────────────────────────────────
+server.registerTool(
+  'get_headings',
+  {
+    description: 'Heading structure (H1–H6) for a specific page. Returns ordered list of { level, text }. Useful for content architecture comparisons between target and competitor pages. Free tier.',
+    inputSchema: {
+      project: z.string().describe('Project slug'),
+      url: z.string().describe('Exact page URL (as crawled). Get URLs from get_pages.'),
+      limit: z.number().int().positive().max(200).optional().describe('Max headings (default 50)'),
+    },
+  },
+  async ({ project, url, limit = 50 }) => {
+    try {
+      const db = getDb();
+      const page = db.prepare(
+        `SELECT p.id, p.title, p.word_count, d.domain, d.role
+         FROM pages p JOIN domains d ON d.id = p.domain_id
+         WHERE d.project = ? AND p.url = ?`
+      ).get(project, url);
+      if (!page) {
+        return {
+          content: [{ type: 'text', text: `No crawled page found for url="${url}" in project "${project}". Use get_pages to discover URLs.` }],
+          isError: true,
+        };
+      }
+      const headings = db.prepare(
+        `SELECT level, text FROM headings WHERE page_id = ? ORDER BY id LIMIT ?`
+      ).all(page.id, limit);
+      const out = { project, url, page_title: page.title, domain: page.domain, role: page.role, word_count: page.word_count, headings };
+      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.`);
+}
+
+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.25",
+  "version": "1.5.27",
   "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",