# 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/ tech_radar_mcp/ tests/
```

---

---

# Tech Radar & Career Intelligence MCP

An autonomous **Tech Radar** server that keeps you current on the engineering tech landscape — aggregating top articles across favorite publications, extracting clean content for AI synthesis, generating progressive learning roadmaps, and evaluating live job market demand signals — all without any paid API keys.

---

## Tech Radar Features

- **Multi-Source Article Discovery**:
  - `get_top_articles`: Query top-voted, trending, or newest articles filtered by topics/tags across all tracked sources.
  - `list_trending_tech`: Return the top trending tags and categories observed across cached articles.

- **Source Onboarding (`setup_source`)**:
  - Register any tech publication by name or domain — presets for `bytebytego`, `devto`, `baeldung`, `medium`, `dailydev`.
  - Auto-discovers RSS/Atom feeds from HTML `<link rel="alternate">` tags or common probe paths (`/feed`, `/rss`, `/atom.xml`).
  - `list_sources`: Inspect all configured publications and sync metadata.

- **Article Content Extraction**:
  - `extract_article_content`: Fetches the article URL and returns clean, structured Markdown stripped of boilerplate (`<nav>`, `<script>`, `<header>`, `<aside>`), with code blocks and architecture headings preserved for AI synthesis.

- **Career & Job Market Intelligence**:
  - `assess_job_market`: Queries public developer job feeds (RemoteOK) for a target topic, returning hiring demand level (`HIGH`, `MODERATE`, `EMERGING`, `NICHE`), top required adjacent skills, sample roles, and estimated salary ranges — cached for 24 hours in local SQLite.

- **AI Learning Roadmap Prompt**:
  - `generate_tech_roadmap`: Prompt template guiding your agent through a structured 4-stage milestone curriculum for any engineering topic, informed by live trending articles and market demand signals.

- **MCP Resources**:
  - `techradar://sources`: JSON snapshot of all active tracked publications.
  - `techradar://trending`: Top 20 trending articles across all sources.

---

## Tech Radar Installation & Setup

### 1. Requirements
- Python 3.11+
- No external databases or paid API keys required

### 2. Environment Variables (Optional)

| Variable | Default | Description |
|---|---|---|
| `TECH_RADAR_DB_PATH` | `~/.tech-radar/radar.db` | Path to local SQLite database |
| `TECH_RADAR_CACHE_TTL_MINS` | `30` | Article cache TTL in minutes |
| `TECH_RADAR_MAX_ARTICLES_PER_SOURCE` | `25` | Max articles fetched per source per sync |
| `TECH_RADAR_REQUEST_TIMEOUT` | `15.0` | HTTP request timeout in seconds |

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

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

```json
{
  "mcpServers": {
    "tech-radar": {
      "command": "/run/media/normdevstorm/data-linux/dang-cay/agentic_ai/projects/normdevblog/mcp-server/.venv/bin/python",
      "args": ["-m", "tech_radar_mcp"],
      "env": {
        "TECH_RADAR_DB_PATH": "/home/<YOUR_USER>/.tech-radar/radar.db",
        "TECH_RADAR_CACHE_TTL_MINS": "30"
      }
    }
  }
}
```AdminTagController#createTag

---

## Tech Radar Usage Examples

### Register a publication
```
setup_source(name="bytebytego")
# → Registers https://blog.bytebytego.com/feed immediately

setup_source(name="martinfowler.com")
# → Auto-discovers feed URL from <link rel="alternate"> tags
```

### Discover trending AI content
```
get_top_articles(tags=["agentic-ai", "llm"], sort_by="TRENDING", limit=5)
list_trending_tech(domain="graph-engineering", limit=10)
```

### Extract article for AI synthesis
```
extract_article_content(url="https://dev.to/example/ai-agents-deep-dive")
# → Returns clean Markdown + extracted code blocks
```

### Assess tech job market
```
assess_job_market(topic="AI Agent")
# → Returns demand_level, top_skills, sample_roles, typical_salary_range
```

### Generate learning roadmap
```
generate_tech_roadmap(topic="Graph RAG", current_level="intermediate")
# → Prompts the agent to build a 4-stage milestone curriculum
```

---

## Tech Radar — Running Tests & Linting

```bash
cd mcp-server
.venv/bin/pytest tests/test_tech_radar_*.py -v
.venv/bin/ruff check tech_radar_mcp/ tests/test_tech_radar_*.py
```