Skip to main content
Glama
Metalsmith Plugin MCP Server

Metalsmith Plugin MCP Server

by wernerglinka

Metalsmith Plugin MCP Server

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

metalsmith:plugin npm: version license: MIT test coverage Known Vulnerabilities

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

Related MCP server: packkit-mcp

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

License

MIT © Werner Glinka


Available Tools

7 tools
configsC

Generate configuration files following enhanced standards.

Inputs: configs, outputPath.

diff-templateA

Diff a plugin against the current scaffold templates. Reports which files match, are missing, or have drifted (with unified diff snippets). Use to keep aging plugins in sync with the latest scaffold.

Inputs: path, templates.

install-claude-mdA

Install a CLAUDE.md in an existing Metalsmith plugin. Smart-merges the MCP Server Integration section into any existing CLAUDE.md so user customizations survive.

Inputs: path, dryRun, replace.

list-templatesA

List every template the server can hand back via get-template. Call this before guessing a template name.

Inputs: no named parameters.

plugin-scaffoldA

Scaffold a complete Metalsmith plugin (src/, test/, package.json, README.md, CLAUDE.md, GitHub workflows). Use only for NEW plugins in an empty directory — never against an existing project. Pass the user's exact plugin name (do not add a metalsmith- prefix); both name and description are required.

Inputs: name (required), description (required), license, features, +1 more.

update-depsB

Update dependencies in Metalsmith plugin(s) using npm-check-updates.

Inputs: path, major, dryRun, interactive.

validateB

Check an existing Metalsmith plugin against quality standards.

Inputs: path (required), checks, functional.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: installing CLAUDE.md, scaffolding new plugins, listing templates, validating, generating configs, diffing against templates, and updating deps. No overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent hyphenated lowercase pattern (e.g., install-claude-md, plugin-scaffold). Verbs are clear and naming conventions are uniform throughout.

    Tool Count5/5

    Seven tools is a well-scoped set for a plugin development server, covering scaffolding, validation, configuration, dependency updates, and template management without being overwhelming or sparse.

    Completeness4/5

    The tool set covers the main plugin creation and maintenance lifecycle: scaffold, validate, diff, update deps, install CLAUDE.md. A minor gap is the lack of a tool for running tests or building, but core workflows are well-supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables scaffolding, validating, and managing plugins for the Motor Agéntico ecosystem, with tools to generate plugin structures and verify compliance with the plugin standard.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Lets AI agents scaffold modern npm packages, CLIs, HTTP services, and apps as a native tool. Three tools: inspect the full option/preset schema, preview the generated file tree for a config, and write the project to disk.
      3
      119 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Swiss-Army developer toolkit, stdio inspector, scaffolding CLI & built-in suite of developer tools for Model Context Protocol (MCP) servers.
      1
      MIT