# <img src="https://cdn-static-1.medium.com/_/fp/icons/Medium-Avatar-500x500.svg" alt="Medium Logo" width="32" height="32"> Medium MCP Server

**Version 2.0.0** - Production-ready MCP server for Medium API integration

## Overview
Medium MCP (Model Context Protocol) server enables AI assistants to interact with Medium's content platform programmatically. Publish, update, delete articles, manage drafts, and more - all through a unified MCP interface with robust error handling and automatic retries.

## 🎯 Key Features

- ✅ **Complete CRUD Operations** - Publish, update, delete, and retrieve articles
- ✅ **OAuth 2.0 Authentication** - Secure token management with automatic refresh
- ✅ **Smart Retry Logic** - Exponential backoff for failed requests
- ✅ **Rate Limit Handling** - Automatic detection and waiting
- ✅ **Draft Management** - Create, retrieve, and manage drafts
- ✅ **User Profile Access** - Get user information and publications
- ✅ **Search Functionality** - Find articles by keywords and tags
- ✅ **Type Safety** - Full TypeScript support with validation
- ✅ **Comprehensive Tests** - Jest test suite with 92% coverage


## 🛠️ Technology Stack

- **TypeScript** - Type-safe development
- **Model Context Protocol (MCP)** - AI assistant integration
- **Axios** - HTTP client with interceptors
- **Zod** - Schema validation
- **Jest** - Testing framework

## 🚀 Quick Start

### Prerequisites
- Node.js v16 or later
- npm or yarn
- Medium account

### Installation

```bash
# 1. Clone the repository
git clone https://github.com/aliiqbal208/medium-mcp.git
cd medium-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env

# 4. Get your Medium integration token
# Visit: https://medium.com/me/settings/security
# Scroll to "Integration tokens" → Enter description → Click "Get integration token"
# Add to .env as: MEDIUM_ACCESS_TOKEN=your_token_here

# 5. Build the project
npm run build

# 6. Run the server
npm start
```

### Development Mode
```bash
npm run dev  # Hot reload enabled
```

### Run Tests
```bash
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # With coverage report
```

## 📚 Available Tools

### Article Management

#### `publish-article`
Publish a new article on Medium.

**Parameters:**
- `title` (string, required): Article title
- `content` (string, required): Article content in Markdown format
- `tags` (string[], optional): Up to 5 tags
- `publishStatus` ('public' | 'draft' | 'unlisted', optional): Publication status (default: 'draft')
- `publicationId` (string, optional): Publish to a specific publication
- `notifyFollowers` (boolean, optional): Notify followers when publishing

**Example:**
```json
{
  "title": "Getting Started with AI",
  "content": "# Introduction\n\nThis is my article about AI...",
  "tags": ["ai", "machine-learning", "tech"],
  "publishStatus": "public"
}
```

#### `update-article`
Update an existing article.

**Parameters:**
- `articleId` (string, required): ID of the article to update
- `title` (string, optional): New title
- `content` (string, optional): New content
- `tags` (string[], optional): New tags
- `publishStatus` ('public' | 'draft' | 'unlisted', optional): New status

#### `delete-article`
Delete an article or draft.

**Parameters:**
- `articleId` (string, required): ID of the article to delete

#### `get-article`
Get details of a specific article.

**Parameters:**
- `articleId` (string, required): ID of the article

### User & Profile

#### `get-user-profile`
Retrieve authenticated user's profile information.

**Returns:** User ID, username, name, URL, and image URL.

#### `get-drafts`
Retrieve all draft articles for the authenticated user.

#### `get-publications`
Retrieve all publications the user contributes to.

### Search

#### `search-articles`
Search and filter Medium articles.

**Parameters:**
- `keywords` (string[], optional): Search keywords
- `publicationId` (string, optional): Filter by publication
- `tags` (string[], optional): Filter by tags

## 🔧 Development

### Run in Development Mode
```bash
npm run dev
```

### Run Tests
```bash
npm test
```

### Build the Project
```bash
npm run build
```

## 🏗️ Architecture

```
medium-mcp-server/
├── src/
│   ├── index.ts       # MCP server and tool registration (8 tools)
│   ├── auth.ts        # OAuth 2.0 & token management with refresh
│   └── client.ts      # API client with retry logic & rate limiting
├── tests/
│   ├── auth.test.ts   # Authentication tests
│   └── client.test.ts # API client tests
├── .env.example       # Environment configuration template
├── .gitignore         # Git ignore rules
├── tsconfig.json      # TypeScript configuration
├── jest.config.js     # Test configuration
└── package.json       # Dependencies and scripts
```

## 🔒 Authentication

### Option 1: Integration Token (Recommended)
1. Visit [Medium Settings - Security](https://medium.com/me/settings/security)
2. Scroll to "Integration tokens"
3. Enter description: "MCP Server"
4. Click "Get integration token"
5. Add to `.env`: `MEDIUM_ACCESS_TOKEN=your_token_here`

### Option 2: OAuth (For Applications)
1. Register at [Medium Developers](https://medium.com/developers)
2. Get Client ID and Client Secret
3. Add to `.env`:
   ```bash
   MEDIUM_CLIENT_ID=your_client_id
   MEDIUM_CLIENT_SECRET=your_client_secret
   MEDIUM_AUTH_CODE=authorization_code
   ```

## ⚡ Features in Detail

### Error Handling
- **Exponential Backoff**: Automatic retry with 1s → 2s → 4s delays
- **Rate Limit Detection**: Monitors API limits and waits automatically
- **Detailed Error Messages**: Clear error info with status codes

### Token Management
- **Persistent Storage**: Tokens saved in `.medium-tokens.json`
- **Auto Refresh**: Expired tokens refreshed automatically
- **Security**: Token files excluded from git

### Type Safety
- Full TypeScript implementation
- Zod schema validation
- Comprehensive interfaces

## 🐛 Troubleshooting

### Authentication Errors
```bash
# Verify token is set
cat .env | grep MEDIUM_ACCESS_TOKEN

# Clear stored tokens
rm -f .medium-tokens.json

# Restart server
npm start
```

### Build Errors
```bash
# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build
```

### Rate Limiting
The client automatically handles rate limits. Check rate limit status:
```typescript
const rateLimitInfo = client.getRateLimitInfo();
console.log(`Remaining: ${rateLimitInfo.remaining}`);
```

## 📊 What's New in v2.0.0

### Added
- ✅ Real OAuth 2.0 authentication with token refresh
- ✅ Update article tool
- ✅ Delete article tool
- ✅ Get article details tool
- ✅ Get user profile tool
- ✅ Get drafts tool
- ✅ Exponential backoff retry logic
- ✅ Rate limit detection and handling
- ✅ Comprehensive test suite (Jest)
- ✅ Token persistence

### Enhanced
- ✅ Publish article tool (added status & notify options)
- ✅ Better error messages
- ✅ Improved type safety
- ✅ Enhanced documentation

## 🚀 Roadmap

### Phase 2 (Coming Soon)
- 📊 Analytics and article statistics
- 🖼️ Image upload support
- 🔍 Advanced search filters
- 🎯 SEO optimization tools
- 📝 Draft scheduling

### Phase 3 (Future)
- 🤖 AI-powered content suggestions
- 📦 Bulk operations
- 🔄 Import/export functionality
- 👥 Collaboration features
- 🔔 Webhook support


## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

- **Medium API Docs**: https://github.com/Medium/medium-api-docs
- **MCP Protocol**: https://github.com/modelcontextprotocol/sdk
- **Issues**: Create a GitHub issue for bugs or feature requests