zen-marketing/PLAN.md

# Zen-Marketing MCP Server - Implementation Plan

## Project Overview

A specialized MCP server for Claude Desktop focused on marketing workflows, derived from the Zen MCP Server codebase. Designed for solo marketing professionals working in technical B2B content, particularly HVAC/technical education and software marketing.

**Target User Profile:** Marketing professional managing:
- Technical newsletters with guest contributors
- Multi-platform social media campaigns
- Educational content with SEO optimization
- A/B testing and content variation generation
- WordPress content management with internal linking
- Brand voice consistency across channels

## Core Principles

1. **Variation at Scale**: Generate 5-20 variations of content for A/B testing
2. **Platform Intelligence**: Understand character limits, tone, and best practices per platform
3. **Technical Accuracy**: Verify facts via web search before publishing
4. **Voice Preservation**: Maintain authentic voices (guest authors, brand persona)
5. **Cross-Platform Integration**: Connect content across blog, social, email, video
6. **Style Enforcement**: Apply specific writing guidelines automatically

## Planned Tools

### 1. `contentvariant` (Simple Tool)
**Purpose:** Rapid generation of multiple content variations for testing

**Real-world use case from project memory:**
- "Generate 15 email subject line variations testing different angles: technical curiosity, contrarian statements, FOMO, educational value"
- "Create 10 LinkedIn post variations of this announcement, mixing lengths and hooks"

**Key features:**
- Generate 5-20 variations in one call
- Specify variation dimensions (tone, length, hook, CTA placement)
- Fast model (gemini-flash) for speed
- Output formatted for easy copy-paste testing

**Parameters:**
- `content` (str): Base content to vary
- `variation_count` (int): Number of variations (default 10)
- `variation_types` (list): Types to vary - "tone", "length", "hook", "structure", "cta"
- `platform` (str): Target platform for context
- `constraints` (str): Character limits, style requirements

**Model:** gemini-flash (fast, cost-effective for bulk generation)
**Temperature:** 0.8 (creative variation while maintaining message)

---

### 2. `platformadapt` (Simple Tool)
**Purpose:** Adapt single content piece across multiple social platforms

**Real-world use case from project memory:**
- "Take this blog post intro and create versions for LinkedIn (1300 chars), Twitter (280 chars), Instagram caption (2200 chars), Facebook (500 chars), and Bluesky (300 chars)"

**Key features:**
- Single source → multiple platform versions
- Respects character limits automatically
- Platform-specific best practices (hashtags, tone, formatting)
- Preserves core message across adaptations

**Parameters:**
- `source_content` (str): Original content
- `source_platform` (str): Where content originated
- `target_platforms` (list): ["linkedin", "twitter", "instagram", "facebook", "bluesky"]
- `preserve_urls` (bool): Keep links intact vs. adapt
- `brand_voice` (str): Voice guidelines to maintain

**Model:** minimax/minimax-m2 (creative adaptations)
**Temperature:** 0.7

---

### 3. `subjectlines` (Simple Tool)
**Purpose:** Specialized tool for email subject line generation with angle testing

**Real-world use case from project memory:**
- "Generate subject lines testing: technical curiosity hook, contrarian/provocative angle, knowledge gap emphasis, urgency/timeliness, insider knowledge positioning"

**Key features:**
- Generates 15-25 subject lines by default
- Groups by psychological angle/hook
- Includes A/B testing rationale for each
- Character count validation (under 60 chars optimal)
- Emoji suggestions (optional)

**Parameters:**
- `email_topic` (str): Main topic/content
- `target_audience` (str): Who receives this
- `angles_to_test` (list): Psychological hooks to explore
- `include_emoji` (bool): Add emoji options
- `preview_text` (str): Optional - generate matching preview text

**Model:** gemini-flash (fast generation, creative but focused)
**Temperature:** 0.8

---

### 4. `styleguide` (Workflow Tool)
**Purpose:** Enforce specific writing guidelines and polish content

**Real-world use case from project memory:**
- "Check this content for: em-dashes (remove), 'This isn't X, it's Y' constructions (rewrite), semantic variety in paragraph structure, direct affirmative statements instead of negations"

**Key features:**
- Multi-step workflow: detection → flagging → rewriting → validation
- Tracks style violations with severity
- Provides before/after comparisons
- Custom rule definitions

**Workflow steps:**
1. Analyze content for style violations
2. Flag issues with line numbers and severity
3. Generate corrected version
4. Validate improvements

**Parameters:**
- `content` (str): Content to check
- `rules` (list): Style rules to enforce
- `rewrite_violations` (bool): Auto-fix vs. flag only
- `preserve_technical_terms` (bool): Don't change HVAC/technical terminology

**Common rules (from project memory):**
- No em-dashes (use periods or semicolons)
- No "This isn't X, it's Y" constructions
- Direct affirmative statements over negations
- Semantic variety in paragraph openings
- No clichéd structures
- Concrete metrics over abstract claims

**Model:** gemini-2.5-pro (analytical precision)
**Temperature:** 0.3 (consistency enforcement)

---

### 5. `seooptimize` (Workflow Tool)
**Purpose:** Comprehensive SEO optimization for WordPress content

**Real-world use case from project memory:**
- "Create SEO title under 60 chars, excerpt under 156 chars, suggest 5-7 WordPress tags, internal linking opportunities to foundational content"

**Workflow steps:**
1. Analyze content for primary keywords and topics
2. Generate SEO title (under 60 chars)
3. Create meta description/excerpt (under 156 chars)
4. Suggest WordPress tags (5-10)
5. Identify internal linking opportunities
6. Validate character limits and keyword density

**Parameters:**
- `content` (str): Full article content
- `existing_tags` (list): Current WordPress tag library
- `target_keywords` (list): Keywords to optimize for
- `internal_links_context` (str): Description of site structure for linking
- `platform` (str): "wordpress" (default), "ghost", "medium"

**Model:** gemini-2.5-pro (analytical, search-aware)
**Temperature:** 0.4
**Web search:** Enabled for keyword research

---

### 6. `guestedit` (Workflow Tool)
**Purpose:** Edit guest content while preserving author expertise and voice

**Real-world use case from project memory:**
- "Edit this guest article on PCB components: preserve technical authority, add key takeaways section, suggest internal links to foundational content, enhance educational flow, maintain expert's voice"

**Workflow steps:**
1. Analyze guest author's voice and technical expertise level
2. Identify areas needing clarification vs. areas to preserve
3. Generate educational enhancements (key takeaways, callouts)
4. Suggest internal linking without fabricating URLs
5. Validate technical accuracy via web search
6. Present edits with rationale

**Parameters:**
- `guest_content` (str): Original article
- `author_name` (str): Guest author for voice reference
- `expertise_level` (str): "expert", "practitioner", "educator"
- `enhancements_needed` (list): ["key_takeaways", "internal_links", "clarity", "seo"]
- `site_context` (str): Description of broader content ecosystem
- `verify_technical` (bool): Use web search for fact-checking

**Model:** gemini-2.5-pro (analytical + creative balance)
**Temperature:** 0.5
**Web search:** Enabled for technical verification

---

### 7. `linkstrategy` (Workflow Tool)
**Purpose:** Internal linking and cross-platform content integration strategy

**Real-world use case from project memory:**
- "Find opportunities to link this advanced PCB article to foundational HVAC knowledge. Connect blog with related podcast episode, Instagram post, and YouTube video from our content database."

**Workflow steps:**
1. Analyze content topics and technical depth
2. Identify prerequisite concepts needing internal links
3. Search for related content across platforms (blog, podcast, video, social)
4. Generate linking strategy with anchor text suggestions
5. Validate URLs against actual content (no fabrication)
6. Create cross-platform promotion plan

**Parameters:**
- `primary_content` (str): Main piece to link from/to
- `content_type` (str): "blog", "newsletter", "social_post"
- `available_platforms` (list): ["blog", "podcast", "youtube", "instagram"]
- `technical_depth` (str): "foundational", "intermediate", "advanced"
- `verify_links` (bool): Validate URLs exist before suggesting

**Model:** gemini-2.5-pro (analytical, relationship mapping)
**Temperature:** 0.4
**Web search:** Enabled for content discovery

---

### 8. `factcheck` (Simple Tool)
**Purpose:** Quick technical fact verification via web search

**Real-world use case from project memory:**
- "Verify these technical claims about voltage regulation chains in HVAC PCBs"
- "Check if this White-Rodgers universal control model number and compatibility claims are accurate"

**Key features:**
- Web search-powered verification
- Cites sources for each claim
- Flags unsupported or questionable statements
- Quick turnaround for pre-publish checks

**Parameters:**
- `content` (str): Content with claims to verify
- `technical_domain` (str): "hvac", "software", "general"
- `claim_type` (str): "product_specs", "technical_process", "statistics", "general"
- `confidence_threshold` (str): "high_confidence_only", "balanced", "comprehensive"

**Model:** gemini-2.5-pro (search-augmented, analytical)
**Temperature:** 0.2 (precision for facts)
**Web search:** Required (core functionality)

---

### 9. `voiceanalysis` (Workflow Tool)
**Purpose:** Extract and codify brand/author voice for consistency

**Real-world use case from project memory:**
- "Analyze these 10 pieces of Gary McCreadie's content to extract voice patterns, then check if this new draft matches his authentic teaching voice"

**Workflow steps:**
1. Analyze sample content for voice characteristics
2. Extract patterns: sentence structure, vocabulary, tone markers
3. Create voice profile with examples
4. Compare new content against profile
5. Flag inconsistencies with suggested rewrites
6. Track confidence in voice matching

**Parameters:**
- `sample_content` (list): 5-15 pieces showing authentic voice
- `author_name` (str): Voice owner for reference
- `new_content` (str): Content to validate against voice
- `voice_aspects` (list): ["tone", "vocabulary", "structure", "educational_style"]
- `generate_profile` (bool): Create reusable voice profile

**Model:** gemini-2.5-pro (pattern analysis)
**Temperature:** 0.3

---

### 10. `campaignmap` (Workflow Tool)
**Purpose:** Map content campaign across multiple touchpoints

**Real-world use case from project memory:**
- "Plan content campaign for measureQuick National Championship: social teaser posts, email sequence, on-site promotion, post-event follow-up, blog recap with internal links"

**Workflow steps:**
1. Define campaign goals and timeline
2. Map content across platforms and stages (awareness → consideration → action → retention)
3. Create content calendar with dependencies
4. Generate messaging for each touchpoint
5. Plan cross-promotion and internal linking
6. Set success metrics per channel

**Parameters:**
- `campaign_goal` (str): Primary objective
- `timeline_days` (int): Campaign duration
- `platforms` (list): Channels to use
- `content_pillars` (list): Key messages to reinforce
- `target_audience` (str): Audience description
- `existing_assets` (list): Content to repurpose

**Model:** gemini-2.5-pro (strategic planning)
**Temperature:** 0.6

---

## Tool Architecture

### Simple Tools (3)
Fast, single-shot interactions for rapid iteration:
- `contentvariant` - Bulk variation generation
- `platformadapt` - Cross-platform adaptation
- `subjectlines` - Email subject line testing
- `factcheck` - Quick verification

### Workflow Tools (6)
Multi-step systematic processes:
- `styleguide` - Style enforcement workflow
- `seooptimize` - Comprehensive SEO process
- `guestedit` - Guest content editing workflow
- `linkstrategy` - Internal linking analysis
- `voiceanalysis` - Voice extraction and validation
- `campaignmap` - Multi-touch campaign planning

### Keep from Original Zen
- `chat` - General brainstorming
- `thinkdeep` - Deep strategic thinking
- `planner` - Project planning

## Model Assignment Strategy

**Primary Models:**
- **minimax/minimax-m2**: Creative content generation (contentvariant, platformadapt)
- **google/gemini-2.5-pro**: Analytical and strategic work (seooptimize, guestedit, linkstrategy, voiceanalysis, campaignmap, styleguide, factcheck)
- **google/gemini-flash**: Fast bulk generation (subjectlines)

**Fallback Chain:**
1. Configured provider (minimax or gemini)
2. OpenRouter (if API key present)
3. Error (no fallback to Anthropic to avoid confusion)

## Configuration Defaults

```json
{
  "mcpServers": {
    "zen-marketing": {
      "command": "/home/ben/mcp/zen-marketing/.venv/bin/python",
      "args": ["/home/ben/mcp/zen-marketing/server.py"],
      "env": {
        "OPENROUTER_API_KEY": "your-key",
        "DEFAULT_MODEL": "gemini-2.5-pro",
        "FAST_MODEL": "gemini-flash",
        "CREATIVE_MODEL": "minimax-m2",
        "DISABLED_TOOLS": "analyze,refactor,testgen,secaudit,docgen,tracer,precommit,codereview,debug,consensus,challenge",
        "ENABLE_WEB_SEARCH": "true",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

## Tool Temperature Defaults

| Tool | Temperature | Rationale |
|------|-------------|-----------|
| contentvariant | 0.8 | High creativity for diverse variations |
| platformadapt | 0.7 | Creative while maintaining message |
| subjectlines | 0.8 | Explore diverse psychological angles |
| styleguide | 0.3 | Precision for consistency |
| seooptimize | 0.4 | Balanced analytical + creative |
| guestedit | 0.5 | Balance preservation + enhancement |
| linkstrategy | 0.4 | Analytical relationship mapping |
| factcheck | 0.2 | Precision for accuracy |
| voiceanalysis | 0.3 | Pattern recognition precision |
| campaignmap | 0.6 | Strategic creativity |

## Differences from Zen Code

### What's Different
1. **Content-first**: Tools designed for writing, not coding
2. **Variation generation**: Built-in support for A/B testing at scale
3. **Platform awareness**: Character limits, formatting, best practices per channel
4. **Voice preservation**: Tools explicitly maintain author authenticity
5. **SEO native**: WordPress-specific optimization built in
6. **Verification emphasis**: Web search for fact-checking integrated
7. **No code tools**: Remove debug, codereview, precommit, refactor, testgen, secaudit, tracer

### What's Kept
1. **Conversation continuity**: `continuation_id` across tools
2. **Multi-model orchestration**: Different models for different tasks
3. **Workflow architecture**: Multi-step systematic processes
4. **File handling**: Attach content files, brand guidelines
5. **Image support**: Analyze screenshots, brand assets
6. **Thinking modes**: Control depth vs. cost
7. **Web search**: Current information access

### What's Enhanced
1. **Bulk operations**: Generate 5-20 variations in one call
2. **Style enforcement**: Custom writing rules
3. **Cross-platform thinking**: Native multi-channel workflows
4. **Technical verification**: Domain-specific fact-checking

## Implementation Phases

### Phase 1: Foundation (Week 1)
- Fork Zen MCP Server codebase
- Remove code-specific tools
- Configure minimax and gemini providers
- Update system prompts for marketing context
- Basic testing with chat tool

### Phase 2: Simple Tools (Week 2)
- Implement `contentvariant`
- Implement `platformadapt`
- Implement `subjectlines`
- Implement `factcheck`
- Test variation generation workflows

### Phase 3: Workflow Tools (Week 3-4)
- Implement `styleguide`
- Implement `seooptimize`
- Implement `guestedit`
- Implement `linkstrategy`
- Test multi-step workflows

### Phase 4: Advanced Features (Week 5)
- Implement `voiceanalysis`
- Implement `campaignmap`
- Add voice profile storage
- Test complex campaign workflows

### Phase 5: Polish & Documentation (Week 6)
- User documentation
- Example workflows
- Configuration guide
- Testing with real project memories

## Success Metrics

1. **Variation Quality**: Can generate 10+ usable subject lines in one call
2. **Platform Accuracy**: Respects character limits and formatting rules
3. **Voice Consistency**: Successfully preserves guest author expertise
4. **SEO Effectiveness**: Generated titles/descriptions pass WordPress SEO checks
5. **Cross-platform Integration**: Correctly maps content across blog/social/email
6. **Fact Accuracy**: Catches technical errors before publication
7. **Speed**: Simple tools respond in <10 seconds, workflow tools in <30 seconds

## File Structure

```
zen-marketing/
├── server.py                 # Main MCP server (adapted from zen)
├── config.py                 # Marketing-specific configuration
├── PLAN.md                   # This file
├── CLAUDE.md                 # Development guide
├── README.md                 # User documentation
├── requirements.txt          # Python dependencies
├── .env.example              # Environment template
├── run-server.sh             # Setup and run script
├── tools/
│   ├── contentvariant.py     # Bulk variation generation
│   ├── platformadapt.py      # Cross-platform adaptation
│   ├── subjectlines.py       # Email subject lines
│   ├── styleguide.py         # Writing style enforcement
│   ├── seooptimize.py        # WordPress SEO workflow
│   ├── guestedit.py          # Guest content editing
│   ├── linkstrategy.py       # Internal linking strategy
│   ├── factcheck.py          # Technical verification
│   ├── voiceanalysis.py      # Voice extraction/validation
│   ├── campaignmap.py        # Campaign planning
│   └── shared/               # Shared utilities from zen
├── providers/
│   ├── gemini.py             # Google Gemini provider
│   ├── minimax.py            # Minimax provider (NEW)
│   ├── openrouter.py         # OpenRouter fallback
│   └── registry.py           # Provider registration
├── systemprompts/
│   ├── contentvariant_prompt.py
│   ├── platformadapt_prompt.py
│   ├── subjectlines_prompt.py
│   ├── styleguide_prompt.py
│   ├── seooptimize_prompt.py
│   ├── guestedit_prompt.py
│   ├── linkstrategy_prompt.py
│   ├── factcheck_prompt.py
│   ├── voiceanalysis_prompt.py
│   └── campaignmap_prompt.py
└── tests/
    ├── test_contentvariant.py
    ├── test_platformadapt.py
    └── ...
```

## Development Priorities

### High Priority (Essential)
1. `contentvariant` - Most used feature from project memories
2. `subjectlines` - Specific workflow mentioned multiple times
3. `platformadapt` - Core multi-channel need
4. `styleguide` - Explicit writing rules enforcement
5. `factcheck` - Technical accuracy verification

### Medium Priority (Important)
6. `seooptimize` - WordPress-specific SEO needs
7. `guestedit` - Guest content workflow
8. `linkstrategy` - Internal linking mentioned frequently

### Lower Priority (Nice to Have)
9. `voiceanalysis` - Advanced voice preservation
10. `campaignmap` - Strategic planning (can use planner tool initially)

## Next Steps

1. Create CLAUDE.md with development guide for zen-marketing
2. Start new session in ~/mcp/zen-marketing/ directory
3. Begin Phase 1 implementation:
   - Copy core architecture from zen-mcp-server
   - Configure minimax provider
   - Remove code-specific tools
   - Test with basic chat functionality
4. Implement Phase 2 simple tools starting with `contentvariant`