docs/API.md

# Medium-MCP API Reference

## Overview

Medium-MCP provides a Model Context Protocol (MCP) server for scraping Medium articles.

---

## MCP Tools

### `medium_scrape`
Scrape a single Medium article.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | ✅ | Medium article URL |
| `force_refresh` | boolean | ❌ | Bypass cache (default: false) |
| `output_format` | string | ❌ | "markdown", "html", or "both" |

**Response:**
```json
{
  "url": "https://medium.com/...",
  "title": "Article Title",
  "author": {"name": "...", "username": "..."},
  "markdown_content": "...",
  "html_content": "...",
  "reading_time": 5,
  "is_paywalled": false
}
```

---

### `medium_batch`
Scrape multiple articles in parallel.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `urls` | string[] | ✅ | List of URLs (max 20) |

**Response:**
```json
{
  "success": [...],
  "failed": [{"url": "...", "error": "..."}],
  "total": 5,
  "success_count": 4,
  "fail_count": 1
}
```

---

### `medium_search`
Search for articles.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `query` | string | ✅ | Search query |
| `max_results` | number | ❌ | Max results (1-20) |

**Response:**
```json
[
  {"title": "...", "url": "...", "author": "..."}
]
```

---

### `medium_fresh`
Browse trending articles by tag.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `tag` | string | ✅ | Tag name (e.g., "python") |
| `max_articles` | number | ❌ | Max articles (1-20) |

---

### `medium_export`
Export article to file.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | ✅ | Article URL |
| `format` | string | ❌ | "pdf", "html", "json", "md" |

---

### `medium_tts`
Convert article to audio.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string | ✅ | Article URL |
| `voice` | string | ❌ | Voice name (default: "george") |

---

## Error Codes

| Code | HTTP | Description |
|------|------|-------------|
| `INVALID_URL` | 400 | Invalid URL format |
| `ARTICLE_NOT_FOUND` | 404 | Article not found |
| `RATE_LIMITED` | 429 | Rate limit exceeded |
| `SCRAPE_FAILED` | 502 | Scraping failed |
| `TIMEOUT` | 504 | Request timeout |

---

## Rate Limits

- **60 requests/minute** per client
- **1000 requests/hour** daily limit
- Burst limit: 10 requests

---

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GROQ_API_KEY` | ✅ | Groq API for LLM |
| `ELEVENLABS_API_KEY` | ❌ | ElevenLabs TTS |
| `GEMINI_API_KEY` | ❌ | Gemini fallback |