# Dev Blog MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to publish blog posts directly to Dev.to. This server provides a seamless way to integrate blog publishing capabilities into your AI workflows.

## Features

- 🚀 **Direct Dev.to Publishing**: Publish blog posts directly to Dev.to via MCP
- 📝 **Rich Content Support**: Full Markdown support with tags, series, and cover images
- 🔒 **Secure API Integration**: Uses environment variables for API key management
- 🛠️ **Easy Integration**: Simple setup with uv package manager
- 📊 **Comprehensive Logging**: Detailed logging for debugging and monitoring

## Prerequisites

Before you begin, ensure you have the following installed:

- **Python 3.13+**
- **uv** (Python package manager)
- **Git** (for version control)
- **Dev.to API Key** (get it from [Dev.to Settings](https://dev.to/settings/account))

## Installation

### 1. Install uv (if not already installed)

```bash
# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv
```

### 2. Clone the Repository

```bash
git clone https://github.com/anuragck2/dev-blog-mcp-server.git
cd dev-blog-mcp-server
```

### 3. Install Dependencies

```bash
# Install project dependencies using uv
uv sync
```

### 4. Environment Setup

Create a `.env` file in the project root:

```bash
# Copy the example environment file
cp .env.example .env

# Edit the .env file and add your Dev.to API key
echo "DEVTO_API_KEY=your_devto_api_key_here" > .env
```

**Get your Dev.to API key:**
1. Go to [Dev.to Settings](https://dev.to/settings/account)
2. Scroll down to the "API Keys" section
3. Generate a new API key
4. Copy the key and add it to your `.env` file

## Usage

### Running the MCP Server

```bash
# Activate the virtual environment and run the server
uv run python main.py
```

The server will start and listen for MCP connections via stdio transport.

### Using with MCP Inspector

The MCP Inspector is a powerful tool for testing and debugging MCP servers. Here's how to set it up:

#### 1. Install MCP Inspector

```bash
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector
```

#### 2. Configure MCP Inspector

Create a configuration file for the MCP Inspector:

```json
{
  "mcpServers": {
    "dev-blog-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/your/dev-blog-mcp-server"
    }
  }
}
```

#### 3. Run MCP Inspector

```bash
# Start the MCP Inspector
mcp-inspector
```

This will open a web interface where you can:
- Test the `publish_blog_to_devto` tool
- View server logs
- Debug MCP communication
- Monitor tool execution

### Using with Claude Desktop

To use this MCP server with Claude Desktop:

1. **Open Claude Desktop Settings**
2. **Add MCP Server Configuration**

Add the following to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "dev-blog-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/your/dev-blog-mcp-server"
    }
  }
}
```

3. **Restart Claude Desktop**

After adding the configuration, restart Claude Desktop to load the new MCP server.

## API Reference

### `publish_blog_to_devto` Tool

Publishes a blog post to Dev.to with the following parameters:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `title` | string | ✅ | The title of the blog post |
| `body_markdown` | string | ✅ | The content in Markdown format |
| `tags` | List[string] | ❌ | List of tags (e.g., ["python", "webdev"]) |
| `published` | boolean | ❌ | Set to `true` to publish immediately, `false` for draft |
| `series` | string | ❌ | The name of the series this article belongs to |
| `canonical_url` | string | ❌ | Canonical URL if cross-posted |
| `cover_image` | string | ❌ | URL of the cover image |

### Example Usage

```python
# Example tool call
publish_blog_to_devto(
    title="Getting Started with MCP",
    body_markdown="# Introduction\n\nThis is a great article about MCP!",
    tags=["mcp", "ai", "tutorial"],
    published=False,  # Save as draft
    series="MCP Fundamentals"
)
```

## Development

### Project Structure

```
dev-blog-mcp-server/
├── main.py              # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── .env.example         # Environment variables template
├── sample_prompt.md     # Sample prompts for testing
├── README.md           # This file
└── uv.lock             # Dependency lock file
```

### Adding New Features

1. **Add new tools** by creating functions decorated with `@mcp.tool()`
2. **Update dependencies** in `pyproject.toml`
3. **Test with MCP Inspector** before deploying
4. **Update documentation** in this README

### Testing

```bash
# Run the server in development mode
uv run python main.py

# Test with MCP Inspector
mcp-inspector
```

## Troubleshooting

### Common Issues

1. **"DEVTO_API_KEY environment variable not set"**
   - Ensure your `.env` file exists and contains the correct API key
   - Verify the API key is valid and has the necessary permissions

2. **"Network or API request error"**
   - Check your internet connection
   - Verify the Dev.to API is accessible
   - Ensure your API key has not expired

3. **MCP Inspector connection issues**
   - Verify the server is running
   - Check the configuration file paths
   - Ensure all dependencies are installed

### Debug Mode

Enable debug logging by modifying the logging level in `main.py`:

```python
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- 📧 **Issues**: [GitHub Issues](https://github.com/anuragck2/dev-blog-mcp-server/issues)
- 📖 **Documentation**: [MCP Documentation](https://modelcontextprotocol.io/)
- 🐦 **Twitter**: [@anuragck2](https://twitter.com/anuragck2)

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) for the amazing MCP framework
- [Dev.to](https://dev.to/) for providing the publishing API
- [uv](https://github.com/astral-sh/uv) for the fast Python package manager
- [FastMCP](https://github.com/jlowin/fastmcp) for the excellent MCP server framework

---

**Happy Blogging! 🚀**