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

{
  "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