feat(seo-engine): implement competitor scraper, MDX draft editor, and strategy report generator

2026-03-02 10:16:11 +01:00
parent 36ed26ad79
commit ded9da7d32
20 changed files with 1596 additions and 0 deletions
--- a/packages/seo-engine/README.md
+++ b/packages/seo-engine/README.md
@@ -0,0 +1,123 @@
+# @mintel/seo-engine
+
+AI-powered SEO keyword discovery, topic clustering, competitor analysis, and content gap identification — grounded in real search data, zero hallucinations.
+
+## Architecture
+
+```
+ProjectContext + SeoConfig
+        │
+        ▼
+┌──────────────────────────────────────────┐
+│            SEO Engine Orchestrator       │
+│                                          │
+│  1. Seed Query Expansion                 │
+│     (company + industry + seedKeywords)  │
+│                                          │
+│  2. Data Collection (parallel)           │
+│     ├── Serper Search Agent              │
+│     │   (related searches, PAA,          │
+│     │    organic snippets, volume proxy) │
+│     ├── Serper Autocomplete Agent        │
+│     │   (long-tail suggestions)          │
+│     └── Serper Competitor Agent          │
+│         (top-10 SERP positions)          │
+│                                          │
+│  3. LLM Evaluation (Gemini/Claude)       │
+│     → Strict context filtering           │
+│     → Topic Clustering + Intent Mapping  │
+│                                          │
+│  4. Content Gap Analysis (LLM)           │
+│     → Compare clusters vs existing pages │
+│     → Identify missing content           │
+└──────────────────────────────────────────┘
+        │
+        ▼
+   SeoEngineOutput
+   (clusters, gaps, competitors, discarded)
+```
+
+## Quick Start
+
+```typescript
+import { runSeoEngine } from "@mintel/seo-engine";
+
+const result = await runSeoEngine(
+  {
+    companyName: "KLZ Cables",
+    industry: "Mittelspannungskabel, Kabeltiefbau",
+    briefing: "B2B provider of specialized medium-voltage cables.",
+    targetAudience: "Bauleiter, Netzbetreiber",
+    competitors: ["nkt.de", "faberkabel.de"],
+    seedKeywords: ["NA2XS2Y", "VPE-isoliert"],
+    existingPages: [
+      { url: "/produkte", title: "Produkte" },
+      { url: "/kontakt", title: "Kontakt" },
+    ],
+    locale: { gl: "de", hl: "de" },
+  },
+  {
+    serperApiKey: process.env.SERPER_API_KEY!,
+    openRouterApiKey: process.env.OPENROUTER_API_KEY!,
+  },
+);
+```
+
+## Configuration
+
+### `ProjectContext`
+
+| Field              | Type                          | Description                                 |
+| ------------------ | ----------------------------- | ------------------------------------------- |
+| `companyName`      | `string?`                     | Client company name                         |
+| `industry`         | `string?`                     | Industry / main focus keywords              |
+| `briefing`         | `string?`                     | Project briefing text                       |
+| `targetAudience`   | `string?`                     | Who the content targets                     |
+| `competitors`      | `string[]?`                   | Competitor domains to analyze               |
+| `seedKeywords`     | `string[]?`                   | Explicit seed keywords beyond auto-derived  |
+| `existingPages`    | `{ url, title }[]?`           | Current site pages for content gap analysis |
+| `customGuidelines` | `string?`                     | Extra strict filtering rules for the LLM    |
+| `locale`           | `{ gl: string, hl: string }?` | Google locale (default: `de`)               |
+
+### `SeoConfig`
+
+| Field              | Type      | Description                                  |
+| ------------------ | --------- | -------------------------------------------- |
+| `serperApiKey`     | `string`  | **Required.** Serper API key                 |
+| `openRouterApiKey` | `string`  | **Required.** OpenRouter API key             |
+| `model`            | `string?` | LLM model (default: `google/gemini-2.5-pro`) |
+| `maxKeywords`      | `number?` | Cap total keywords returned                  |
+
+## Output
+
+```typescript
+interface SeoEngineOutput {
+  topicClusters: TopicCluster[]; // Grouped keywords with intent + scores
+  competitorRankings: CompetitorRanking[]; // Who ranks for your terms
+  contentGaps: ContentGap[]; // Missing pages you should create
+  discardedTerms: string[]; // Terms filtered out (with reasons)
+}
+```
+
+## Agents
+
+| Agent                 | Source                 | Data                                |
+| --------------------- | ---------------------- | ----------------------------------- |
+| `serper-agent`        | Serper `/search`       | Related searches, PAA, snippets     |
+| `serper-autocomplete` | Serper `/autocomplete` | Google Autocomplete long-tail terms |
+| `serper-competitors`  | Serper `/search`       | Competitor SERP positions           |
+
+## API Keys
+
+- **Serper** — [serper.dev](https://serper.dev) (pay-per-search, ~$0.001/query)
+- **OpenRouter** — [openrouter.ai](https://openrouter.ai) (pay-per-token)
+
+No monthly subscriptions. Pure pay-on-demand.
+
+## Development
+
+```bash
+pnpm install          # from monorepo root
+pnpm --filter @mintel/seo-engine build
+npx tsx src/test-run.ts   # smoke test (needs API keys in .env)
+```