Metalsmith Plugin MCP Server

MCP server for scaffolding and validating high-quality Metalsmith plugins.

This MCP (Model Context Protocol) server gives Claude and other AI clients a small, opinionated toolkit for creating and maintaining Metalsmith plugins. Scaffolded plugins are ESM-only (Node 22+), use Biome for unified lint + format, and run tests via the native node:test runner with native coverage. CommonJS consumers can still require() ESM-only plugins via Node 22's stable require(esm).

Use it two ways: as an MCP server inside Claude Desktop / Claude Code, or directly from the terminal with npx.

Documentation

• docs/tools.md — per-tool MCP reference (options, examples, validation rules)
• docs/cli.md — full CLI command reference
• docs/setup.md — installing the server in Claude Desktop or Claude Code
• MIGRATION.md — upgrading existing plugins to the current scaffold
• CHANGELOG.md / GitHub releases — version history
• CONTRIBUTING.md — contributing guidelines
• TESTING.md — testing the server locally
• RELEASE.md — release process

Installation

npm install -g metalsmith-plugin-mcp-server

Or use directly with npx (no install):

npx metalsmith-plugin-mcp-server --help

Quick start

Scaffold a new plugin:

npx metalsmith-plugin-mcp-server scaffold metalsmith-my-plugin "Processes markdown files" ./plugins

Validate an existing plugin:

npx metalsmith-plugin-mcp-server validate ./metalsmith-my-plugin

Use with Claude Code:

claude mcp add metalsmith-plugin npx "metalsmith-plugin-mcp-server@latest" "server"

Then in Claude: "Create a Metalsmith plugin called metalsmith-json-feed that generates JSON feeds from markdown files." See docs/setup.md for the full setup, including Claude Desktop config.

Available tools

Tool	What it does
plugin-scaffold	Generate a complete plugin (src/, test/, package.json, README.md, CLAUDE.md, GitHub workflows). Use only for new plugins in an empty directory.
validate	Check an existing plugin against 17 quality checks (structure, tests, docs, package shape, native methods, marketing language, hardcoded values, etc.)
audit-plugin	Validation + lint + tests + coverage in one health report
configs	Generate config files (biome.json, .release-it.json, .editorconfig, .gitignore)
show-template	Display a canonical config template (release-it, package-scripts, biome, etc.)
list-templates	List every template the server can hand back
get-template	Retrieve a specific template file verbatim
install-claude-md	Add or smart-merge a CLAUDE.md into an existing plugin
diff-template	Detect drift between a plugin and the current scaffold templates
update-deps	Update dependencies via npm-check-updates

The CLI adds batch-audit for processing every plugin in a directory.

See docs/tools.md for full options, examples, and the complete list of validation checks.

What a scaffolded plugin looks like

A plugin-scaffold call produces:

• ESM-only package.json ("type": "module", "exports": "./src/index.js") — no build step, no lib/, no microbundle
• src/index.js using the two-phase plugin factory pattern
• test/index.test.js using node:test + node:assert/strict against a real Metalsmith instance
• biome.json for unified lint + format
• Native test coverage via node --test --experimental-test-coverage
• README.md, CLAUDE.md, docs/THEORY.md skeletons
• .github/workflows/test.yml, test-matrix.yml, claude-code.yml
• .github/dependabot.yml
• scripts/release.sh for secure manual releases (gh auth token based)

The scaffold enforces use of Metalsmith's native methods (metalsmith.debug(), metalsmith.match(), metalsmith.env(), metalsmith.path()) over external debug, minimatch, process.env, or path.join.

Validation philosophy

The validate tool returns four categories:

• Passed — requirement met
• Failed — must-fix
• Warnings — quality concern (low coverage, unfilled THEORY.md stub)
• Recommendations — optional, with the exact command you can paste

Naming and license are recommendations, never failures — author choice is respected. Each check lives in its own file under src/tools/validate/checks/ and is described in docs/tools.md.

Plugin types

The scaffold supports the three common plugin shapes:

• Processor — transforms file contents (markdown rendering, image optimization)
• Transformer — reshapes file metadata or structure (permalinks, collections)
• Validator — checks files against rules (HTML validation, link checking)

Contributing

See CONTRIBUTING.md. Before any commit:

npm run lint
npm run format
npm test

Resources

• Metalsmith Documentation
• Model Context Protocol Specification

License

MIT © Werner Glinka

---