docs(spv): add marketing intelligence specs and lodge-first launch design
- spv/marketing-intelligence-features.md — full 7-feature technical spec with build order, dependency map, and tool signatures - spv/lodge-first-launch-design.md — approved office hours design doc; Phase A→C→B sequencing targeting Alex/lodge July demo and CMG Opal replacement; includes pull analysis and success criteria Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
garfieldheron
291
spv/marketing-intelligence-features.md
Normal file
291
spv/marketing-intelligence-features.md
Normal file
@@ -0,0 +1,291 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user