# 🚀 Medium Blog MCP Server

AI-powered blog generation system built with FastMCP. Automates research, content generation, quality checks, and Medium export for technical blog posts.

## ✨ Features

- 🔍 **Multi-Source Research**: Automatically gathers content from Wikipedia, arXiv, web search, and images
- 🤖 **AI Content Generation**: Uses Claude API to generate high-quality blog posts
- 📊 **Image Processing**: Downloads and describes images with AI-generated descriptions
- 📝 **Quality Analysis**: Comprehensive readability, citation, and SEO checks
- ✅ **Plagiarism Tracking**: Hybrid manual/automated plagiarism checking workflow
- 📤 **Medium Export**: One-click export to Medium-ready markdown format
- 💾 **SQLite Storage**: Persistent storage of all drafts and research

## 🏗️ Architecture

```
Medium Blog MCP Server
├── Research Engine (Wikipedia, arXiv, Web, Images)
├── AI Content Generator (Claude API)
├── Image Handler (Download + AI Description)
├── Quality Analyzer (Readability, Citations, SEO)
├── Medium Exporter (Markdown + Assets)
└── SQLite Database (Sessions, Drafts, Research)
```

## 📋 Prerequisites

- Python 3.10+
- Anthropic API Key ([Get one here](https://console.anthropic.com/))
- pip or conda

## 🚀 Quick Start

### 1. Clone and Install

```bash
# Clone repository
git clone <your-repo-url>
cd medium-blog-mcp

# Activate virtual environment
uv init
uv sync

# Install dependencies
uv add -r requirements.txt

# use these uv commands to test , run mcp servers
Test the server - uv run fastmcp dev main.py
Run the server - uv run fastmcp run main.py
Add the server to claude desktop - uv run fastmcp install
claude-desktop main.py
```

### 2. Configure Environment

```bash
# Copy environment template
cp .env.example .env

# Edit .env and add your DB URL
# DATABASE_URL=YOUR_SQLITE_DB_URL
```

### 3. Run the Server

```bash
python main.py
```

The MCP server will start and be available for Claude Desktop or other MCP clients.

## 🔧 Configuration for Claude Desktop

Add to your Claude Desktop `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "medium-blog-generator": {
      "command": "[Your/Path/to/uv]",
      "args": [
        "--directory",
        "C:\\medium_mcp",
        "run",
        "fastmcp",
        "run",
        "main.py"
      ],
      "env": {},
      "transport": "stdio",
      "type": null,
      "cwd": null,
      "timeout": null,
      "description": null,
      "icon": null,
      "authentication": null
    }
  }
}
```

**Config locations:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

## 📖 Complete Workflow

### Step 1: Create Session
```
create_blog_session(topic="Latest AI Model Advancements", target_length="medium")
```

### Step 2: Research Phase ⭐ USER CHECKPOINT
```
research_topic(session_id="abc123", depth="comprehensive")
get_research_summary(session_id="abc123")  # Review research
approve_research(session_id="abc123")       # Approve to continue
```

### Step 3: Outline Generation ⭐ USER CHECKPOINT
```
generate_outline(session_id="abc123", style="technical", num_sections=5)
# Review outline, optionally modify
approve_outline(session_id="abc123")
```

### Step 4: Content Generation
```
generate_full_content(session_id="abc123")
get_full_draft(session_id="abc123")  # Review full draft
```

### Step 5: Plagiarism Checking ⭐ USER CHECKPOINT (Manual)
```
prepare_plagiarism_chunks(session_id="abc123")
# Copy chunks to Grammarly/QuillBot/GPTZero manually
record_plagiarism_result(session_id="abc123", chunk_id=1, 
                        plagiarism_score=2.3, ai_detection_score=8.5, 
                        tool_used="Grammarly")
```

### Step 6: Quality Analysis ⭐ USER CHECKPOINT
```
run_quality_analysis(session_id="abc123")  # Get detailed QA report
approve_final_draft(session_id="abc123")   # Final approval
```

### Step 7: Export to Medium
```
export_to_medium(session_id="abc123")
```

## 🛠️ Available MCP Tools

### Session Management
- `create_blog_session` - Start new blog project
- `get_session_status` - Check progress
- `list_sessions` - List all sessions

### Research
- `research_topic` - Multi-source research
- `get_research_summary` - Review findings
- `add_custom_source` - Add manual sources
- `approve_research` - ⭐ Proceed to outline

### Outline
- `generate_outline` - AI-generated structure
- `modify_outline` - Make changes
- `approve_outline` - ⭐ Proceed to writing

### Content Generation
- `generate_full_content` - Generate blog
- `get_full_draft` - Review content
- `regenerate_section` - Improve specific section

### Plagiarism Checking
- `prepare_plagiarism_chunks` - Split for checking
- `record_plagiarism_result` - ⭐ Record manual checks
- `get_plagiarism_summary` - View all results

### Quality & Export
- `run_quality_analysis` - Comprehensive QA
- `approve_final_draft` - ⭐ Final approval
- `export_to_medium` - Generate export files

## 📁 Project Structure

```
medium-blog-mcp/
├── main.py                   # FastMCP server (all tools)
├── database.py               # SQLAlchemy models & DB operations
├── research.py               # Multi-source research engine
├── content_generator.py      # Claude API content generation
├── image_handler.py          # Image download & AI descriptions
├── quality.py                # Quality analysis & readability
├── exporter.py               # Medium markdown export
├── config.py                 # Configuration management
├── requirements.txt          # Python dependencies
├── .env.example              # Environment variables template
├── README.md                 # This file
└── data/                     # Generated data (auto-created)
    ├── blog_database.db      # SQLite database
    ├── sessions/             # Session-specific data
    │   └── {session_id}/
    │       └── images/       # Downloaded images
    ├── exports/              # Final exports
    │   └── {session_id}/
    │       ├── blog_post.md
    │       ├── images/
    │       ├── citations.txt
    │       ├── metadata.json
    │       └── qa_report.txt
    └── images/               # Image storage
```

## 🎯 Usage Example

Here's a complete example of generating a blog about AI models:

```python
# 1. Create session
create_blog_session(topic="GPT-4 vs Claude 3: Technical Comparison", target_length="medium")
# Returns: {"session_id": "abc123", ...}

# 2. Research
research_topic(session_id="abc123", depth="comprehensive")
get_research_summary(session_id="abc123")
# Review the 15-20 sources gathered
approve_research(session_id="abc123")

# 3. Generate outline
generate_outline(session_id="abc123", style="technical", num_sections=5)
# Review outline structure
approve_outline(session_id="abc123")

# 4. Generate content
generate_full_content(session_id="abc123")
get_full_draft(session_id="abc123")
# Review the ~2500 word blog with images

# 5. Check plagiarism manually
prepare_plagiarism_chunks(session_id="abc123")
# Copy chunks to Grammarly, check, then:
record_plagiarism_result(session_id="abc123", chunk_id=1, 
                        plagiarism_score=1.8, ai_detection_score=7.2, 
                        tool_used="Grammarly")

# 6. Quality analysis
run_quality_analysis(session_id="abc123")
# Review QA report
approve_final_draft(session_id="abc123")

# 7. Export
export_to_medium(session_id="abc123")
# Get Medium-ready markdown + all assets!
```

**Total time:** 30-45 minutes for a complete 2500-word blog!

## 🔍 Quality Checks

The system automatically checks:

### Readability
- Flesch Reading Ease score
- Flesch-Kincaid Grade Level
- Average sentence length
- Passive voice percentage

### Citations
- All sources properly cited
- Citation format validation
- Unused sources identified

### Images
- All images have descriptions
- Alt text present
- Proper placement

### SEO
- Title length (50-70 chars optimal)
- Header hierarchy (H1, H2, H3)
- Keyword presence
- Meta information

### Structure
- Word count vs target
- Section balance
- Overall organization

## 📊 Database Schema

### Tables
- **sessions** - Blog sessions
- **research_sources** - Research data
- **outlines** - Generated outlines
- **blog_drafts** - Blog content versions
- **images** - Downloaded images
- **plagiarism_checks** - Manual check results
- **quality_checks** - QA reports

All data persists across sessions and can be resumed.

## 🐛 Troubleshooting

### Database Issues
```bash
# Reset database (WARNING: deletes all data)
rm data/blog_database.db
python main.py  # Will recreate database
```

### Image Download Failures
- Check internet connection
- Some images may be behind authentication
- System will create fallback descriptions

## 🔄 Development Roadmap

### Current Version (v1.0)
- ✅ Multi-source research
- ✅ AI content generation
- ✅ Image processing
- ✅ Quality analysis
- ✅ Medium export

### Future Enhancements (v2.0+)
- 🔲 Automated plagiarism APIs
- 🔲 Multiple format exports (HTML, PDF)
- 🔲 Note-taking app integrations (Obsidian, Notion)
- 🔲 Multi-blog management
- 🔲 SEO optimization suggestions
- 🔲 Social media snippet generation

## 📝 License

MIT License - feel free to use and modify for your needs.

## 🤝 Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## 💬 Support

For issues or questions:
- Open an issue on GitHub
- Check the documentation
- Review example workflows

## 🙏 Credits

Built with:
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Anthropic Claude](https://www.anthropic.com) - AI content generation
- [SQLAlchemy](https://www.sqlalchemy.org/) - Database ORM
- Various open-source research APIs

---

**Happy blogging! 🚀**