From 95b4138f87b213f03c3c891c1cd8b69bd6fe8f75 Mon Sep 17 00:00:00 2001 From: garfieldheron Date: Thu, 4 Jun 2026 12:17:26 -0400 Subject: [PATCH] docs(spv): add marketing intelligence specs and lodge-first launch design MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- spv/lodge-first-launch-design.md | 135 ++++++++++++ spv/marketing-intelligence-features.md | 291 +++++++++++++++++++++++++ 2 files changed, 426 insertions(+) create mode 100644 spv/lodge-first-launch-design.md create mode 100644 spv/marketing-intelligence-features.md diff --git a/spv/lodge-first-launch-design.md b/spv/lodge-first-launch-design.md new file mode 100644 index 0000000..6e2a4de --- /dev/null +++ b/spv/lodge-first-launch-design.md @@ -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` diff --git a/spv/marketing-intelligence-features.md b/spv/marketing-intelligence-features.md new file mode 100644 index 0000000..4044f58 --- /dev/null +++ b/spv/marketing-intelligence-features.md @@ -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, // 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, + 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, // 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