metalsmith-plugin-mcp-server

wernerglinka/metalsmith-plugin-mcp-server

3.2

If you are the rightful owner of metalsmith-plugin-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Metalsmith MCP Server is a tool for scaffolding and validating high-quality Metalsmith plugins, encapsulating best practices from the Metalsmith ecosystem.

Tools
3
Resources
0
Prompts
0

Metalsmith Plugin MCP Server

MCP server for scaffolding and validating high-quality Metalsmith plugins

Known Vulnerabilities

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 v1.6.0

IDE Compatibility Fix - Release scripts handle environment-set GITHUB_TOKEN variables:

  • Clears IDE-set GITHUB_TOKEN environment variables before authentication
  • Supports VSCode, Claude Code, and other IDEs that automatically set GITHUB_TOKEN
  • Uses GitHub CLI keyring authentication regardless of environment variables
  • Prevents authentication failures when IDEs inject tokens with insufficient permissions

The release script now includes unset GITHUB_TOKEN before calling gh auth token to ensure consistent authentication across development environments.

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:

  • Dual Module Support: Both ESM and CommonJS builds using microbundle
  • 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 with both ESM and CJS testing
  • Production-ready documentation
  • ESLint 9.x flat config
  • Prettier formatting
  • 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 Scripts (scripts/):

  • release.sh: Manual release control with secure GitHub CLI authentication
  • release-notes.sh: Custom release notes generation filtering maintenance commits

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

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
  • ESLint: Modern configuration presence
  • Coverage: Test coverage analysis

🆕 Enhanced Quality Standards (addressing Metalsmith maintainer feedback):

  • Marketing Language Detection: Flags buzzwords like "intelligent", "smart", "seamless" in documentation
  • Module System Consistency: Detects dangerous CJS/ESM mixing in README examples that cause runtime errors
  • 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: ['eslint', 'prettier', '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 ESLint configuration. Generate with: npx metalsmith-plugin-mcp-server scaffold ./my-plugin eslint.config.js eslint
💡 Consider adding script: lint. Example: "lint": "eslint src test"
💡 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:

  • debugmetalsmith.debug(): For consistent debugging across plugins
  • minimatchmetalsmith.match(): For file pattern matching
  • process.envmetalsmith.env(): For environment variables
  • path.joinmetalsmith.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: ESLint compliance (5% weight)
  • Formatting: Prettier 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 ESLint 9 flat config and modern testing patterns."

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

OptionTypeDefaultDescription
namestringRequiredPlugin name (exact name as provided - no auto-prefix)
descriptionstringRequiredWhat the plugin does (must be provided)
featuresstring[]['async-processing']Optional features (exact strings required): async-processing, background-processing, metadata-generation
outputPathstring'.'Where to create the plugin directory
authorstringFrom config/gitPlugin author
licensestring'MIT'License type: 'MIT', 'Apache-2.0', 'BSD-3-Clause', 'ISC'

Plugin Validation Options

OptionTypeDefaultDescription
pathstringRequiredPath to the plugin to validate
checksstring[]All checksSpecific checks to run: 'structure', 'tests', 'docs', 'package-json', 'eslint', 'coverage'

Configuration Generation Options

OptionTypeDefaultDescription
outputPathstringRequiredWhere to generate config files
configsstring[]All configsConfig files to generate: 'eslint', 'prettier', '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

FeatureString (exact)Description
Async Processingasync-processingAdds batch processing and async capabilities
Background Processingbackground-processingAdds worker thread support for concurrent processing
Metadata Generationmetadata-generationAdds 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:

OptionTypeDefaultDescription
licensestring'MIT'Default license
authorstring''Default author name and email
outputPathstring'.'Default output directory for new plugins
featuresstring[]['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 follow a modern dual-module development workflow:

# Install dependencies
npm install

# Build both ESM and CJS versions
npm run build

# Run tests for both module formats
npm test

# Run only ESM tests
npm run test:esm

# Run only CJS tests
npm run test:cjs

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

# Format code
npm run format

Important:

  • Always run npm run build before testing or publishing, as the tests run against the built files in the lib/ directory.
  • 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 test:coverage

# Run linting
npm run lint

# Format code
npm run format

Resources

License

MIT © Werner Glinka