# 🔌 MCP Server v3.0 - Claude Integration Guide

**Medium Agent** is one of the first consumer applications to fully embrace the **Model Context Protocol (MCP)**. 

This is not just an API; it is a **Standard for Agency**. By exposing our tools via MCP, we allow any compliant AI client (like **Claude Desktop**) to interact with the Medium ecosystem directly.

---

## 🚀 What's New in v3.0

| Feature | Description |
|---------|-------------|
| **12 Tools** | 2 new: `medium_related`, `medium_recommend` |
| **4 Resources** | New `medium://stats` endpoint |
| **9 Prompts** | 3 new: `analyze_trending`, `deep_research`, `content_repurpose` |
| **MCP Annotations** | All tools have `readOnlyHint`, `openWorldHint`, `idempotentHint` |
| **Progress Notifications** | Real-time progress for batch operations |
| **HTTP Transport** | Run as HTTP server with `--http` flag |

---

## 🛠️ Tools Reference

### Core Scraping
| Tool | Description |
|------|-------------|
| `medium_scrape` | Scrape a single Medium article (35+ domains) |
| `medium_batch` | Batch scrape multiple articles with progress |
| `medium_search` | Search Medium for articles |
| `medium_fresh` | Get latest articles by tag |
| `medium_render_html` | Render article as styled HTML |
| `medium_export` | Export to markdown/HTML/JSON |

### Audio & AI
| Tool | Description |
|------|-------------|
| `medium_cast` | Convert article to audio podcast (ElevenLabs) |
| `medium_voices` | List available TTS voices |
| `medium_synthesize` | Generate AI research report |

### Discovery
| Tool | Description |
|------|-------------|
| `medium_related` | Find related articles |
| `medium_recommend` | Personalized reading list |
| `get_thumbnail` | Fetch article thumbnail |

---

## 📚 Resources

| URI | Description |
|-----|-------------|
| `medium://trending` | Current trending articles |
| `medium://tag/{tag}` | Articles by topic tag |
| `medium://search/{query}` | Search results |
| `medium://stats` | Server capabilities |

---

## 💬 Prompts

| Prompt | Use Case |
|--------|----------|
| `summarize_article` | Create article summary |
| `tweet_thread` | Convert to Twitter thread |
| `linkedin_post` | Convert to LinkedIn post |
| `newsletter` | Create newsletter digest |
| `research_report` | Comprehensive research report |
| `code_tutorial` | Extract code tutorial |
| `analyze_trending` | Analyze trends with workflow |
| `deep_research` | Multi-phase research workflow |
| `content_repurpose` | Multi-platform content |

---

## 🤝 Setup Guide

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "medium-agent": {
      "command": "python",
      "args": ["c:/Dev/Medium-Agent/medium-mcp/server.py"],
      "env": {
        "GROQ_API_KEY": "your-key",
        "GEMINI_API_KEY": "your-key",
        "ELEVENLABS_API_KEY": "your-key",
        "OPENAI_API_KEY": "your-key"
      }
    }
  }
}
```

### MCP Inspector Testing

```bash
cd c:\Dev\Medium-Agent\medium-mcp
npx @modelcontextprotocol/inspector python server.py
```

### HTTP Transport Mode

For remote deployment:

```bash
python server.py --http --port 8000
```

---

## 🏆 Agentic Capabilities

Unlike simple chatbots, the Medium Agent via MCP allows Claude to:

1. **Plan**: Decide *when* to search and *when* to read
2. **Act**: Execute real-time web scraping commands
3. **Observe**: Analyze content and extract meaning
4. **Synthesize**: Generate comprehensive reports

### Example Workflow

1. **User**: *"Find the latest articles on React 19 and summarize the controversy."*
2. **Claude**: Calls `medium_search("React 19")`
3. **Agent**: Returns article list with progress notifications
4. **Claude**: Selects relevant articles, calls `medium_scrape(url)`
5. **Agent**: Returns full text with MCP logging
6. **Claude**: Synthesizes the answer

---

*Medium MCP Server v3.0 - Full MCP Specification Compliance*