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
135
spv/lodge-first-launch-design.md
Normal file
135
spv/lodge-first-launch-design.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# Marketing Intelligence Co-Pilot — Lodge-First Launch
|
||||
|
||||
**Date:** 2026-06-04
|
||||
**Session:** /office-hours
|
||||
**Status:** APPROVED
|
||||
**Phase:** A → C → B
|
||||
|
||||
---
|
||||
|
||||
## Pull Analysis
|
||||
|
||||
### Real Customer Discovery
|
||||
|
||||
| Customer | Role | Signal |
|
||||
|----------|------|--------|
|
||||
| Alex | Mortgage broker / agent | Asked directly for marketing tools |
|
||||
| Alex Ferrari | Mortgage reseller (from banks) | Needs promotion tools for his pipeline |
|
||||
| Paul — CMGBank / CMGFI | Board level | Evaluating Opal alternatives — AI token cost too high |
|
||||
| The lodge | Fraternal network — brokers, insurance, investors | Members watching; if Alex uses it at July meeting, network converts |
|
||||
|
||||
### The Business Model in One Sentence
|
||||
|
||||
> Alex and the lodge are the proof. CMG is the check.
|
||||
|
||||
Bottom-up enterprise:
|
||||
1. Alex validates it this week
|
||||
2. Lodge network sees it live in July
|
||||
3. Paul sees a room already using it → writes the check
|
||||
|
||||
### Why CMG Is Replacing Opal
|
||||
|
||||
Opal = $15k+/yr. Pain: AI token usage is too expensive. Paul (board) wants to
|
||||
internalize the capability. SquareMCP is the internal alternative.
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Mortgage brokers, insurance agents, and financial services professionals need
|
||||
marketing tools to compete but can't afford or justify enterprise platforms.
|
||||
Individual brokers like Alex have no marketing team. They need a co-pilot.
|
||||
|
||||
SquareMCP replaces Opal for CMGBank AND becomes the daily co-pilot for Alex
|
||||
and the lodge network — at a fraction of the cost.
|
||||
|
||||
---
|
||||
|
||||
## Narrowest Wedge
|
||||
|
||||
**The Monday Morning Brief** — weekly automated email Alex receives:
|
||||
- What competitors posted last week
|
||||
- 5 ready-to-post mortgage content drafts
|
||||
- Twitter performance from his previous posts
|
||||
|
||||
He brings it to the lodge in July. The room asks how to get it. Paul signs.
|
||||
|
||||
---
|
||||
|
||||
## Build Order: A → C → B
|
||||
|
||||
### Phase A — Weeks 1-2 (ship now)
|
||||
|
||||
Three tools. One new API key (Serper or Brave Search — **get today**).
|
||||
|
||||
| Tool | Signature | Notes |
|
||||
|------|-----------|-------|
|
||||
| `create_faq` | `(topic, source_url?) → FAQ[]` | Mortgage Q&A from broker's site |
|
||||
| `research_competitor` | `(name_or_domain) → CompetitorProfile` | Web search + Twitter |
|
||||
| `generate_report` | `(type, params) → Markdown` | Emails brief via SMTP |
|
||||
| `optimize_metadata` | `(source_url) → {title, meta, og, keywords}` | OG/meta tag suggestions |
|
||||
|
||||
New files: `src/clients/web-crawler.ts`, `src/clients/web-search.ts`
|
||||
|
||||
### Phase C — Weeks 3-4
|
||||
|
||||
Cron workflow. Alex registers email once. Brief arrives Monday 7am.
|
||||
Twitter-only performance in weeks 3-4. IG/FB added in Phase B.
|
||||
Alex's UX: email delivery only — no login, no dashboard.
|
||||
|
||||
### Phase B — Post-July (CMG-funded)
|
||||
|
||||
Full dashboard, full workflow engine, LinkedIn analytics, multi-tenant.
|
||||
Apply for LinkedIn Marketing API partner approval **now**.
|
||||
|
||||
---
|
||||
|
||||
## Feature Timeline
|
||||
|
||||
| Week | Feature | Dependencies |
|
||||
|------|---------|-------------|
|
||||
| 1 | Create FAQs | web-crawler.ts |
|
||||
| 1 | Optimize Metadata | web-crawler.ts |
|
||||
| 1-2 | Generate Reports | existing tools |
|
||||
| 2 | Research Competitors | web-search.ts + Serper/Brave key |
|
||||
| 3-4 | Monday Morning Brief (cron) | all above + workflow_subscriptions table |
|
||||
| 4 | Monitor Campaigns (Twitter) | Twitter analytics methods |
|
||||
| 5 | SEO Audits | Cheerio |
|
||||
| 5-6 | Monitor Campaigns (IG/FB) | Platform analytics APIs |
|
||||
| Post-July | Dashboard + Workflow Engine | CMG funding |
|
||||
| Post-July | LinkedIn Analytics | Partner approval |
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. What platforms does Alex post on today?
|
||||
2. Alex's top 3 competitor brokers geographically?
|
||||
3. Paul's specific CMG campaign for mid-July?
|
||||
4. Lodge sector breakdown?
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Alex runs FAQs + competitor research + one report by end of Week 2
|
||||
- [ ] Alex receives first Monday Morning Brief by Week 4
|
||||
- [ ] Alex brings it to July lodge meeting
|
||||
- [ ] 3+ lodge members express interest
|
||||
- [ ] Paul greenlights SquareMCP as Opal alternative by end of July
|
||||
|
||||
---
|
||||
|
||||
## The Assignment
|
||||
|
||||
**This week:** 30-minute call with Alex. Run `create_faq` and
|
||||
`research_competitor` with him live. Generate the report. Send it.
|
||||
Watch his reaction. That's the product validation.
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- `spv/marketing-intelligence-features.md` — original feature spec
|
||||
- `~/.gstack/projects/garfield-hermes-mcp/garfieldheron-main-design-20260604-110738.md` — full gstack design doc
|
||||
- Vault: `SquareMCP/2026-06-04-marketing-intelligence-lodge-first.md`
|
||||
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