yuukiii/hermes-mcp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(spv): add marketing intelligence specs and lodge-first launch design

Browse Source 
- 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
2026-06-04 12:17:26 -04:00
parent 2bb1a2db60
commit 95b4138f87
2 changed files with 426 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
spv/lodge-first-launch-design.md Normal file
View 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
View 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