Content
# @haakco/mcp-config-validator
**Comprehensive validation and health checker for MCP (Model Context Protocol) servers**
Ensures your MCP servers follow best practices, security standards, and optimal configuration patterns with automated fixes, performance benchmarking, and 50+ validation rules across 7 categories.
[](https://www.npmjs.com/package/@haakco/mcp-config-validator)
[](https://github.com/haakco/mcp-config-validator/actions)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
## Features
- **🔍 Multi-Category Validation**: Structure, dependencies, configuration, security, performance, best practices, and MCP-specific rules
- **🛠️ Automated Fixes**: Apply safe fixes automatically with `--fix` flag
- **📊 Performance Benchmarking**: Measure build time, startup time, bundle size, and memory usage
- **🎯 Severity Filtering**: Focus on errors, warnings, or info-level issues
- **📝 Multiple Output Formats**: Text, JSON, YAML, or HTML reports
- **🚀 CI/CD Integration**: Exit codes and formats optimized for continuous integration
- **🔧 Customizable Rules**: Configure validation rules via config files
## Installation
```bash
npm install -g @haakco/mcp-config-validator
```
Or use locally in a project:
```bash
npm install --save-dev @haakco/mcp-config-validator
```
## Usage
### Basic Validation
```bash
# Validate current directory
mcp-validate validate
# Validate specific project
mcp-validate validate /path/to/mcp-server
# Only show errors
mcp-validate validate --severity error
# Auto-fix issues
mcp-validate validate --fix
```
### Quick Health Check
```bash
# Quick check with summary only
mcp-validate check
# CI mode (exits with error code if issues found)
mcp-validate check --ci
```
### Performance Benchmarking
```bash
# Run performance benchmarks
mcp-validate benchmark
# Run with more iterations for accuracy
mcp-validate benchmark --iterations 5
```
### Interactive Mode
```bash
# Interactive validation wizard
mcp-validate interactive
```
## Validation Categories
### 1. **Structure** (`structure`)
- Package.json existence and validity
- README.md documentation
- TypeScript configuration
- Test directory structure
- Docker support files
### 2. **Dependencies** (`dependencies`)
- MCP SDK version requirements
- Security vulnerabilities
- Outdated packages
- Missing peer dependencies
- Dev vs production dependencies
### 3. **Configuration** (`configuration`)
- TypeScript optimization settings
- ESLint and Prettier setup
- Test framework configuration
- Build scripts
- Environment variable handling
### 4. **Security** (`security`)
- Hardcoded secrets detection
- Git ignore patterns
- Environment variable security
- Input validation patterns
- Error handling security
### 5. **Performance** (`performance`)
- Bundle size optimization
- Async/await patterns
- Memory leak prevention
- Caching implementation
- Resource limits
### 6. **Best Practices** (`best-practices`)
- Code organization
- Naming conventions
- Error handling patterns
- Logging practices
- Testing coverage
### 7. **MCP-Specific** (`mcp-specific`)
- Server structure requirements
- Tool implementation patterns
- Error response formatting
- SDK usage patterns
- Claude Desktop configuration
## Configuration
Create `mcp-validator.config.json` in your project:
```json
{
"$schema": "https://raw.githubusercontent.com/haakco/mcp-tools/main/config-validator/schema.json",
"severity": "warning",
"categories": [
"structure",
"dependencies",
"configuration",
"security",
"performance",
"best-practices",
"mcp-specific"
],
"format": "text",
"fix": false,
"rules": {
"structure-tests": "error",
"security-env-secrets": "error",
"mcp-server-structure": "error",
"performance-bundle-size": "warning",
"best-practice-documentation": "info"
},
"ignore": [
"node_modules/**",
"dist/**",
"coverage/**"
]
}
```
## Command Line Options
### `validate` Command
| Option | Description | Default |
|--------|-------------|---------|
| `--severity, -s` | Minimum severity level (error, warning, info) | `info` |
| `--categories, -c` | Categories to validate | All categories |
| `--format, -f` | Output format (text, json, yaml, html) | `text` |
| `--output, -o` | Output file path | Console output |
| `--fix` | Automatically fix issues | `false` |
| `--config` | Path to config file | Auto-detected |
### `check` Command
| Option | Description | Default |
|--------|-------------|---------|
| `--ci` | CI mode (exit with error if issues) | `false` |
| `--format, -f` | Output format | `text` |
### `benchmark` Command
| Option | Description | Default |
|--------|-------------|---------|
| `--iterations, -i` | Number of benchmark iterations | `3` |
| `--output, -o` | Output file for results | `benchmark-report.json` |
## Exit Codes
- `0`: Success, no issues found (or only info-level issues in CI mode)
- `1`: Validation errors found
- `2`: Tool execution error
## Examples
### CI/CD Integration
```yaml
# GitHub Actions
- name: Validate MCP Server
run: |
npm install -g @haakco/mcp-config-validator
mcp-validate check --ci
```
```yaml
# GitLab CI
validate:
script:
- npm install -g @haakco/mcp-config-validator
- mcp-validate validate --severity error --format json --output validation-report.json
artifacts:
reports:
junit: validation-report.json
```
### Pre-commit Hook
```json
{
"husky": {
"hooks": {
"pre-commit": "mcp-validate check --ci"
}
}
}
```
### Custom Rule Severity
```bash
# Only fail on errors, ignore warnings
mcp-validate validate --severity error --ci
# Show all issues including info
mcp-validate validate --severity info
```
### Generate Reports
```bash
# HTML report for documentation
mcp-validate validate --format html --output report.html
# JSON for further processing
mcp-validate validate --format json | jq '.results[] | select(.severity == "error")'
```
## Programmatic Usage
```typescript
import { ConfigValidator } from '@haakco/mcp-config-validator';
const validator = new ConfigValidator('/path/to/project', {
severity: 'warning',
categories: ['security', 'mcp-specific'],
format: 'json',
});
const report = await validator.validate();
console.log(`Health Score: ${report.summary.score}/100`);
```
## 🚀 Development
```bash
# Install dependencies
npm install
# Run tests in watch mode
npm run test:watch
# Build the library
npm run build
# Test CLI locally
npm run dev -- validate . --format json
# Lint and format code
npm run lint
npm run lint:fix
# Type checking
npm run typecheck
```
## 🤝 Contributing
We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for:
- Development setup instructions
- Code quality standards
- Adding new validation rules
- Testing guidelines
- Pull request process
## 📄 License
MIT License - see [LICENSE](./LICENSE) file for details.
## 🔗 Related Projects
- [@haakco/mcp-utils](https://github.com/haakco/mcp-utils) - Shared utilities for MCP servers
- [@haakco/mcp-pattern-generator](https://github.com/haakco/mcp-pattern-generator) - Pattern generation for MCP projects
- [@haakco/mcp-migration-tool](https://github.com/haakco/mcp-migration-tool) - Migration assistance for MCP servers
---
**Built with TypeScript, tested with Vitest, and designed for production MCP server validation.**
