Update CLAUDE.md with improved /init format
- Restructured to follow /init specifications for Claude Code - Added clear command reference for setup and development - Documented architecture patterns (tool system, providers, conversation continuity) - Explained schema generation and file processing systems - Removed planning/roadmap content (belongs in PLAN.md) - Added practical debugging tips and implementation patterns - Focused on non-obvious architecture insights
This commit is contained in:
Ben
parent
371806488d
commit
122797d325
1 changed files with 264 additions and 447 deletions
711
CLAUDE.md
711
CLAUDE.md
|
|
@ -1,84 +1,66 @@
|
|||
# Claude Development Guide for Zen-Marketing MCP Server
|
||||
# CLAUDE.md
|
||||
|
||||
This file contains essential commands and workflows for developing the Zen-Marketing MCP Server - a specialized marketing-focused fork of Zen MCP Server.
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Context
|
||||
## Project Overview
|
||||
|
||||
**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
|
||||
Zen-Marketing is an MCP server for Claude Desktop providing AI-powered marketing tools. It's a fork of Zen MCP Server, specialized for marketing workflows rather than software development.
|
||||
|
||||
**Target User:** Solo marketing professionals managing technical B2B content, particularly in industries like HVAC, SaaS, and technical education.
|
||||
**Key distinction:** This server generates content variations, enforces writing styles, and optimizes for platforms (LinkedIn, newsletters, WordPress) - not code review or debugging.
|
||||
|
||||
**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.
|
||||
**Target user:** Solo marketing professionals managing technical B2B content (HVAC, SaaS, technical education).
|
||||
|
||||
## Quick Reference Commands
|
||||
## Essential Commands
|
||||
|
||||
### Initial Setup
|
||||
### Setup and Running
|
||||
|
||||
```bash
|
||||
# Navigate to project directory
|
||||
cd ~/mcp/zen-marketing
|
||||
# Initial setup
|
||||
./run-server.sh
|
||||
|
||||
# Copy core files from zen-mcp-server (if starting fresh)
|
||||
# We'll do this in the new session
|
||||
|
||||
# Create virtual environment
|
||||
# Manual setup
|
||||
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
|
||||
```
|
||||
# Edit .env with 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
|
||||
# Run server
|
||||
python server.py
|
||||
|
||||
# View logs
|
||||
# Run with debug logging
|
||||
LOG_LEVEL=DEBUG python server.py
|
||||
```
|
||||
|
||||
### Testing and Development
|
||||
|
||||
```bash
|
||||
# Watch logs during development
|
||||
tail -f logs/mcp_server.log
|
||||
|
||||
# Run tests
|
||||
python -m pytest tests/ -v
|
||||
# Filter logs for specific tool
|
||||
tail -f logs/mcp_server.log | grep -E "(TOOL_CALL|ERROR|contentvariant)"
|
||||
|
||||
# Test with Claude Desktop after changes
|
||||
# Restart Claude Desktop to reload MCP server configuration
|
||||
```
|
||||
|
||||
### Claude Desktop Configuration
|
||||
|
||||
Add to `~/.claude.json`:
|
||||
Configuration file: `~/.claude.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"zen-marketing": {
|
||||
"command": "/home/ben/mcp/zen-marketing/.venv/bin/python",
|
||||
"args": ["/home/ben/mcp/zen-marketing/server.py"],
|
||||
"command": "/Users/ben/dev/mcp/zen-marketing/.venv/bin/python",
|
||||
"args": ["/Users/ben/dev/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",
|
||||
"GEMINI_API_KEY": "your-key",
|
||||
"DEFAULT_MODEL": "google/gemini-2.5-pro-latest",
|
||||
"FAST_MODEL": "google/gemini-2.5-flash-preview-09-2025",
|
||||
"CREATIVE_MODEL": "minimax/minimax-m2",
|
||||
"ENABLE_WEB_SEARCH": "true",
|
||||
"DISABLED_TOOLS": "",
|
||||
"LOG_LEVEL": "INFO"
|
||||
}
|
||||
}
|
||||
|
|
@ -86,481 +68,316 @@ Add to `~/.claude.json`:
|
|||
}
|
||||
```
|
||||
|
||||
**After modifying config:** Restart Claude Desktop for changes to take effect.
|
||||
**Critical:** After modifying configuration, restart Claude Desktop completely for changes to take effect.
|
||||
|
||||
## Tool Development Guidelines
|
||||
## Architecture Overview
|
||||
|
||||
### Tool Categories
|
||||
### Tool System Design
|
||||
|
||||
**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
|
||||
The codebase uses a two-tier tool architecture inherited from Zen MCP Server:
|
||||
|
||||
**Workflow Tools** (multi-step processes):
|
||||
- Inherit from `WorkflowTool` base class
|
||||
- Systematic step-by-step workflows
|
||||
- Track progress, confidence, findings
|
||||
- Examples: `styleguide`, `seooptimize`, `guestedit`, `linkstrategy`
|
||||
1. **Simple Tools** (`tools/simple/base.py`): Single-shot request/response tools for fast iteration
|
||||
- Example: `contentvariant` - generates 5-25 variations in one call
|
||||
- Use `ToolModelCategory.FAST_RESPONSE` for quick operations
|
||||
- Inherit from `SimpleTool` base class
|
||||
|
||||
### Temperature Guidelines for Marketing Tools
|
||||
2. **Workflow Tools** (`tools/workflow/base.py`): Multi-step systematic processes
|
||||
- Track `step_number`, `total_steps`, `next_step_required`
|
||||
- Maintain `findings` and `confidence` across steps
|
||||
- Example: `styleguide` - detect → flag → rewrite → validate
|
||||
- Use `ToolModelCategory.DEEP_THINKING` for complex analysis
|
||||
|
||||
- **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
|
||||
### Provider System
|
||||
|
||||
### Model Selection Strategy
|
||||
Model providers are managed through a registry pattern (`providers/registry.py`):
|
||||
|
||||
**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
|
||||
- **Priority order:** GOOGLE (Gemini) → OPENAI → XAI → DIAL → CUSTOM → OPENROUTER
|
||||
- **Lazy initialization:** Providers are only instantiated when first needed
|
||||
- **Model categories:** Tools request `FAST_RESPONSE` or `DEEP_THINKING`, registry selects best available model
|
||||
- **Fallback chain:** If primary provider fails, falls back to next in priority order
|
||||
|
||||
**Gemini Flash** (`gemini-flash`):
|
||||
- Fast bulk generation
|
||||
- Subject line creation
|
||||
- Quick variations
|
||||
- Cost-effective iterations
|
||||
Key providers:
|
||||
- `gemini.py` - Google Gemini API (analytical work)
|
||||
- `openai_compatible.py` - OpenAI and compatible APIs
|
||||
- `openrouter.py` - Fallback for cloud models
|
||||
- `custom.py` - Self-hosted models
|
||||
|
||||
**Minimax M2** (`minimax-m2`):
|
||||
- Creative content generation
|
||||
- Platform adaptation
|
||||
- Content repurposing
|
||||
- Marketing copy variations
|
||||
### Conversation Continuity
|
||||
|
||||
### System Prompt Best Practices
|
||||
Every tool supports `continuation_id` for stateful conversations:
|
||||
|
||||
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")
|
||||
1. First call returns a `continuation_id` in response
|
||||
2. Subsequent calls include this ID to preserve context
|
||||
3. Stored in-memory with 6-hour expiration (configurable)
|
||||
4. Managed by `utils/conversation_memory.py`
|
||||
|
||||
Example prompt structure:
|
||||
```python
|
||||
CONTENTVARIANT_PROMPT = """
|
||||
You are a marketing content strategist specializing in A/B testing and variation generation.
|
||||
This allows follow-up interactions like:
|
||||
- "Now check if this new draft matches the voice" (after voice analysis)
|
||||
- "Generate 10 more variations with different angles" (after initial generation)
|
||||
|
||||
TASK: Generate multiple variations of marketing content for testing different approaches.
|
||||
### File Processing
|
||||
|
||||
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
|
||||
Tools automatically handle file inputs (`utils/file_utils.py`):
|
||||
- Directory expansion (recursively processes all files in directory)
|
||||
- Deduplication (removes duplicate file paths)
|
||||
- Image support (screenshots, brand assets via `utils/image_utils.py`)
|
||||
- Path resolution (converts relative to absolute paths)
|
||||
|
||||
CONSTRAINTS:
|
||||
- Maintain core message across variations
|
||||
- Respect platform character limits if specified
|
||||
- Preserve brand voice characteristics
|
||||
- Generate genuinely different approaches, not just word swaps
|
||||
Files are included in model context, so tools can reference brand guidelines, content samples, etc.
|
||||
|
||||
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
|
||||
"""
|
||||
```
|
||||
### Schema Generation
|
||||
|
||||
## Implementation Phases
|
||||
Tools use a builder pattern for MCP schemas (`tools/shared/schema_builders.py`):
|
||||
- `SchemaBuilder` - Generates MCP tool schemas from Pydantic models
|
||||
- `WorkflowSchemaBuilder` - Specialized for workflow tools with step tracking
|
||||
- Automatic field type conversion (Pydantic → JSON Schema)
|
||||
- Shared field definitions (files, images, continuation_id, model, temperature)
|
||||
|
||||
### 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
|
||||
## Tool Implementation Pattern
|
||||
|
||||
### 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
|
||||
### Creating a Simple Tool
|
||||
|
||||
```python
|
||||
# tools/mynewtool.py
|
||||
from typing import Optional
|
||||
# tools/mymarketingtool.py
|
||||
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
|
||||
from tools.simple.base import SimpleTool
|
||||
from tools.models import ToolModelCategory
|
||||
from systemprompts import MYMARKETINGTOOL_PROMPT
|
||||
from config import TEMPERATURE_CREATIVE
|
||||
|
||||
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 MyMarketingToolRequest(ToolRequest):
|
||||
content: str = Field(..., description="Content to process")
|
||||
platform: str = Field(default="linkedin", description="Target platform")
|
||||
|
||||
class MyNewTool(SimpleTool):
|
||||
class MyMarketingTool(SimpleTool):
|
||||
def get_name(self) -> str:
|
||||
return "mynewtool"
|
||||
return "mymarketingtool"
|
||||
|
||||
def get_description(self) -> str:
|
||||
return "Brief description of what this tool does"
|
||||
return "Brief description shown in Claude Desktop"
|
||||
|
||||
def get_system_prompt(self) -> str:
|
||||
return MYNEWTOOL_PROMPT
|
||||
return MYMARKETINGTOOL_PROMPT
|
||||
|
||||
def get_default_temperature(self) -> float:
|
||||
return TEMPERATURE_BALANCED
|
||||
return TEMPERATURE_CREATIVE
|
||||
|
||||
def get_model_category(self) -> "ToolModelCategory":
|
||||
from tools.models import ToolModelCategory
|
||||
def get_model_category(self) -> ToolModelCategory:
|
||||
return ToolModelCategory.FAST_RESPONSE
|
||||
|
||||
def get_request_model(self):
|
||||
return MyNewToolRequest
|
||||
return MyMarketingToolRequest
|
||||
```
|
||||
|
||||
### Adding a New Workflow Tool
|
||||
### Registering a Tool
|
||||
|
||||
In `server.py`, add to the `_initialize_tools()` method:
|
||||
|
||||
```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
|
||||
from tools.mymarketingtool import MyMarketingTool
|
||||
|
||||
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
|
||||
def _initialize_tools(self) -> list[BaseTool]:
|
||||
tools = [
|
||||
ChatTool(),
|
||||
ContentVariantTool(),
|
||||
MyMarketingTool(), # Add here
|
||||
# ... other tools
|
||||
]
|
||||
return tools
|
||||
```
|
||||
|
||||
### Testing a Tool Manually
|
||||
### System Prompt Structure
|
||||
|
||||
```bash
|
||||
# Start server with debug logging
|
||||
LOG_LEVEL=DEBUG python server.py
|
||||
System prompts live in `systemprompts/`:
|
||||
|
||||
# In another terminal, watch logs
|
||||
tail -f logs/mcp_server.log | grep -E "(TOOL_CALL|ERROR|MyNewTool)"
|
||||
```python
|
||||
# systemprompts/mymarketingtool_prompt.py
|
||||
MYMARKETINGTOOL_PROMPT = """
|
||||
You are a marketing content specialist.
|
||||
|
||||
# In Claude Desktop, test:
|
||||
# "Use zen-marketing to generate 10 subject lines about HVAC maintenance"
|
||||
TASK: [Clear description of what this tool does]
|
||||
|
||||
OUTPUT FORMAT:
|
||||
[Specify exact format - JSON, markdown, numbered list, etc.]
|
||||
|
||||
CONSTRAINTS:
|
||||
- Character limits for platform
|
||||
- Preserve brand voice
|
||||
- Technical accuracy required
|
||||
|
||||
PROCESS:
|
||||
1. Step one
|
||||
2. Step two
|
||||
3. Final output
|
||||
"""
|
||||
```
|
||||
|
||||
**Import in systemprompts/__init__.py:**
|
||||
|
||||
```python
|
||||
from .mymarketingtool_prompt import MYMARKETINGTOOL_PROMPT
|
||||
```
|
||||
|
||||
## Temperature Configurations
|
||||
|
||||
Defined in `config.py` for different content types:
|
||||
|
||||
- `TEMPERATURE_PRECISION` (0.2) - Fact-checking, technical verification
|
||||
- `TEMPERATURE_ANALYTICAL` (0.3) - Style enforcement, SEO optimization
|
||||
- `TEMPERATURE_BALANCED` (0.5) - Strategic planning, guest editing
|
||||
- `TEMPERATURE_CREATIVE` (0.7) - Platform adaptation
|
||||
- `TEMPERATURE_HIGHLY_CREATIVE` (0.8) - Content variation, subject lines
|
||||
|
||||
Choose based on whether tool needs creativity (variations) or precision (fact-checking).
|
||||
|
||||
## Platform Character Limits
|
||||
|
||||
Defined in `config.py` as `PLATFORM_LIMITS`:
|
||||
|
||||
```python
|
||||
PLATFORM_LIMITS = {
|
||||
"twitter": 280,
|
||||
"bluesky": 300,
|
||||
"linkedin": 3000,
|
||||
"linkedin_optimal": 1300,
|
||||
"instagram": 2200,
|
||||
"facebook": 500,
|
||||
"email_subject": 60,
|
||||
"email_preview": 100,
|
||||
"meta_description": 156,
|
||||
"page_title": 60,
|
||||
}
|
||||
```
|
||||
|
||||
Tools reference these when generating platform-specific content.
|
||||
|
||||
## Model Selection Strategy
|
||||
|
||||
Tools specify category, not specific model:
|
||||
|
||||
- **FAST_RESPONSE** → Uses `FAST_MODEL` from config (default: gemini-flash)
|
||||
- **DEEP_THINKING** → Uses `DEFAULT_MODEL` from config (default: gemini-2.5-pro)
|
||||
|
||||
Users can override:
|
||||
1. Via `model` parameter in tool request
|
||||
2. Via environment variables (`DEFAULT_MODEL`, `FAST_MODEL`, `CREATIVE_MODEL`)
|
||||
|
||||
**Default models:**
|
||||
- Analytical work: `google/gemini-2.5-pro-latest`
|
||||
- Fast generation: `google/gemini-2.5-flash-preview-09-2025`
|
||||
- Creative content: `minimax/minimax-m2`
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### Tool Not Appearing
|
||||
|
||||
1. Check tool is registered in `server.py`
|
||||
2. Verify not in `DISABLED_TOOLS` env var
|
||||
3. Check logs: `tail -f logs/mcp_server.log`
|
||||
4. Restart Claude Desktop after config changes
|
||||
|
||||
### Model Errors
|
||||
|
||||
1. Verify API key in `.env` file
|
||||
2. Check provider supports requested model
|
||||
3. Look for provider errors in logs
|
||||
4. Test with explicit model name override
|
||||
|
||||
### Response Issues
|
||||
|
||||
1. Check system prompt specifies output format clearly
|
||||
2. Verify response doesn't exceed token limits
|
||||
3. Review logs for truncation warnings
|
||||
4. Test with simpler input first
|
||||
|
||||
### Conversation Context Lost
|
||||
|
||||
1. Verify `continuation_id` passed correctly
|
||||
2. Check conversation hasn't expired (6 hours default)
|
||||
3. Look for memory errors in logs: `grep "continuation_id" logs/mcp_server.log`
|
||||
|
||||
## 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 directories:
|
||||
|
||||
## Key Concepts from Zen Architecture
|
||||
- `server.py` - MCP server implementation, tool registration
|
||||
- `config.py` - Configuration constants, temperature defaults, platform limits
|
||||
- `tools/` - Tool implementations (simple/ and workflow/ subdirs)
|
||||
- `providers/` - AI model provider implementations
|
||||
- `systemprompts/` - System prompts for each tool
|
||||
- `utils/` - Shared utilities (file handling, conversation memory, image processing)
|
||||
- `logs/` - Server logs (gitignored)
|
||||
|
||||
### Conversation Continuity
|
||||
Every tool supports `continuation_id` to maintain context across interactions:
|
||||
## Marketing-Specific Context
|
||||
|
||||
```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"
|
||||
### Writing Style Rules
|
||||
|
||||
# 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
|
||||
From project memories, tools should enforce:
|
||||
- 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
|
||||
|
||||
Common psychological angles for A/B testing:
|
||||
- Technical curiosity
|
||||
- Contrarian/provocative
|
||||
- Knowledge gap emphasis
|
||||
- Urgency/timeliness
|
||||
- Insider knowledge positioning
|
||||
- Insider knowledge
|
||||
- Problem-solution framing
|
||||
- Before-after transformation
|
||||
- Social proof/credibility
|
||||
- FOMO (fear of missing out)
|
||||
- Educational value
|
||||
|
||||
## Next Session Goals
|
||||
### Platform Best Practices
|
||||
|
||||
When you start the new session in `~/mcp/zen-marketing/`:
|
||||
- **LinkedIn**: 1300 chars optimal (3000 max), professional tone
|
||||
- **Twitter/Bluesky**: 280 chars, conversational, high engagement hooks
|
||||
- **Email subject**: 60 chars, action-oriented, clear value prop
|
||||
- **Instagram**: 2200 chars, visual storytelling, emojis appropriate
|
||||
- **Blog/WordPress**: SEO-optimized titles (<60 chars), meta descriptions (<156 chars)
|
||||
|
||||
1. **Copy Core Files from Zen**
|
||||
- Copy base architecture preserving git history
|
||||
- Remove code-specific tools
|
||||
- Update imports and references
|
||||
## Key Differences from Zen MCP Server
|
||||
|
||||
2. **Configure Minimax Provider**
|
||||
- Add minimax support to providers/
|
||||
- Register in provider registry
|
||||
- Test basic model calls
|
||||
1. **Removed tools:** debug, codereview, refactor, testgen, secaudit, docgen, tracer, precommit
|
||||
2. **Added tools:** contentvariant, platformadapt, subjectlines, styleguide, seooptimize, guestedit, linkstrategy, factcheck
|
||||
3. **Kept tools:** chat, thinkdeep, planner (useful for marketing strategy)
|
||||
4. **New focus:** Content variation, platform adaptation, voice preservation
|
||||
5. **Model preference:** Minimax for creative generation, Gemini for analytical work
|
||||
|
||||
3. **Implement First Simple Tool**
|
||||
- Start with `contentvariant` (highest priority)
|
||||
- Create tool, system prompt, and tests
|
||||
- Test end-to-end with Claude Desktop
|
||||
## Current Implementation Status
|
||||
|
||||
4. **Validate Architecture**
|
||||
- Ensure conversation continuity works
|
||||
- Verify file handling
|
||||
- Test web search integration
|
||||
**Completed:**
|
||||
- [x] Core architecture from Zen MCP Server
|
||||
- [x] Provider system (Gemini, OpenAI, OpenRouter)
|
||||
- [x] Tool base classes (SimpleTool, WorkflowTool)
|
||||
- [x] Conversation continuity system
|
||||
- [x] File processing utilities
|
||||
- [x] Basic tools: chat, contentvariant, listmodels, version
|
||||
|
||||
## Questions to Consider
|
||||
**In Progress:**
|
||||
- [ ] Additional simple tools (platformadapt, subjectlines, factcheck)
|
||||
- [ ] Workflow tools (styleguide, seooptimize, guestedit, linkstrategy)
|
||||
- [ ] Minimax provider configuration
|
||||
- [ ] Advanced features (voiceanalysis, campaignmap)
|
||||
|
||||
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)
|
||||
See PLAN.md for detailed implementation roadmap.
|
||||
|
||||
## Git Workflow
|
||||
|
||||
**Commit signature:** Ben Reed `ben@tealmaker.com` (not Claude Code)
|
||||
|
||||
**Commit frequency:** After reasonable amount of updates (not after every small change)
|
||||
|
||||
## 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
|
||||
```
|
||||
- MCP Protocol: https://modelcontextprotocol.com
|
||||
- Zen MCP Server (parent project): https://github.com/BeehiveInnovations/zen-mcp-server
|
||||
- Claude Desktop download: https://claude.ai/download
|
||||
- Project planning: See PLAN.md for tool designs and implementation phases
|
||||
- User documentation: See README.md for end-user features
|
||||
|
|
|
|||
Loading…
Reference in a new issue