zen-marketing/README.md

# Zen-Marketing MCP Server

> **Status:** 🚧 In Development - Phase 1

AI-powered marketing tools for Claude Desktop, specialized for technical B2B content creation, multi-platform campaigns, and content variation testing.

## What is This?

A fork of the [Zen MCP Server](https://github.com/BeehiveInnovations/zen-mcp-server) optimized for marketing workflows instead of software development. Provides Claude Desktop with specialized tools for:

- **Content Variation** - Generate 5-20 variations for A/B testing
- **Platform Adaptation** - Adapt content across LinkedIn, Twitter, newsletters, blogs
- **Style Enforcement** - Apply writing guidelines automatically
- **SEO Optimization** - WordPress-specific SEO workflows
- **Guest Editing** - Edit external content while preserving author voice
- **Fact Verification** - Technical accuracy checking via web search
- **Internal Linking** - Cross-platform content integration strategy
- **Campaign Planning** - Multi-touch campaign mapping

## For Whom?

Solo marketing professionals managing:
- Technical newsletters and educational content
- Multi-platform social media campaigns
- WordPress blogs with SEO requirements
- Guest contributor content
- A/B testing and content experimentation
- B2B SaaS or technical product marketing

## Key Differences from Zen Code

| Zen Code | Zen Marketing |
|----------|---------------|
| Code review, debugging, testing | Content variation, SEO, style guide |
| Software architecture analysis | Campaign planning, voice analysis |
| Development workflows | Marketing workflows |
| Technical accuracy for code | Technical accuracy for content |
| GitHub/git integration | WordPress/platform integration |

## Tools (Planned)

### Simple Tools (Fast, Single-Shot)
- `contentvariant` - Generate 5-20 variations for testing
- `platformadapt` - Cross-platform content adaptation
- `subjectlines` - Email subject line generation
- `factcheck` - Technical fact verification

### Workflow Tools (Multi-Step)
- `styleguide` - Writing style enforcement
- `seooptimize` - WordPress SEO optimization
- `guestedit` - Guest content editing
- `linkstrategy` - Internal linking strategy
- `voiceanalysis` - Voice extraction and validation
- `campaignmap` - Campaign planning

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

## Models

**Primary Models:**
- **Gemini 2.5 Pro** - Analytical and strategic work
- **Gemini Flash** - Fast bulk generation
- **Minimax M2** - Creative content generation

**Fallback:**
- OpenRouter (if configured)

## Quick Start

> **Note:** Not yet functional - see [PLAN.md](PLAN.md) for implementation roadmap

```bash
# Clone and setup
git clone [repo-url]
cd zen-marketing
./run-server.sh

# Configure Claude Desktop (~/.claude.json)
{
  "mcpServers": {
    "zen-marketing": {
      "command": "/home/ben/mcp/zen-marketing/.venv/bin/python",
      "args": ["/home/ben/mcp/zen-marketing/server.py"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "OPENROUTER_API_KEY": "your-key",
        "DEFAULT_MODEL": "gemini-2.5-pro"
      }
    }
  }
}

# Restart Claude Desktop
```

## Example Usage

```
# Generate subject line variations
"Use zen-marketing contentvariant to generate 15 subject lines for an HVAC newsletter about PCB diagnostics. Test angles: technical curiosity, contrarian, knowledge gap, urgency."

# Adapt content across platforms
"Use zen-marketing platformadapt to take this blog post intro and create versions for LinkedIn (1300 chars), Twitter (280), Instagram (2200), and newsletter."

# Enforce writing style
"Use zen-marketing styleguide to check this draft for em-dashes, 'This isn't X, it's Y' constructions, and ensure direct affirmative statements."

# SEO optimize
"Use zen-marketing seooptimize to create SEO title under 60 chars, excerpt under 156 chars, and suggest WordPress tags for this article about HVAC voltage regulation."
```

## Development Status

### Phase 1: Foundation (Current)
- [x] Create directory structure
- [x] Write implementation plan
- [x] Create development guide
- [ ] Copy core architecture from zen-mcp-server
- [ ] Configure minimax provider
- [ ] Test basic functionality

### Phase 2: Simple Tools (Next)
- [ ] Implement `contentvariant`
- [ ] Implement `subjectlines`
- [ ] Implement `platformadapt`
- [ ] Implement `factcheck`

See [PLAN.md](PLAN.md) for complete roadmap.

## Documentation

- **[PLAN.md](PLAN.md)** - Detailed implementation plan with tool designs
- **[CLAUDE.md](CLAUDE.md)** - Development guide for contributors
- **[Project Memories](PLAN.md#project-overview)** - Real-world usage examples

## Architecture

Based on Zen MCP Server's proven architecture:
- **Conversation continuity** via `continuation_id`
- **Multi-model orchestration** (Gemini, Minimax, OpenRouter)
- **Simple tools** for fast iteration
- **Workflow tools** for multi-step processes
- **Web search integration** for current information
- **File handling** for content and brand assets

## License

Apache 2.0 License (inherited from Zen MCP Server)

## Acknowledgments

Built on the foundation of:
- [Zen MCP Server](https://github.com/BeehiveInnovations/zen-mcp-server) by Fahad Gilani
- [Model Context Protocol](https://modelcontextprotocol.com) by Anthropic
- [Claude Desktop](https://claude.ai/download) - AI interface

---

**Status:** Planning phase complete, ready for implementation
**Next:** Start new Claude session in `~/mcp/zen-marketing/` to begin Phase 1