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

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

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