Metalsmith Plugin MCP Server

MCP server for scaffolding and validating high-quality Metalsmith plugins

This MCP (Model Context Protocol) server provides tools for creating and maintaining Metalsmith plugins following quality standards. It encapsulates patterns from the Metalsmith ecosystem, such as @metalsmith/core-plugin and contributed plugins like metalsmith-optimize-images.

What's New in v3.0.0

ESM-Only Scaffold (BREAKING) — Scaffolded plugins no longer ship a CommonJS build. The scaffold publishes src/ directly with "type": "module" and "exports": "./src/index.js", and Node 22+'s stable require(esm) lets CommonJS consumers still require() the plugin without a dual build.

• No build step — microbundle removed; no lib/, no main, no module, no dual exports.import/exports.require
• Single test format — test/index.test.js runs against source; test:esm/test:cjs scripts gone
• Template cleanup — README examples use import/import.meta.dirname; ESM/CommonJS badge removed
• Validation flip — module-consistency check now fails on any require(), module.exports, __dirname, or __filename in README code blocks, and fails when package.json is missing "type": "module"
• Legacy flagging — microbundle, lib/, main/module, and dual-exports fields now surface as modernization recommendations

See MIGRATION.md for step-by-step instructions for existing plugins.

What's New in v2.0.0

Biome + node:test Toolchain Modernization (BREAKING) - Scaffolded plugins use the modern toolchain:

• Biome replaces ESLint + Prettier - Unified lint + format via a single biome.json
• Native node:test replaces Mocha + Chai - Test templates use node:test / node:assert/strict
• Native coverage replaces c8 - node --test --experimental-test-coverage with lcov output
• Node >= 22 - Engine requirement bumped for stable coverage reporter destinations
• MCP schema changes - validate checks enum drops 'eslint' (use 'biome'); configs and show-template enums drop eslint/prettier

Installation

npm install -g metalsmith-plugin-mcp-server

Or use directly with npx (no installation required):

npx metalsmith-plugin-mcp-server --help

MCP Tools

The MCP server provides eight main tools:

1. Plugin Scaffolding

Generate a complete Metalsmith plugin structure with enhanced standards:

await mcp.call('plugin-scaffold', {
  name: 'my-feature', // Uses exact name provided
  description: 'Processes and transforms content based on custom rules',
  features: ['async-processing', 'background-processing', 'metadata-generation'],
  outputPath: './plugins'
});

This creates a fully-configured plugin with:

• ESM-Only Publishing: Ships src/ directly with "type": "module" and "exports": "./src/index.js" — no build step, no lib/, no microbundle. CommonJS consumers can still require() the plugin via Node 22+'s stable require(esm)
• Native Metalsmith Methods: Enforces metalsmith.debug(), metalsmith.match(), metalsmith.env(), metalsmith.path() over external packages
• Zero External Dependencies: Self-contained utilities for pattern matching and config merging
• Complementary CI/CD Architecture: GitHub workflows for automated testing + manual release scripts
• Comprehensive test setup via the native node:test runner
• Production-ready documentation
• Unified lint + format via Biome (biome.json)
• Native coverage via node --test --experimental-test-coverage (no c8/nyc)
• Release automation with GitHub integration
• Deep configuration merging
• Error handling with proper propagation

Professional Development Workflow

GitHub Workflows (.github/workflows/):

• test.yml: Automated CI/CD with Node.js testing, coverage extraction, and README badge updates
• claude-code.yml: AI-assisted code review integration

Release Script (scripts/):

• release.sh: Secure manual release control with GitHub CLI authentication

Benefits:

• Automated Quality Gates: Every PR/push runs tests and updates coverage badges
• Human Release Control: Developers control release timing, not automation
• Professional Standards: Coverage tracking, AI code review, secure authentication
• GitHub Auto-Generated Release Notes: Uses GitHub's automatic release notes feature

2. Plugin Validation

Check existing plugins against quality standards:

await mcp.call('validate', {
  path: './metalsmith-my-plugin',
  checks: [
    'structure',
    'tests',
    'docs',
    'package-json',
    'jsdoc',
    'performance',
    'security',
    'integration',
    'metalsmith-patterns',
    'marketing-language',
    'module-consistency',
    'hardcoded-values',
    'performance-patterns',
    'i18n-readiness'
  ]
});

Validation checks include:

• Structure: Required directories and files
• Tests: Test coverage and fixture setup
• Documentation: README sections, examples, and badges (detects sections at any header level)
• Package.json: Required fields and conventions
• JSDoc: Type definitions, parameter documentation, and return types
• Performance: Efficient files object iteration, Buffer handling, object destructuring
• Security: Build-time security, dependency monitoring, error handling
• Integration: Compatibility with common Metalsmith plugins
• Metalsmith Patterns: Plugin factory patterns, function signatures, metadata handling, native methods usage
• Biome: Unified lint + format configuration presence (biome.json)
• Coverage: Test coverage analysis (prefers native node:test coverage)

Enhanced Quality Standards (addressing Metalsmith maintainer feedback):

• Marketing Language Detection: Flags buzzwords like "intelligent", "smart", "seamless" in documentation
• Module System Consistency: Flags CommonJS syntax (require(), module.exports, __dirname, __filename) in README code blocks — scaffold is ESM-only
• Hardcoded Values Detection: Identifies hardcoded configurations (wordsPerMinute, viewport, etc.) that should be options
• Performance Pattern Analysis: Finds objects redefined in functions, redundant utilities (get, pick, identity)
• Internationalization Readiness: Detects English-only outputs that prevent global plugin usage

CLAUDE.md Integration: The validation system detects existing project standards from CLAUDE.md files and validates against them instead of imposing conflicting recommendations. For example, if your CLAUDE.md specifies npm script release patterns, the validator recognizes this as approved and doesn't suggest shell script alternatives.

3. Configuration Generation

Generate configuration files following enhanced standards:

await mcp.call('configs', {
  outputPath: './my-plugin',
  configs: ['biome', 'editorconfig', 'gitignore', 'release-it']
});

4. Dependency Updates

Update dependencies in Metalsmith plugins using npm's built-in commands:

await mcp.call('update-deps', {
  path: './plugins', // Single plugin or directory containing multiple plugins
  major: false, // Only minor/patch updates by default (safer)
  interactive: false, // Set to true for interactive selection
  dryRun: false // Set to true to see what would be updated without making changes
});

Features:

• Plugin Detection: Finds Metalsmith plugins by checking for metalsmith- prefix
• Batch Processing: Process all plugins in a directory when run from parent folder
• Safety First: Only updates minor/patch versions by default (no breaking changes)
• Comprehensive Reporting: Shows which plugins had updates, failures, and next steps

5. Plugin Audit

Run comprehensive plugin audits combining validation, linting, testing, and coverage:

await mcp.call('audit-plugin', {
  path: './my-plugin',
  fix: true, // Apply automatic fixes where possible
  output: 'json' // Output format: 'console', 'json', or 'markdown'
});

Features:

• Multi-Check Validation: Runs validation, linting, formatting, tests, and coverage
• Health Scoring: Provides overall health assessment (EXCELLENT, GOOD, FAIR, NEEDS IMPROVEMENT, POOR)
• Automatic Fixes: Optional --fix flag to automatically resolve linting and formatting issues
• Multiple Output Formats: Console, JSON, or Markdown reports
• Actionable Feedback: Clear indication of what needs attention

6. Batch Plugin Audit

Audit multiple plugins in a directory and generate summary reports:

await mcp.call('batch-audit', {
  path: './plugins-directory',
  fix: false, // Apply fixes to all plugins
  output: 'console' // Summary format
});

Features:

• Multi-Plugin Discovery: Automatically finds all Metalsmith plugins in a directory
• Comprehensive Reporting: Summary statistics showing plugin health distribution
• Batch Operations: Optionally apply fixes to all plugins at once
• Progress Tracking: Visual progress indicators for each plugin audit
• Problem Identification: Highlights plugins needing immediate attention

Usage

You can use this tool in two ways:

1. Direct CLI Usage: Run commands directly in your terminal using npx for one-off plugin creation or manual control
2. MCP Server: Set up the server for AI assistants (Claude Desktop/Code) for interactive plugin development with AI guidance and natural language requests

Direct CLI Usage (with npx)

The fastest way to get started is using npx directly:

# Show version information
npx metalsmith-plugin-mcp-server version

# Show help and available commands
npx metalsmith-plugin-mcp-server help

# Show current configuration and setup
npx metalsmith-plugin-mcp-server config

# Create a new plugin with guided prompts
npx metalsmith-plugin-mcp-server scaffold

# Create a new plugin with all parameters (expert mode)
npx metalsmith-plugin-mcp-server scaffold my-plugin "Processes and transforms content" ./plugins

# Validate an existing plugin
npx metalsmith-plugin-mcp-server validate ./my-plugin

# Run comprehensive plugin audit
npx metalsmith-plugin-mcp-server audit ./my-plugin

# Run audit with automatic fixes
npx metalsmith-plugin-mcp-server audit ./my-plugin --fix

# Audit multiple plugins in a directory
npx metalsmith-plugin-mcp-server batch-audit ./plugins

# Generate configuration files
npx metalsmith-plugin-mcp-server configs ./my-plugin

# Show all available templates
npx metalsmith-plugin-mcp-server list-templates

# Get specific template content (useful for CLAUDE.md, configs, etc.)
npx metalsmith-plugin-mcp-server get-template plugin/CLAUDE.md
npx metalsmith-plugin-mcp-server get-template configs/release-it.json

# Install CLAUDE.md with AI assistant instructions
npx metalsmith-plugin-mcp-server install-claude-md

# Update dependencies
npx metalsmith-plugin-mcp-server update-deps ./my-plugin

# Update all plugins in a directory
npx metalsmith-plugin-mcp-server update-deps ./plugins

# Interactive mode - asks whether to update all or specific plugin
npx metalsmith-plugin-mcp-server update-deps

Guided vs. Expert Mode

Guided Mode (recommended for beginners):

npx metalsmith-plugin-mcp-server scaffold
# Will prompt you for:
# - Plugin name: my-awesome-plugin
# - Plugin description: Processes markdown files with custom rules
# - Output path (./): ./plugins

Expert Mode (for quick execution):

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

Enhanced Validation Features

The validate command supports functional validation that runs your tests and coverage, plus CLAUDE.md integration:

Standard Validation (structure-based, respects CLAUDE.md standards):

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

Functional Validation (runs tests and coverage):

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

CLAUDE.md Integration: If your plugin has a CLAUDE.md file with established patterns (like npm script releases), the validator automatically detects and validates against those patterns instead of suggesting conflicting approaches.

Understanding Validation Output:

• Passed: Requirements that are met
• Failed: Critical issues that must be fixed
• Warnings: Quality concerns (e.g., low test coverage)
• Recommendations: Optional improvements with actionable commands

Example Recommendations:

Consider adding a LICENSE file. Generate one with: npx metalsmith-plugin-mcp-server scaffold ./my-plugin LICENSE MIT
Consider adding a Biome configuration for lint + format. Generate with: npx metalsmith-plugin-mcp-server configs . --configs biome
Consider adding script: lint. Example: "lint": "biome check --write ."
Use metalsmith.debug() instead of debug package. Replace debug() calls with metalsmith.debug()
Use metalsmith.match() instead of minimatch package for file pattern matching
Remove debug dependency from package.json since you're using metalsmith.debug()

Native Methods Validation

The validator automatically detects usage of external packages that can be replaced with Metalsmith's native methods:

• debug → metalsmith.debug(): For consistent debugging across plugins
• minimatch → metalsmith.match(): For file pattern matching
• process.env → metalsmith.env(): For environment variables
• path.join → metalsmith.path(): For cross-platform path handling

This reduces dependencies and ensures consistency with Metalsmith's built-in functionality.

Dependency Update Features

The update-deps command now supports automatic installation and testing:

# Show what can be updated (dry run)
npx metalsmith-plugin-mcp-server update-deps ./my-plugin

# Update and install dependencies
npx metalsmith-plugin-mcp-server update-deps ./my-plugin --install

# Update, install, and run tests
npx metalsmith-plugin-mcp-server update-deps ./my-plugin --install --test

# Process multiple plugins in a directory
npx metalsmith-plugin-mcp-server update-deps ./plugins --install --test

Plugin Audit Features

The audit commands provide comprehensive plugin health assessment:

Single Plugin Audit:

# Basic audit (validation, linting, formatting, tests, coverage)
npx metalsmith-plugin-mcp-server audit ./my-plugin

# Audit with automatic fixes
npx metalsmith-plugin-mcp-server audit ./my-plugin --fix

# JSON output for CI/CD integration
npx metalsmith-plugin-mcp-server audit ./my-plugin --output=json

# Markdown report for documentation
npx metalsmith-plugin-mcp-server audit ./my-plugin --output=markdown

Batch Plugin Audit:

# Audit all plugins in a directory
npx metalsmith-plugin-mcp-server batch-audit ./plugins

# Batch audit with fixes applied to all plugins
npx metalsmith-plugin-mcp-server batch-audit ./plugins --fix

# Get JSON summary of all plugin health statuses
npx metalsmith-plugin-mcp-server batch-audit ./plugins --output=json

Audit Health Scores:

• EXCELLENT (90%+): Plugin meets all quality standards
• GOOD (80-89%): Minor improvements recommended
• FAIR (70-79%): Some issues need attention
• NEEDS IMPROVEMENT (60-69%): Multiple issues to address
• POOR (<60%): Significant problems requiring fixes

What Gets Audited:

• Validation: Plugin structure and configuration (40% weight)
• Tests: Test execution and pass/fail status (30% weight)
• Coverage: Code coverage percentage (20% weight)
• Linting: Biome compliance (5% weight)
• Formatting: Biome formatter compliance (5% weight)

Pre-Release Integration: New plugins scaffolded with this tool include a pre-release script that runs a full audit before releasing:

# Run before any release to ensure quality
npm run pre-release

This script runs: npm run lint && npm run format:check && npm test && npx metalsmith-plugin-mcp-server validate .

Configuration Management

You can check your current setup at any time:

# Show current configuration, file locations, and explanations
npx metalsmith-plugin-mcp-server config

This command displays:

• Configuration Sources: Which config files were found and loaded
• Current Configuration: Your effective settings (merged from all sources)
• Feature Explanations: What each configured feature does
• Impact Analysis: How your settings affect plugin creation
• Example Configuration: Template for creating your own config file
• Valid Options: All supported features and licenses

Validation Configuration

You can customize validation rules by creating a .metalsmith-plugin-validation.json file in your plugin directory:

{
  "rules": {
    "structure": {
      "enabled": true,
      "requiredDirs": ["src", "test"],
      "requiredFiles": ["src/index.js", "README.md"],
      "recommendedDirs": ["src/utils", "test/fixtures"]
    },
    "tests": {
      "enabled": true,
      "coverageThreshold": 85,
      "requireFixtures": false
    },
    "documentation": {
      "enabled": true,
      "requiredSections": ["Installation", "Usage"],
      "recommendedSections": ["Options", "Examples", "API"]
    },
    "packageJson": {
      "namePrefix": "metalsmith-",
      "requiredScripts": ["test", "build"],
      "recommendedScripts": ["lint", "format", "test:coverage"]
    }
  },
  "recommendations": {
    "showCommands": true,
    "templateSuggestions": true
  }
}

The validator will look for configuration files in this order:

1. .metalsmith-plugin-validation.json
2. .validation.json
3. .validationrc.json

Setting Up the MCP Server

1. Create a Local MCP Server Installation:

# Create a dedicated folder for the MCP server
mkdir ~/metalsmith-mcp-tools
cd ~/metalsmith-mcp-tools

# Initialize npm project and install the MCP server
npm init -y
npm install metalsmith-plugin-mcp-server

2. Configure Your AI Assistant:

For Claude Desktop

Add to your configuration file at ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "metalsmith-plugin-mcp-server": {
      "command": "node",
      "args": ["/Users/yourusername/metalsmith-mcp-tools/node_modules/metalsmith-plugin-mcp-server/src/index.js"],
      "cwd": "/Users/yourusername/metalsmith-mcp-tools"
    }
  }
}

For Claude Code

You can use the MCP server in two ways:

Option 1: Local Installation (as described above)

After installing the MCP server locally, configure it using Claude Code's MCP management commands:

# Add the MCP server to Claude Code
claude mcp add metalsmith-plugin /Users/yourusername/metalsmith-mcp-tools/node_modules/metalsmith-plugin-mcp-server/src/index.js

Option 2: Using npx (no installation required)

You can run the MCP server directly with npx:

# Add the MCP server using npx
claude mcp add metalsmith-plugin npx "metalsmith-plugin-mcp-server@latest" "server"

Verify it was added correctly!

claude mcp list

Important Notes:

• For local installation: Use the full absolute path to the src/index.js file (not just the directory)
• For npx: The command must be exactly as shown with "server" at the end
• Path is case-sensitive - use /Users (uppercase U) on macOS for local paths
• Replace yourusername with your actual username for local installation
• If using NVM, the path might be different - use which node to find your Node.js path

Restart Required! Exit and restart Claude Code for the MCP server to become available.

Verify Setup: In a new Claude Code session, the following tools should be available:

• plugin-scaffold - Generate plugin structures
• validate - Check plugin quality
• configs - Create configuration files
• update-deps - Update plugin dependencies
• list-templates - Show all available templates
• get-template - Retrieve specific template content
• install-claude-md - Install CLAUDE.md file with merge capabilities

Optimal AI Workflow for Existing Plugins

For existing plugins that don't have CLAUDE.md yet, use this workflow:

1. Add the MCP server (if not already done):

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

2. Install CLAUDE.md with complete AI instructions:

   # Merge with existing CLAUDE.md (preserves your content)
   npx metalsmith-plugin-mcp-server install-claude-md
   
   # Preview changes before applying
   npx metalsmith-plugin-mcp-server install-claude-md --dry-run
   
   # Force full replacement (overwrites existing content)
   npx metalsmith-plugin-mcp-server install-claude-md --replace
   

3. Ask Claude to review CLAUDE.md for context:

   Please review the CLAUDE.md file for context on how to work with this plugin
   

4. Claude now has all the instructions to:

   • Use MCP server templates correctly
   • Follow validation recommendations
   • Avoid creating custom implementations
   • Use proper commands like get-template and list-templates

This ensures Claude instances work consistently and follow the MCP server patterns rather than improvising their own solutions.

Merge Feature: The install-claude-md command merges MCP guidance with existing project-specific content:

• Preserves existing content: Your custom development notes, architecture decisions, and team instructions stay intact
• Adds MCP section: Inserts comprehensive AI assistant instructions without overwriting your content
• Updates existing MCP sections: If MCP guidance already exists, it updates it with the latest instructions
• Safe preview: Use --dry-run to see exactly what changes will be made before applying them

Restart Your AI Assistant**:

• Claude Desktop: Restart the application
• Claude Code: Restart or reload your development environment

Using the MCP Server for Plugin Development

Now you can create Metalsmith plugins in any directory and use AI assistance:

# Create a new plugin project anywhere
mkdir ~/my-projects/metalsmith-awesome-plugin
cd ~/my-projects/metalsmith-awesome-plugin

# Start Claude Code or use Claude Desktop
# The MCP server is now available globally

Verify Installation by asking your AI assistant:

"Do you have access to the Metalsmith Plugin MCP Server?"

Example Development Workflow:

"Create a new Metalsmith plugin called 'metalsmith-image-optimizer' that compresses images and generates responsive variants."

Example Prompts

Here are prompts that will trigger the MCP server's capabilities:

Creating a New Plugin:

"Create a new Metalsmith plugin called metalsmith-json-feed that generates JSON feeds from markdown files. Include async processing and comprehensive tests."

Plugin Validation and Recommendations:

"Does the MCP server have any recommendations for this plugin?"

"Run the MCP validation on this plugin and implement any recommendations."

"Check my metalsmith-sass plugin against the MCP server's enhanced quality standards and suggest improvements."

Upgrading Configuration:

"Update my Metalsmith plugin to use Biome for lint+format and the native node:test runner."

Complex Plugin Development:

"Help me build a Metalsmith plugin that optimizes SVG files, supports batch processing, and integrates with the plugin chain properly."

Configuration Management:

"Show me my current MCP server configuration and explain how it affects plugin creation."

The AI assistant will use the MCP server tools to scaffold, validate, and configure your Metalsmith plugins according to documented patterns.

Important: Following MCP Server Recommendations

When the MCP server provides recommendations or code snippets:

• Use them exactly as provided - The recommendations are designed to follow established patterns and best practices
• Don't simplify or reinterpret - The server's output includes specific configurations tested to work correctly
• Copy code snippets precisely - Configuration files, scripts, and patterns should be implemented exactly as shown
• Follow referenced documentation - If a recommendation mentions specific patterns in this documentation, use those patterns exactly

This ensures consistent, high-quality plugin development and prevents common configuration issues.

Options

Plugin Scaffolding Options

Option	Type	Default	Description
name	string	Required	Plugin name (exact name as provided - no auto-prefix)
description	string	Required	What the plugin does (must be provided)
features	string[]	['async-processing']	Optional features (exact strings required): async-processing, background-processing, metadata-generation
outputPath	string	'.'	Where to create the plugin directory
author	string	From config/git	Plugin author
license	string	'MIT'	License type: 'MIT', 'Apache-2.0', 'BSD-3-Clause', 'ISC'

Plugin Validation Options

Option	Type	Default	Description
path	string	Required	Path to the plugin to validate
checks	string[]	All checks	Specific checks to run: 'structure', 'tests', 'docs', 'package-json', 'biome', 'coverage'

Configuration Generation Options

Option	Type	Default	Description
outputPath	string	Required	Where to generate config files
configs	string[]	All configs	Config files to generate: 'biome', 'editorconfig', 'gitignore', 'release-it'

Plugin Types

Processor

Plugins that process file contents (e.g., markdown rendering, image optimization)

Transformer

Plugins that transform file metadata or structure (e.g., permalinks, collections)

Validator

Plugins that validate files against rules (e.g., HTML validation, link checking)

Plugin Features

Features control what additional functionality gets generated in your plugin. Exact strings are required - the system validates against these specific values.

Available Features

Feature	String (exact)	Description
Async Processing	async-processing	Adds batch processing and async capabilities
Background Processing	background-processing	Adds worker thread support for concurrent processing
Metadata Generation	metadata-generation	Adds metadata extraction and generation features

Usage Examples

Basic plugin (no features):

await mcp.call('plugin-scaffold', {
  name: 'my-simple-plugin',
  description: 'Processes files with basic functionality',
  features: []
});

Plugin with async processing:

await mcp.call('plugin-scaffold', {
  name: 'my-async-plugin',
  description: 'Processes files with batch support',
  features: ['async-processing']
});

Plugin with multiple features:

await mcp.call('plugin-scaffold', {
  name: 'my-advanced-plugin',
  description: 'Full-featured processing plugin',
  features: ['async-processing', 'background-processing', 'metadata-generation']
});

What Each Feature Adds

async-processing

• Batch Processing: Process files in configurable batches
• Async/Await Support: Native promise-based processing
• Error Handling: Comprehensive error handling for async operations
• Progress Tracking: Built-in progress reporting

Generated code includes:

// Batch processing utilities
async function processBatch(files, options) {
  const batchSize = options.batchSize || 10;
  // ... batch processing logic
}

background-processing

• Worker Threads: Offload CPU-intensive tasks to worker threads
• Concurrent Processing: Process multiple files simultaneously
• Resource Management: Automatic worker pool management
• Thread Communication: Structured message passing between threads

Generated code includes:

// Worker thread setup
import { Worker, isMainThread, parentPort } from 'worker_threads';
// ... worker thread implementation

metadata-generation

• Metadata Extraction: Extract metadata from processed files
• Automatic Enrichment: Add computed metadata to file objects
• Flexible Schema: Configurable metadata schemas
• Caching Support: Built-in metadata caching

Generated code includes:

// Metadata generation utilities
function generateMetadata(file, options) {
  return {
    processedAt: new Date().toISOString()
    // ... metadata generation logic
  };
}

Feature Validation

If you provide invalid feature strings, you'll get a helpful error message:

Invalid features: async, background

Valid features are:
- async-processing: Adds batch processing and async capabilities
- background-processing: Adds worker thread support for concurrent processing
- metadata-generation: Adds metadata extraction and generation features

Example: ["async-processing", "metadata-generation"]

Configuration

Environment Variables

Currently, no environment variables are used for configuration. All configuration is handled through the configuration file or command-line arguments.

Configuration File

You can create a .metalsmith-plugin-mcp file to set default values for plugin creation. The CLI will look for this file in:

1. Current working directory
2. Your home directory

Example .metalsmith-plugin-mcp:

{
  "license": "MIT",
  "author": "Your Name <your.email@example.com>",
  "outputPath": "./plugins",
  "features": ["async-processing"]
}

Available configuration options:

Option	Type	Default	Description
license	string	'MIT'	Default license
author	string	''	Default author name and email
outputPath	string	'.'	Default output directory for new plugins
features	string[]	['async-processing']	Default features to include

Debug

The MCP server currently uses standard console output for logging. For troubleshooting:

1. CLI Usage: All output is shown directly in the terminal
2. MCP Server: Check your AI assistant's connection logs
3. Verbose Output: The server provides detailed success/error messages for all operations

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/feature-name)
3. Commit your changes (git commit -m 'Add feature description')
4. Push to the branch (git push origin feature/feature-name)
5. Open a Pull Request

Release Process

The release process is fully automated using GitHub CLI. Simply run:

npm run release

The release automatically:

• Syncs with remote (to handle CI commits like coverage badge updates)
• Runs tests and linting
• Generates changelog from commit history
• Creates GitHub release using GitHub CLI (no tokens needed)
• Pushes everything including tags

Prerequisites

Make sure GitHub CLI is installed and authenticated:

# Install GitHub CLI (if not already installed)
brew install gh

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

The release process will automatically check for GitHub CLI availability and fail gracefully if not found.

Development Workflow

Generated plugins ship ESM-only — no build step, no lib/, tests run directly against src/:

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint + format (Biome)
npm run lint

# Format only
npm run format

Important: Remove any empty directories (like src/utils) that aren't needed for your specific plugin after development is complete.

Testing

The MCP server itself uses comprehensive testing:

# Run all MCP server tests
npm test

# Run tests with coverage
npm run coverage

# Run linting
npm run lint

# Format code
npm run format

Resources

• Metalsmith Documentation
• MCP Protocol Specification

License

MIT © Werner Glinka

---