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

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):

{
  "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

Verification

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:

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