# Dev.to Article MCP

An offline-first Model Context Protocol server that lets Kiro validate repository-native Dev.to Markdown, preview/apply conservative frontmatter fixes, and create a real **unpublished** Dev.to draft through the official Forem API.

## Why this MCP exists

Kiro can edit files, but it does not inherently know this repository's article tree, publishing constraints, changed-file set, or safe draft workflow. This server adds deterministic diagnostics and a guarded bridge from local content to Dev.to without exposing publish, update, delete, browse, or community-API tools.

## Requirements

- Node.js 24+
- npm
- Git (for `validate_changed_articles`)
- A Dev.to API key only for live draft creation

## Setup

```bash
npm ci
npm run build
```

Configure the built stdio server in your MCP host. Prefer loading secrets from a
gitignored `.env` via Node's `--env-file` (do not put the real key in `mcp.json`):

```json
{
  "mcpServers": {
    "devto-article-mcp": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/devto-article-mcp/.env",
        "/absolute/path/devto-article-mcp/dist/src/index.js"
      ],
      "env": {
        "WORKSPACE_ROOT": "/absolute/path/to/your/repository",
        "ARTICLES_ROOT": "articles"
      }
    }
  }
}
```

Create `.env` from `.env.example` and set `DEVTO_API_KEY` there. Never commit `.env`.

## Tools

- `validate_article(file)` — validate one workspace-relative Markdown file.
- `validate_articles(directory?)` — recursively validate Markdown (defaults to `ARTICLES_ROOT`).
- `validate_changed_articles(base?)` — validate staged, unstaged, untracked, or base-relative articles.
- `fix_article(file, mode, hashes, decisions?)` — preview or atomically apply the exact reviewed fix plan.
- `create_devto_draft(file)` — validate, then create an unpublished draft with `published: false`.

All tools remain registered without `DEVTO_API_KEY`; only draft creation returns `API_KEY_MISSING`. The default test suite and all validation/fixing work fully offline.

## Typical Kiro flow

1. “Validate `articles/demo.md`.”
2. Review the path, line, stable rule ID, and suggested correction.
3. “Preview fixes for that article.”
4. Explicitly confirm ambiguous changes such as replacing `dev-to` with `devto`, then apply.
5. Revalidate.
6. “Create an unpublished Dev.to draft from `articles/demo.md`.”
7. Open the returned real Dev.to draft URL and verify it remains unpublished.

The request builder strips local frontmatter from `body_markdown`, maps supported metadata into JSON, and always forces `published: false`. Local IDs and dates are never used for remote updates.

## Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `WORKSPACE_ROOT` / `DEVTO_WORKSPACE_ROOT` | process cwd | Trusted repository root |
| `ARTICLES_ROOT` | `articles` | Relative article directory |
| `DEVTO_API_KEY` | unset | Forem credential for draft creation |
| `DEVTO_API_BASE_URL` | `https://dev.to/api` | Forem API endpoint |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |
| `MAX_FILE_SIZE_BYTES` | `1048576` | Bounded article read size |
| `PHASE2_LIQUID` | `false` | Enable optional Liquid diagnostics |

## Verification

```bash
npm test
npm run typecheck
npm run build
npm run test:coverage
```

The offline suite uses deterministic property-test seeds and is designed to complete in under 30 seconds. A manual command creates one real side-effecting draft:

```bash
DEVTO_API_KEY=... npm run smoke:live-draft -- articles/demo.md
```

This command is intentionally excluded from CI. See `docs/runbook.md` for troubleshooting and `docs/demo/README.md` for the recording checklist.

## Safety and limitations

- Workspace containment rejects traversal, outside absolute paths, and symlink escapes.
- Reads are bounded and require valid UTF-8.
- Validation and draft creation never modify local files.
- Fix apply uses dual hashes and same-directory atomic replacement.
- API keys are never emitted in tool output or logs.
- The remote surface creates drafts only; it cannot publish or mutate existing posts.
- HTML `<img>` validation and Liquid detection are outside the default MVP rule set.

## Architecture

The stdio MCP layer calls isolated tool handlers over a core pipeline: path safety → bounded read → YAML/Markdown parsing → pure rule evaluation → deterministic result aggregation. Git detection, fixing, and the Forem client are separate adapters with structured operational errors.

Demo video: <https://youtu.be/Mm0uAhi0jcs>