wernerglinka/metalsmith-plugin-mcp-server
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.
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 v1.6.0
IDE Compatibility Fix - Release scripts handle environment-set GITHUB_TOKEN variables:
- Clears IDE-set
GITHUB_TOKENenvironment 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:
- Direct CLI Usage: Run commands directly in your terminal using npx for one-off plugin creation or manual control
- 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:
- 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: 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:
.metalsmith-plugin-validation.json.validation.json.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:
-
Add the MCP server (if not already done):
claude mcp add metalsmith-plugin npx "metalsmith-plugin-mcp-server@latest" "server" -
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 -
Ask Claude to review CLAUDE.md for context:
Please review the CLAUDE.md file for context on how to work with this plugin -
Claude now has all the instructions to:
- Use MCP server templates correctly
- Follow validation recommendations
- Avoid creating custom implementations
- Use proper commands like
get-templateandlist-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-runto 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
| 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', 'eslint', 'coverage' |
Configuration Generation Options
| Option | Type | Default | Description |
|---|---|---|---|
outputPath | string | Required | Where to generate config files |
configs | string[] | All configs | Config 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
| 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:
- Current working directory
- 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:
- CLI Usage: All output is shown directly in the terminal
- MCP Server: Check your AI assistant's connection logs
- Verbose Output: The server provides detailed success/error messages for all operations
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/feature-name) - Commit your changes (
git commit -m 'Add feature description') - Push to the branch (
git push origin feature/feature-name) - 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 buildbefore testing or publishing, as the tests run against the built files in thelib/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