# NormDevBlog MCP Server

The Model Context Protocol (MCP) server for **NormDevBlog**. Connects AI-powered editors (such as **Google Antigravity**, **Cursor**, **Claude Desktop**, and **Windsurf**) directly to your NormDevBlog backend for post authoring, local Markdown synchronization, taxonomy management, and safe administrative actions.

---

## Features

- **Article Management**:
  - `list_articles`: Discover published and draft articles with category/tag filtering.
  - `get_article`: Pull article content and YAML frontmatter metadata.
  - `create_article`: Create drafts or publish immediately.
  - `update_article`: Edit titles, summaries, content, categories, and tags.
  - `publish_article` / `unpublish_article`: Manage publishing state.
- **Two-Way Local Sync**:
  - `sync_down_articles`: Export posts to a local folder as Markdown files with YAML frontmatter.
  - `sync_up_article`: Read edited local Markdown files and sync updates or new posts to the backend.
- **Human-Gated Safe Deletions**:
  - `delete_article` & `delete_tag`: Require explicit `confirmed=True` to execute; otherwise, returns an informative safety warning without modifying data.
- **Taxonomy Management**:
  - `list_categories` & `create_category`
  - `list_tags`, `create_tag`, & `delete_tag`
- **MCP Resources & Prompt Templates**:
  - Resources: `blog://categories`, `blog://tags`, `blog://articles/recent`
  - Prompts: `draft_blog_post`, `review_frontmatter`

---

## Installation & Setup

### 1. Requirements
- Python 3.11+
- Running NormDevBlog backend (`http://localhost:8080`)

### 2. Setup Virtual Environment
```bash
cd mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3. Configure Editor (e.g. Antigravity / Cursor / Claude Desktop)

Add the server to your editor's MCP server configuration (e.g., `~/.gemini/antigravity-ide/mcp_config.json` or `.vscode/settings.json`):

```json
{
  "mcpServers": {
    "normdevblog": {
      "command": "/run/media/normdevstorm/data-linux/dang-cay/agentic_ai/projects/normdevblog/mcp-server/.venv/bin/python",
      "args": ["-m", "blog_mcp.server"],
      "env": {
        "BLOG_API_BASE_URL": "http://localhost:8080",
        "BLOG_API_TOKEN": "<YOUR_ADMIN_OR_AUTHOR_JWT_TOKEN>"
      }
    }
  }
}
```

---

## Running Tests & Linters

```bash
cd mcp-server
.venv/bin/pytest tests/
.venv/bin/ruff check blog_mcp/ tests/
```