zen-marketing/CLAUDE.md

# Claude Development Guide for Zen-Marketing MCP Server

This file contains essential commands and workflows for developing the Zen-Marketing MCP Server - a specialized marketing-focused fork of Zen MCP Server.

## Project Context

**What is Zen-Marketing?**
A Claude Desktop MCP server providing AI-powered marketing tools focused on:
- Content variation generation for A/B testing
- Cross-platform content adaptation
- Writing style enforcement
- SEO optimization for WordPress
- Guest content editing with voice preservation
- Technical fact verification
- Internal linking strategy
- Multi-channel campaign planning

**Target User:** Solo marketing professionals managing technical B2B content, particularly in industries like HVAC, SaaS, and technical education.

**Key Difference from Zen Code:** This is for marketing/content work, not software development. Tools generate content variations, enforce writing styles, and optimize for platforms like LinkedIn, newsletters, and WordPress - not code review or debugging.

## Quick Reference Commands

### Initial Setup

```bash
# Navigate to project directory
cd ~/mcp/zen-marketing

# Copy core files from zen-mcp-server (if starting fresh)
# We'll do this in the new session

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies (once requirements.txt is created)
pip install -r requirements.txt

# Create .env file
cp .env.example .env
# Edit .env with your API keys
```

### Development Workflow

```bash
# Activate environment
source .venv/bin/activate

# Run code quality checks (once implemented)
./code_quality_checks.sh

# Run server locally for testing
python server.py

# View logs
tail -f logs/mcp_server.log

# Run tests
python -m pytest tests/ -v
```

### Claude Desktop Configuration

Add to `~/.claude.json`:

```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-openrouter-key",
        "GEMINI_API_KEY": "your-gemini-key",
        "DEFAULT_MODEL": "gemini-2.5-pro",
        "FAST_MODEL": "gemini-flash",
        "CREATIVE_MODEL": "minimax-m2",
        "ENABLE_WEB_SEARCH": "true",
        "DISABLED_TOOLS": "",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

**After modifying config:** Restart Claude Desktop for changes to take effect.

## Tool Development Guidelines

### Tool Categories

**Simple Tools** (single-shot, fast response):
- Inherit from `SimpleTool` base class
- Focus on speed and iteration
- Examples: `contentvariant`, `platformadapt`, `subjectlines`, `factcheck`
- Use fast models (gemini-flash) when possible

**Workflow Tools** (multi-step processes):
- Inherit from `WorkflowTool` base class
- Systematic step-by-step workflows
- Track progress, confidence, findings
- Examples: `styleguide`, `seooptimize`, `guestedit`, `linkstrategy`

### Temperature Guidelines for Marketing Tools

- **High (0.7-0.8)**: Content variation, creative adaptation
- **Medium (0.5-0.6)**: Balanced tasks, campaign planning
- **Low (0.3-0.4)**: Analytical work, SEO optimization
- **Very Low (0.2)**: Fact-checking, technical verification

### Model Selection Strategy

**Gemini 2.5 Pro** (`gemini-2.5-pro`):
- Analytical and strategic work
- SEO optimization
- Guest editing
- Internal linking analysis
- Voice analysis
- Campaign planning
- Fact-checking

**Gemini Flash** (`gemini-flash`):
- Fast bulk generation
- Subject line creation
- Quick variations
- Cost-effective iterations

**Minimax M2** (`minimax-m2`):
- Creative content generation
- Platform adaptation
- Content repurposing
- Marketing copy variations

### System Prompt Best Practices

Marketing tool prompts should:
1. **Specify output format clearly** (JSON, markdown, numbered list)
2. **Include platform constraints** (character limits, formatting rules)
3. **Emphasize preservation** (voice, expertise, technical accuracy)
4. **Request rationale** (why certain variations work, what to test)
5. **Avoid code terminology** (use "content" not "implementation")

Example prompt structure:
```python
CONTENTVARIANT_PROMPT = """
You are a marketing content strategist specializing in A/B testing and variation generation.

TASK: Generate multiple variations of marketing content for testing different approaches.

OUTPUT FORMAT:
Return variations as numbered list, each with:
1. The variation text
2. The testing angle (what makes it different)
3. Predicted audience response

CONSTRAINTS:
- Maintain core message across variations
- Respect platform character limits if specified
- Preserve brand voice characteristics
- Generate genuinely different approaches, not just word swaps

VARIATION TYPES:
- Hook variations: Different opening angles
- Length variations: Short, medium, long
- Tone variations: Professional, conversational, urgent
- Structure variations: Question, statement, story
- CTA variations: Different calls-to-action
"""
```

## Implementation Phases

### Phase 1: Foundation ✓ (You Are Here)
- [x] Create project directory
- [x] Write implementation plan (PLAN.md)
- [x] Create development guide (CLAUDE.md)
- [ ] Copy core architecture from zen-mcp-server
- [ ] Configure minimax provider
- [ ] Remove code-specific tools
- [ ] Test basic chat functionality

### Phase 2: Simple Tools (Priority: High)
Implementation order based on real-world usage:
1. **`contentvariant`** - Most frequently used (subject lines, social posts)
2. **`subjectlines`** - Specific workflow mentioned in project memories
3. **`platformadapt`** - Multi-channel content distribution
4. **`factcheck`** - Technical accuracy verification

### Phase 3: Workflow Tools (Priority: Medium)
5. **`styleguide`** - Writing rule enforcement (no em-dashes, etc.)
6. **`seooptimize`** - WordPress SEO optimization
7. **`guestedit`** - Guest content editing workflow
8. **`linkstrategy`** - Internal linking and cross-platform integration

### Phase 4: Advanced Features (Priority: Lower)
9. **`voiceanalysis`** - Voice extraction and consistency checking
10. **`campaignmap`** - Multi-touch campaign planning

## Tool Implementation Checklist

For each new tool:

**Code Files:**
- [ ] Create tool file in `tools/` (e.g., `tools/contentvariant.py`)
- [ ] Create system prompt in `systemprompts/` (e.g., `systemprompts/contentvariant_prompt.py`)
- [ ] Create test file in `tests/` (e.g., `tests/test_contentvariant.py`)
- [ ] Register tool in `server.py`

**Tool Class Requirements:**
- [ ] Inherit from `SimpleTool` or `WorkflowTool`
- [ ] Implement `get_name()` - tool name
- [ ] Implement `get_description()` - what it does
- [ ] Implement `get_system_prompt()` - behavior instructions
- [ ] Implement `get_default_temperature()` - creativity level
- [ ] Implement `get_model_category()` - FAST_RESPONSE or DEEP_THINKING
- [ ] Implement `get_request_model()` - Pydantic request schema
- [ ] Implement `get_input_schema()` - MCP tool schema
- [ ] Implement request/response formatting hooks

**Testing:**
- [ ] Unit tests for request validation
- [ ] Unit tests for response formatting
- [ ] Integration test with real model (optional)
- [ ] Add to quality checks script

**Documentation:**
- [ ] Add tool to README.md
- [ ] Create examples in docs/tools/
- [ ] Update PLAN.md progress

## Common Development Tasks

### Adding a New Simple Tool

```python
# tools/mynewtool.py
from typing import Optional
from pydantic import Field
from tools.shared.base_models import ToolRequest
from .simple.base import SimpleTool
from systemprompts import MYNEWTOOL_PROMPT
from config import TEMPERATURE_BALANCED

class MyNewToolRequest(ToolRequest):
    """Request model for MyNewTool"""
    prompt: str = Field(..., description="What you want to accomplish")
    files: Optional[list[str]] = Field(default_factory=list)

class MyNewTool(SimpleTool):
    def get_name(self) -> str:
        return "mynewtool"

    def get_description(self) -> str:
        return "Brief description of what this tool does"

    def get_system_prompt(self) -> str:
        return MYNEWTOOL_PROMPT

    def get_default_temperature(self) -> float:
        return TEMPERATURE_BALANCED

    def get_model_category(self) -> "ToolModelCategory":
        from tools.models import ToolModelCategory
        return ToolModelCategory.FAST_RESPONSE

    def get_request_model(self):
        return MyNewToolRequest
```

### Adding a New Workflow Tool

```python
# tools/mynewworkflow.py
from typing import Optional
from pydantic import Field
from tools.shared.base_models import WorkflowRequest
from .workflow.base import WorkflowTool
from systemprompts import MYNEWWORKFLOW_PROMPT

class MyNewWorkflowRequest(WorkflowRequest):
    """Request model for workflow tool"""
    step: str = Field(description="Current step content")
    step_number: int = Field(ge=1)
    total_steps: int = Field(ge=1)
    next_step_required: bool
    findings: str = Field(description="What was discovered")
    # Add workflow-specific fields

class MyNewWorkflow(WorkflowTool):
    # Implementation similar to Simple Tool
    # but with workflow-specific logic
```

### Testing a Tool Manually

```bash
# Start server with debug logging
LOG_LEVEL=DEBUG python server.py

# In another terminal, watch logs
tail -f logs/mcp_server.log | grep -E "(TOOL_CALL|ERROR|MyNewTool)"

# In Claude Desktop, test:
# "Use zen-marketing to generate 10 subject lines about HVAC maintenance"
```

## Project Structure

```
zen-marketing/
├── server.py                 # Main MCP server entry point
├── config.py                 # Configuration constants
├── PLAN.md                   # Implementation plan (this doc)
├── CLAUDE.md                 # Development guide
├── README.md                 # User-facing documentation
├── requirements.txt          # Python dependencies
├── .env.example              # Environment variable template
├── .env                      # Local config (gitignored)
├── run-server.sh             # Setup and run script
├── code_quality_checks.sh    # Linting and testing
│
├── tools/                    # Tool implementations
│   ├── __init__.py
│   ├── contentvariant.py     # Bulk variation generator
│   ├── platformadapt.py      # Cross-platform adapter
│   ├── subjectlines.py       # Email subject line generator
│   ├── styleguide.py         # Writing style enforcer
│   ├── seooptimize.py        # SEO optimizer
│   ├── guestedit.py          # Guest content editor
│   ├── linkstrategy.py       # Internal linking strategist
│   ├── factcheck.py          # Technical fact checker
│   ├── voiceanalysis.py      # Voice extractor/validator
│   ├── campaignmap.py        # Campaign planner
│   ├── chat.py               # General chat (from zen)
│   ├── thinkdeep.py          # Deep thinking (from zen)
│   ├── planner.py            # Planning (from zen)
│   ├── models.py             # Shared models
│   ├── simple/               # Simple tool base classes
│   │   └── base.py
│   ├── workflow/             # Workflow tool base classes
│   │   └── base.py
│   └── shared/               # Shared utilities
│       └── base_models.py
│
├── providers/                # AI provider implementations
│   ├── __init__.py
│   ├── base.py               # Base provider interface
│   ├── gemini.py             # Google Gemini
│   ├── minimax.py            # Minimax (NEW)
│   ├── openrouter.py         # OpenRouter fallback
│   ├── registry.py           # Provider registry
│   └── shared/
│
├── systemprompts/            # System prompts for tools
│   ├── __init__.py
│   ├── 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
│   ├── chat_prompt.py        # From zen
│   ├── thinkdeep_prompt.py   # From zen
│   └── planner_prompt.py     # From zen
│
├── utils/                    # Utility functions
│   ├── conversation_memory.py # Conversation continuity
│   ├── file_utils.py         # File handling
│   └── web_search.py         # Web search integration
│
├── tests/                    # Test suite
│   ├── __init__.py
│   ├── test_contentvariant.py
│   ├── test_platformadapt.py
│   ├── test_subjectlines.py
│   └── ...
│
├── logs/                     # Log files (gitignored)
│   ├── mcp_server.log
│   └── mcp_activity.log
│
└── docs/                     # Documentation
    ├── getting-started.md
    ├── tools/
    │   ├── contentvariant.md
    │   ├── platformadapt.md
    │   └── ...
    └── examples/
        └── marketing-workflows.md
```

## Key Concepts from Zen Architecture

### Conversation Continuity
Every tool supports `continuation_id` to maintain context across interactions:

```python
# First call
result1 = await tool.execute({
    "prompt": "Analyze this brand voice",
    "files": ["brand_samples/post1.txt", "brand_samples/post2.txt"]
})
# Returns: continuation_id: "abc123"

# Follow-up call (remembers previous context)
result2 = await tool.execute({
    "prompt": "Now check if this new draft matches the voice",
    "files": ["new_draft.txt"],
    "continuation_id": "abc123"  # Preserves context
})
```

### File Handling
Tools automatically:
- Expand directories to individual files
- Deduplicate file lists
- Handle absolute paths
- Process images (screenshots, brand assets)

### Web Search Integration
Tools can request Claude to perform web searches:
```python
# In system prompt:
"If you need current information about [topic], request a web search from Claude."

# Claude will then use WebSearch tool and provide results
```

### Multi-Model Orchestration
Tools specify model category, server selects best available:
- `FAST_RESPONSE` → gemini-flash or equivalent
- `DEEP_THINKING` → gemini-2.5-pro or equivalent
- User can override with `model` parameter

## Debugging Common Issues

### Tool Not Appearing in Claude Desktop
1. Check `server.py` registers the tool
2. Verify tool is not in `DISABLED_TOOLS` env var
3. Restart Claude Desktop after config changes
4. Check logs: `tail -f logs/mcp_server.log`

### Model Selection Issues
1. Verify API keys in `.env`
2. Check provider registration in `providers/registry.py`
3. Test with explicit model name: `"model": "gemini-2.5-pro"`
4. Check logs for provider errors

### Response Formatting Issues
1. Validate system prompt specifies output format
2. Check response doesn't exceed token limits
3. Test with simpler input first
4. Review logs for truncation warnings

### Conversation Continuity Not Working
1. Verify `continuation_id` is being passed correctly
2. Check conversation hasn't expired (default 6 hours)
3. Validate conversation memory storage
4. Review logs: `grep "continuation_id" logs/mcp_server.log`

## Code Quality Standards

Before committing:

```bash
# Run all quality checks
./code_quality_checks.sh

# Manual checks:
ruff check . --fix          # Linting
black .                      # Formatting
isort .                      # Import sorting
pytest tests/ -v             # Run tests
```

## Marketing-Specific Considerations

### Character Limits by Platform
Tools should be aware of:
- **Twitter/Bluesky**: 280 characters
- **LinkedIn**: 3000 chars (1300 optimal)
- **Instagram**: 2200 characters
- **Facebook**: No hard limit (500 chars optimal)
- **Email subject**: 60 characters optimal
- **Email preview**: 90-100 characters
- **Meta description**: 156 characters
- **Page title**: 60 characters

### Writing Style Rules from Project Memories
- 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
- Concrete metrics over abstract claims
- Technical accuracy preserved
- Author voice maintained

### Testing Angles for Variations
- Technical curiosity
- Contrarian/provocative
- Knowledge gap emphasis
- Urgency/timeliness
- Insider knowledge positioning
- Problem-solution framing
- Before-after transformation
- Social proof/credibility
- FOMO (fear of missing out)
- Educational value

## Next Session Goals

When you start the new session in `~/mcp/zen-marketing/`:

1. **Copy Core Files from Zen**
   - Copy base architecture preserving git history
   - Remove code-specific tools
   - Update imports and references

2. **Configure Minimax Provider**
   - Add minimax support to providers/
   - Register in provider registry
   - Test basic model calls

3. **Implement First Simple Tool**
   - Start with `contentvariant` (highest priority)
   - Create tool, system prompt, and tests
   - Test end-to-end with Claude Desktop

4. **Validate Architecture**
   - Ensure conversation continuity works
   - Verify file handling
   - Test web search integration

## Questions to Consider

Before implementing each tool:
1. What real-world workflow does this solve? (Reference project memories)
2. What's the minimum viable version?
3. What can go wrong? (Character limits, API errors, invalid input)
4. How will users test variations? (Output format)
5. Does it need web search? (Current info, fact-checking)
6. What's the right temperature? (Creative vs analytical)
7. Simple or workflow tool? (Single-shot vs multi-step)

## Resources

- **Zen MCP Server Repo**: Source for architecture and patterns
- **MCP Protocol Docs**: https://modelcontextprotocol.com
- **Claude Desktop Config**: `~/.claude.json`
- **Project Memories**: See PLAN.md for user workflow examples
- **Platform Best Practices**: Research current 2025 guidelines

---

**Ready to build?** Start the new session with:
```bash
cd ~/mcp/zen-marketing
# Then ask Claude to begin Phase 1 implementation
```