# DEV.to MCP Server 🚀

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for **[DEV.to](https://dev.to)** (Forem API) built with Python and FastMCP.

This server enables AI assistants (Antigravity, Claude Desktop, Cursor, etc.) to browse, search, and read DEV.to articles, inspect comments and user profiles, explore tags, and publish or update draft and live articles.

---

## ✨ Features

- **Public Tools (No API Key Required)**:
  - 📰 **List & Filter Articles**: Browse by tags, author username, status (`fresh`, `rising`), or top timeframe.
  - 🕒 **Latest Articles**: Stream recent publications.
  - 📖 **Full Article Reading**: Fetch complete article metadata and raw Markdown body by article ID.
  - 🔍 **Search**: Natural query ranking over DEV.to content and tags.
  - 💬 **Discussion & Comments**: Read threaded comment trees for any article or comment ID.
  - 👤 **User Profiles**: Inspect public user bios, social handles, and publication statistics.
  - 🏷️ **Tags**: Explore trending and popular community tags.
- **Authenticated Tools (Requires `DEVTO_API_KEY`)**:
  - 📝 **Draft & Publish Articles**: Create new articles directly from chat in draft or published mode.
  - ✏️ **Update Articles**: Modify article titles, Markdown content, or publishing status.
  - 📊 **My Articles**: List private draft and published articles with view and reaction stats.
  - 🔐 **Account Details**: Query the authenticated user's private profile.

---

## 🛠️ Installation & Setup

### 1. Clone & Set Up Environment

```bash
cd /path/to/devto-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install package and dependencies in editable mode
pip install -e ".[dev]"
```

### 2. Configure API Key (Optional for Read Operations)

To publish articles or view your own drafts, generate an API key from:
👉 **[DEV Settings -> Extensions -> DEV Community API Keys](https://dev.to/settings/extensions)**

Copy `.env.example` to `.env` and set your key:

```bash
cp .env.example .env
```

```env
DEVTO_API_KEY=your_devto_api_key_here
```

---

## 🔌 Client Configurations

### Antigravity IDE Setup

Add the following to your Antigravity MCP configuration (e.g. `~/.gemini/antigravity/mcp/devto.json` or project MCP config):

```json
{
  "mcpServers": {
    "devto": {
      "command": "/path/to/devto-mcp/.venv/bin/python",
      "args": ["/path/to/devto-mcp/src/server.py"],
      "env": {
        "DEVTO_API_KEY": "your_devto_api_key_here"
      }
    }
  }
}
```

### Claude Desktop Setup

In `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "devto": {
      "command": "/path/to/devto-mcp/.venv/bin/python",
      "args": ["/path/to/devto-mcp/src/server.py"],
      "env": {
        "DEVTO_API_KEY": "your_devto_api_key_here"
      }
    }
  }
}
```

### Cursor Setup

In **Cursor Settings -> Features -> MCP**:
- **Name**: `devto`
- **Type**: `command`
- **Command**: `/path/to/devto-mcp/.venv/bin/python /path/to/devto-mcp/src/server.py`

---

## 🧰 Available MCP Tools

| Tool | Access | Description |
| :--- | :--- | :--- |
| `devto_list_articles` | Public | List & filter articles by `tag`, `username`, `state` (`fresh`/`rising`), `top` (days), and pagination. |
| `devto_get_latest_articles` | Public | Get the latest articles in reverse chronological order. |
| `devto_get_article` | Public | Fetch full article metadata and raw Markdown body by integer `article_id`. |
| `devto_search_articles` | Public | Search articles by text `query` and optional `tag`. |
| `devto_get_comments` | Public | Fetch nested discussion comments for an `article_id`. |
| `devto_get_comment` | Public | Fetch a specific comment thread by `comment_id`. |
| `devto_get_user_profile` | Public | Fetch user bio, social handles, and metadata by `username` or `user_id`. |
| `devto_get_tags` | Public | List popular tags with descriptions and colors. |
| `devto_get_my_articles` | Auth | List authenticated user's articles by `status` (`all`, `published`, `unpublished`). |
| `devto_get_me` | Auth | Fetch authenticated user's account details. |
| `devto_create_article` | Auth | Create a draft or published article with title, markdown body, tags, series, etc. |
| `devto_update_article` | Auth | Update an existing article's title, body, publication status, or tags. |

---

## 🧪 Running Tests

Run the test suite using `pytest`:

```bash
.venv/bin/pytest -v
```

---

## 🛡️ Privacy, Anonymization & Public Showcase

This project is built from the ground up to be 100% safe for public articles, tutorials, video demos, and open source showcases:

- **Local Secrets Stay Local:** Credentials like `DEVTO_API_KEY` are stored in `.env`, which is strictly ignored by `.gitignore`. No private keys or tokens will ever be committed to version control.
- **Built-in Showcase / Demo Mode (`DEVTO_DEMO_MODE=true`):**
  If you are recording a video, writing an article, or taking screenshots, you can enable Demo Mode to return realistic synthetic data (anonymized author profile `@demo_author`, mock drafts, safe simulated publishing) without needing an API key or modifying production DEV.to accounts:
  ```bash
  # Enable Demo Mode via environment variable
  DEVTO_DEMO_MODE=true python -m src.server
  ```
- **Automated Showcase Script:**
  Run the bundled demonstration script to execute and print all core tool interactions with sanitized outputs:
  ```bash
  python scripts/demo.py
  ```

---

## 📄 License

MIT