Marc Mintel
ded9da7d32
Some checks failed
Monorepo Pipeline / ⚡ Prioritize Release (push) Successful in 2s
Monorepo Pipeline / 🧪 Test (push) Failing after 51s
Monorepo Pipeline / 🧹 Lint (push) Failing after 2m25s
Monorepo Pipeline / 🏗️ Build (push) Successful in 2m28s
Monorepo Pipeline / 🚀 Release (push) Has been skipped
Monorepo Pipeline / 🐳 Build Gatekeeper (Product) (push) Has been skipped
Monorepo Pipeline / 🐳 Build Build-Base (push) Has been skipped
Monorepo Pipeline / 🐳 Build Production Runtime (push) Has been skipped
124 lines
5.1 KiB
Markdown
124 lines
5.1 KiB
Markdown
# @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)
|
|
```
|