# 🚀 Hashnode MCP Server v2.0

A production-ready Model Context Protocol (MCP) server for Hashnode, deployable on **Zeabur**. Publish, update, and manage your Hashnode blog via AI assistants from anywhere!

## ✨ Features

| Feature | Description |
|---------|-------------|
| 📝 **11 Powerful Tools** | Complete CRUD operations for articles |
| 🔧 **Flexible Publication ID** | Use env var OR pass per-tool |
| 🏷️ **Smart Tag Handling** | Auto-converts tags to Hashnode format |
| 🖼️ **Cover Images** | Set cover images via URL |
| 🔍 **Search & Discovery** | Search across Hashnode |
| 📚 **Publication Management** | List publications, get details |
| 🗑️ **Delete Articles** | Remove posts permanently |
| 💡 **Smart Errors** | Clear error messages with fix hints |

## 🛠️ Available Tools (11 Total)

### Connection & Setup
| Tool | Purpose |
|------|---------|
| `test_connection` | Verify API token works |
| `list_publications` | Show your publications and IDs |

### Article Management
| Tool | Purpose |
|------|---------|
| `publish_article` | Publish immediately with tags, cover image |
| `create_draft` | Save as draft |
| `update_article` | Edit existing posts |
| `delete_article` | Delete permanently |
| `get_article` | Get full article details |

### Discovery
| Tool | Purpose |
|------|---------|
| `list_my_articles` | List your publication's articles |
| `get_user_articles` | Get articles by username |
| `search_articles` | Search across Hashnode |
| `get_publication` | Get publication info |

## 🚀 Deploy on Zeabur

### Step 1: Get Hashnode Credentials

1. **Personal Access Token (PAT)**:
   - Go to [Hashnode Developer Settings](https://hashnode.com/settings/developer)
   - Click "Generate new token"
   - Copy the token

2. **Publication ID** (optional - can use per-tool instead):
   - Go to your blog dashboard
   - Copy ID from URL: `https://hashnode.com/{PUBLICATION_ID}/dashboard`
   - Or use `list_publications` tool after deployment

### Step 2: Deploy

1. Fork/clone this repo and push to GitHub
2. Go to [Zeabur Dashboard](https://dash.zeabur.com)
3. Create Project → Deploy from GitHub
4. Select your repo
5. **Add Environment Variables** (optional but recommended):
   
   | Variable | Value | Required |
   |----------|-------|----------|
   | `HASHNODE_PERSONAL_ACCESS_TOKEN` | Your PAT | ✅ Yes |
   | `HASHNODE_PUBLICATION_ID` | Your publication ID | ❌ No (can use per-tool) |

6. Click **Deploy**

### Step 3: Get Your URL

After deployment, copy your URL:
```
https://your-app-name.zeabur.app/sse
```

## 🔌 Connect to AI Assistants

### Claude Desktop / Cline Config:
```json
{
  "mcpServers": {
    "hashnode": {
      "url": "https://your-app.zeabur.app/sse"
    }
  }
}
```

**Config file locations:**
- **Claude Desktop**:
  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Cline VSCode**:
  - Windows: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
  - macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

### Cursor Config:
```json
{
  "mcpServers": {
    "hashnode": {
      "url": "https://your-app.zeabur.app/sse"
    }
  }
}
```

## 📖 Usage Examples

### First Time Setup
```markdown
"Test my Hashnode connection"
```

```markdown
"List my publications to see their IDs"
```

### Publishing Articles

**With default publication (env var set):**
```markdown
"Publish an article titled 'Getting Started with Python' 
with content '# Introduction\n\nPython is great...' 
and tags python, tutorial, beginners"
```

**With specific publication ID:**
```markdown
"Publish to publication ID 'abc123' an article titled 'Advanced GraphQL' 
with tags graphql, api, content: '## GraphQL Tips\n\nHere are tips...'"
```

**With cover image:**
```markdown
"Create a draft titled 'My Post' with cover image 
https://example.com/image.png and tags technology"
```

### Managing Articles
```markdown
"List my last 20 articles"
```

```markdown
"Get article details for post ID 'post_id_here'"
```

```markdown
"Update article 'post_id_here' with new title 'Updated Title'"
```

```markdown
"Delete article 'post_id_here'"
```

### Discovery
```markdown
"Search for articles about 'machine learning'"
```

```markdown
"Get articles by username 'john_doe'"
```

```markdown
"Get publication details for host 'blog.hashnode.dev'"
```

## 🔧 Tool Parameters Reference

### Common Parameters
Most article tools accept these parameters:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | ✅ | Article title |
| `content_markdown` | string | ✅ | Article content in Markdown |
| `subtitle` | string | ❌ | Optional subtitle |
| `tags` | string[] | ❌ | Array of tag names (auto-converted to lowercase-slug) |
| `cover_image_url` | string | ❌ | URL for cover image |
| `publication_id` | string | ⚠️ | Required if env var not set |

### Tool-Specific Parameters

**update_article:**
- `post_id` (required) - Article ID to update

**delete_article:**
- `post_id` (required) - Article ID to delete

**get_article:**
- `post_id` (required) - Article ID to fetch

**get_user_articles:**
- `username` (required) - Hashnode username
- `page` (optional) - Page number, default 1

**search_articles:**
- `query` (required) - Search query
- `limit` (optional) - Results to return (1-20), default 10

**list_my_articles:**
- `limit` (optional) - Number of articles (1-50), default 10
- `publication_id` (optional) - Override default publication

**get_publication:**
- `host` (required) - Publication host/domain

## ⚠️ Error Messages & Fixes

### "Publication ID is required"
**Fix:** Either:
1. Set `HASHNODE_PUBLICATION_ID` env var in Zeabur, OR
2. Pass `publication_id` parameter to the tool

### "Authentication failed"
**Fix:** Check your `HASHNODE_PERSONAL_ACCESS_TOKEN` is correct and not expired.

### "Tag format invalid"
**Fix:** Tags are auto-converted, but avoid special characters. Use simple names like "python", "web-development".

### "Session not found"
**Fix:** The MCP session expired. Try the request again.

## 🐛 Troubleshooting

### Connection Issues
1. Check Zeabur logs for startup errors
2. Verify `HASHNODE_PERSONAL_ACCESS_TOKEN` is set
3. Test with `test_connection` tool first

### 400 Errors on Publish
Usually means:
- Invalid tag format (fixed automatically now)
- Missing required fields
- Invalid publication ID

Check the error message - it now includes specific fix instructions!

## 📁 Project Structure

```
hashnode-mcp-zeabur/
├── server.js           # Main MCP server (10 tools)
├── package.json        # Node dependencies
├── Dockerfile          # Docker image for Zeabur
├── zeabur.yaml         # Zeabur deployment config
├── .env.example        # Environment template
└── README.md           # This file
```

## 🔐 Security Best Practices

1. **Never commit `.env` file** - It's in `.gitignore`
2. **Use Zeabur's encrypted variables** - They store secrets securely
3. **Rotate PAT regularly** - Regenerate in Hashnode settings if compromised
4. **Restrict publication access** - Only give necessary permissions

## 📚 Useful Links

- [Hashnode API Docs](https://apidocs.hashnode.com/)
- [MCP Specification](https://modelcontextprotocol.io/)
- [Zeabur Documentation](https://zeabur.com/docs)

## 📄 License

MIT License - feel free to use for personal or commercial projects!

---

**Made with ❤️ for the Hashnode community**