hermes-mcp/spv/marketing-intelligence-features.md

# Marketing Intelligence Features — Hermes MCP

**Status:** Spec / Pre-build  
**Date:** 2026-06-03  
**Scope:** Seven new capabilities layered onto the existing Hermes MCP tool surface

---

## Context

Hermes MCP is a multi-tenant MCP server exposing communication tools across email (IMAP/SMTP), social (Twitter, LinkedIn, Instagram, Facebook, TikTok, Snapchat), and messaging (WhatsApp, Telegram, Discord, Slack). The server is live on Kubernetes, uses PostgreSQL + Redis, and already has webhook ingestion, audit logging, and per-customer billing/usage tracking.

This spec adds a **Marketing Intelligence layer** — tools that turn Hermes into an autonomous marketing co-pilot, not just a send/receive relay.

---

## Features

### 1. Monitor Campaigns (`monitor_campaign`)

**What it does:** Pulls engagement metrics from all connected platforms for a given campaign tag or time window and returns a unified snapshot.

**Tool signature:**
```ts
monitor_campaign({
  campaign_tag?: string,      // optional label to filter posts/tweets by hashtag or ref
  since_days?: number,        // lookback window (default 7)
  platforms?: string[],       // filter to specific platforms
  customer_id: string
})
```

**Data sources:**
- Twitter: `GET /2/tweets/:id` with `public_metrics` expansion
- LinkedIn: Marketing Developer Platform `/v2/organizationalEntityShareStatistics`
- Instagram: Graph API `/media?fields=insights`
- Facebook: Page Insights API `/insights`
- Email: open/click tracking via pixel + redirect links (new infrastructure, see §7)

**Returns:** Unified `CampaignSnapshot` — impressions, engagements, clicks, conversions per platform, delta vs prior window.

**New infrastructure needed:**
- Analytics-fetch methods on each platform client
- `CampaignSnapshot` type + DB table for historical snapshots
- LinkedIn Marketing API scope (`r_organization_social_feed`) — requires partner approval

---

### 2. SEO Audits (`audit_seo`)

**What it does:** Crawls a URL and returns an on-page SEO report with a score and actionable recommendations.

**Tool signature:**
```ts
audit_seo({
  url: string,
  include_external_metrics?: boolean,  // call Ahrefs/SEMrush if configured
  customer_id: string
})
```

**Checks performed:**
- Title tag (length, keyword presence)
- Meta description (length, CTR signals)
- H1/H2 structure
- Image alt text coverage
- Canonical tag
- Schema.org markup presence
- Page load time (via HTTP timing)
- Internal link structure
- Mobile viewport meta
- Open Graph tags

**Returns:** `SEOReport` with score (0–100), per-check pass/fail, and fix recommendations.

**New infrastructure needed:**
- `src/clients/web-crawler.ts` — fetch + parse with Cheerio
- Optional: Ahrefs/SEMrush API client for domain authority, backlink count
- Rate-limit crawler to respect `robots.txt`

---

### 3. Generate Reports (`generate_report`)

**What it does:** Aggregates data across tools into a structured Markdown or JSON report, optionally saving to Obsidian.

**Tool signature:**
```ts
generate_report({
  report_type: 'campaign' | 'seo' | 'competitor' | 'weekly_summary',
  params: Record<string, unknown>,   // forwarded to underlying tools
  output: 'markdown' | 'json',
  save_to_obsidian?: boolean,
  customer_id: string
})
```

**Implementation:** Orchestration wrapper — calls `monitor_campaign`, `audit_seo`, `research_competitor` etc., stitches results into a template, optionally calls `appendToNote` (Obsidian client already exists).

**New infrastructure needed:**
- `src/reports/` — template engine per report type
- No new external API integrations

---

### 4. Research Competitors (`research_competitor`)

**What it does:** Given a competitor name or domain, fans out across web search and social platforms to build a profile.

**Tool signature:**
```ts
research_competitor({
  name: string,
  domain?: string,
  platforms?: string[],
  customer_id: string
})
```

**Data sources:**
- Twitter: `search_tweets` (already implemented) — recent posts, engagement patterns
- LinkedIn: company search
- Web search: Brave Search API or Serper API for news, blog posts, backlinks
- Facebook: public page lookup
- SEO snapshot: `audit_seo` on their homepage

**Returns:** `CompetitorProfile` — social presence, posting cadence, top content, estimated traffic tier.

**New infrastructure needed:**
- `src/clients/web-search.ts` — Brave Search or Serper API (single endpoint, lightweight)
- LinkedIn company search method

---

### 5. Create FAQs (`create_faq`)

**What it does:** Given a topic, URL, or set of notes, generates a structured FAQ document.

**Tool signature:**
```ts
create_faq({
  topic?: string,
  source_url?: string,
  source_note?: string,        // Obsidian note name
  count?: number,              // number of Q&A pairs (default 10)
  save_to_obsidian?: boolean,
  customer_id: string
})
```

**Implementation:**
1. If `source_url` provided: fetch + extract text via web crawler
2. If `source_note` provided: `getNote` from Obsidian
3. Pass content to Claude via internal generation call
4. Return structured `FAQ[]` with question, answer, category
5. Optionally `appendToNote` to Obsidian

**New infrastructure needed:** None — uses existing web crawler (from §2) + Obsidian client. Pure prompt orchestration.

---

### 6. Optimize Metadata (`optimize_metadata`)

**What it does:** Analyzes a page or content block and returns SEO-optimized title, meta description, OG tags, and keyword suggestions.

**Tool signature:**
```ts
optimize_metadata({
  source_url?: string,
  content?: string,            // raw text if no URL
  target_keyword?: string,
  customer_id: string
})
```

**Returns:**
```ts
{
  title: string,               // ≤60 chars, keyword-first
  meta_description: string,   // ≤160 chars, includes CTA
  og_title: string,
  og_description: string,
  keywords: string[],          // 5–10 terms
  score_before?: number,       // from audit_seo if URL provided
  score_after_estimate: number
}
```

**New infrastructure needed:** None beyond web crawler. Prompt-driven generation.

---

### 7. Execute Multi-Step Workflows (`run_workflow`)

**What it does:** Executes a saved workflow definition — an ordered sequence of Hermes tool calls with conditional branching, retries, and result passing between steps.

**Tool signatures:**
```ts
// Define a workflow
save_workflow({
  name: string,
  steps: WorkflowStep[],
  trigger?: 'manual' | 'cron' | 'webhook',
  cron_expr?: string,
  customer_id: string
})

// Execute
run_workflow({
  workflow_id: string,
  input?: Record<string, unknown>,
  customer_id: string
})

// Status
get_workflow_run({
  run_id: string,
  customer_id: string
})
```

**`WorkflowStep` schema:**
```ts
{
  id: string,
  tool: string,                          // any Hermes tool name
  params: Record<string, unknown>,       // supports {{step.id.output.field}} refs
  condition?: string,                    // JSONata expression for skip/branch
  on_error: 'abort' | 'continue' | 'retry',
  retry_max?: number
}
```

**Implementation:**
- `src/workflows/engine.ts` — step executor with result context threading
- `src/workflows/scheduler.ts` — cron trigger using existing Redis + node-cron
- `workflows` table in PostgreSQL — definition + run history
- Webhook trigger integrates with existing `webhook-router.ts`

**Example workflow — "Weekly Competitor Report":**
```json
[
  { "id": "research", "tool": "research_competitor", "params": { "name": "{{input.competitor}}" } },
  { "id": "seo",      "tool": "audit_seo",           "params": { "url": "{{research.domain}}" } },
  { "id": "report",   "tool": "generate_report",     "params": { "report_type": "competitor", "save_to_obsidian": true } },
  { "id": "notify",   "tool": "slack_send_message",  "params": { "channel": "{{input.slack_channel}}", "text": "{{report.summary}}" } }
]
```

**New infrastructure needed:**
- `src/workflows/` module (engine + scheduler + DB schema)
- `workflows` + `workflow_runs` Postgres tables
- Cron management API

---

## Dependency Map

```
run_workflow
  └── any tool, including:
        monitor_campaign    ← platform analytics methods (new)
        audit_seo           ← web-crawler.ts (new)
        research_competitor ← web-search.ts (new) + audit_seo
        generate_report     ← orchestration over above
        create_faq          ← web-crawler.ts + Obsidian (existing)
        optimize_metadata   ← web-crawler.ts + prompt
```

Shared new infrastructure: `web-crawler.ts`, `web-search.ts`, analytics methods on platform clients, `workflows/` engine.

---

## Build Order

1. `web-crawler.ts` + `web-search.ts` — unblocks SEO, FAQs, metadata, competitor research
2. `audit_seo` + `optimize_metadata` — lowest risk, no auth needed
3. `create_faq` — pure orchestration once crawler exists
4. `research_competitor` — adds web search client
5. `monitor_campaign` — requires platform analytics API scopes
6. `generate_report` — aggregation wrapper once data tools exist
7. `run_workflow` engine — highest leverage, builds last when all tools are stable

---

## Out of Scope (this spec)

- Email open/click tracking (pixel infrastructure is a separate project)
- LinkedIn Marketing API partner approval process
- CMS write-back for metadata optimization
- A/B testing engine