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:

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:

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:

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:

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:

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:

optimize_metadata({
  source_url?: string,
  content?: string,            // raw text if no URL
  target_keyword?: string,
  customer_id: string
})

Returns:

{
  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:

// 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:

{
  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":

[
  { "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