Content
# MCP Compliance Validator
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
[](https://www.jsonrpc.org/specification)
[](#security-features)
A comprehensive **security validation system** for Model Context Protocol (MCP) server implementations. Provides enterprise-grade authentication, authorization, and protocol security checks to ensure your MCP servers meet the highest security standards.
## Quick Start
```bash
# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
pip install mcp
pip install -e .
# Run as MCP server
python -m src.mcp_compliance_validator.simple_server
# Or validate a repository directly
python -c "
import asyncio
from src.mcp_compliance_validator.tools.validate_compliance import validate_compliance
async def validate():
result = await validate_compliance('/path/to/your/mcp-server')
print(f'Security Score: {result[\"analysis_summary\"][\"security_score\"]:.2f}')
asyncio.run(validate())
"
```
## Security Features
### **Advanced Authentication & Authorization**
- **OAuth 2.1 Compliance**: PKCE, state parameters, redirect URI validation, client authentication
- **JWT Security**: Algorithm validation, expiration checks, issuer/audience verification, replay protection
- **API Key Security**: Length validation, rotation policies, rate limiting, immediate revocation
- **Transport Security**: HTTPS enforcement, protocol version validation, origin validation
### **Deep Code Analysis**
- **AST-based Security Analysis**: Static analysis for security vulnerabilities and anti-patterns
- **100+ Security Rules**: Comprehensive coverage of authentication, authorization, and protocol security
- **Pattern Detection**: Identifies insecure implementations and compliance violations
- **Real-time Validation**: On-demand security assessments with detailed remediation guidance
### **Enterprise Integration**
- **MCP Protocol Compliant**: Full JSON-RPC 2.0 implementation with comprehensive validation tools
- **CI/CD Integration**: Automated security validation in development pipelines
- **Comprehensive Reporting**: Detailed findings with severity classification and remediation steps
- **High Performance**: 590K+ chars/sec processing, 58K+ validations/sec
### **MCP Documentation Monitoring**
- **Real-time Documentation Tracking**: Monitors official MCP repositories for specification changes
- **Compliance Impact Analysis**: Assesses how documentation changes affect compliance validation
- **Cross-Reference Analysis**: Correlates documentation changes with existing tool implementations
- **Automated Recommendations**: Provides actionable insights for maintaining compliance
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [MCP Server Mode](#mcp-server-mode)
- [Direct API Usage](#direct-api-usage)
- [CI/CD Integration](#cicd-integration)
- [Security Rules](#security-rules)
- [Configuration](#configuration)
- [Documentation Monitoring](#documentation-monitoring)
- [Documentation](#documentation)
- [Performance](#performance)
- [Examples](#examples)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
## Installation
### Quick Start (npm)
The easiest way to use the MCP Compliance Validator:
```bash
# Run directly with npx (no installation required)
npx mcp-compliance-validator
# Or install globally
npm install -g mcp-compliance-validator
```
### Development Installation
For development or custom setups:
#### Prerequisites
- **Python 3.11 or higher**
- **Git** (for repository analysis)
- **GitHub Token** (for MCP documentation monitoring - optional but recommended)
### Install Dependencies
**Note**: Due to Python environment restrictions, a virtual environment is required.
```bash
# Create virtual environment
python3 -m venv venv
# Activate virtual environment
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install MCP library
pip install mcp
# Install package in development mode
pip install -e .
# Development installation (includes testing and linting tools)
pip install -r requirements-dev.txt
# Set up development environment (if available)
make setup
```
### Verify Installation
```bash
# Run tests
make test
# Check code quality
make lint
# Test MCP server
./venv/bin/python -m src.mcp_compliance_validator.simple_server
```
### Build/Test Commands
```bash
# Run all tests
python3 -m pytest
# Run specific test
python3 -m pytest tests/contract/test_analyze_tools_contract.py::TestAnalyzeMCPToolsContract::test_tool_exists
# Run MCP server directly
python3 src/mcp_compliance_validator/simple_server.py
```
## MCP Server Configuration
### Installation
First, install the package and its dependencies in development mode:
```bash
cd /path/to/mcp-compliance-validator
pip install -r requirements.txt
pip install -e .
```
### Claude Desktop Configuration
#### Option 1: npm Package (Recommended)
```json
{
"mcpServers": {
"mcp-compliance-validator": {
"command": "npx",
"args": ["-y", "mcp-compliance-validator"],
"description": "Security validation system for MCP server implementations with enterprise-grade authentication and authorization checks",
"alwaysAllow": [
"validate_compliance",
"analyze_mcp_tools",
"get_mcp_spec_version"
]
}
}
}
```
#### Option 2: Local Development Installation
**Note**: Replace `/path/to/mcp-compliance-validator` with the actual path to your installation.
```json
{
"mcpServers": {
"mcp-compliance-validator": {
"command": "/path/to/mcp-compliance-validator/venv/bin/python",
"args": [
"-m",
"src.mcp_compliance_validator.simple_server"
],
"cwd": "/path/to/mcp-compliance-validator",
"description": "Security validation system for MCP server implementations with enterprise-grade authentication and authorization checks",
"alwaysAllow": [
"validate_compliance",
"analyze_mcp_tools",
"get_mcp_spec_version"
]
}
}
}
```
### Claude Code Configuration
#### Option 1: npm Package (Recommended)
```bash
claude mcp add-json "mcp-compliance-validator" '{
"command": "npx",
"args": ["-y", "mcp-compliance-validator"]
}'
```
#### Option 2: Import from Claude Desktop
```bash
claude mcp add-from-claude-desktop
```
#### Option 3: Manual Configuration
Add to your project's `.claude.json` file:
```json
{
"mcpServers": {
"mcp-compliance-validator": {
"command": "npx",
"args": ["-y", "mcp-compliance-validator"]
}
}
}
```
### Configuration Files Location
- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Claude Desktop (Linux)**: `~/.config/Claude/claude_desktop_config.json`
- **Claude Code**: `~/.claude.json` (global) or `.claude.json` (project-specific)
### Verifying Server Connection
After adding the configuration, restart Claude Desktop and verify the server is connected:
1. The server should appear in Claude's MCP servers list
2. You can test it by asking Claude to validate an MCP server repository
3. Check the logs for any connection errors
### Alternative Configuration (Development)
For development or local testing, you can run the server directly:
```json
{
"mcpServers": {
"mcp-compliance-validator": {
"command": "python",
"args": [
"/full/path/to/mcp-compliance-validator/src/mcp_compliance_validator/simple_server.py"
]
}
}
}
```
## Usage
### MCP Server Mode
Run as an MCP server for integration with MCP clients:
```bash
python -m mcp_compliance_validator.simple_server
```
The server exposes **six powerful validation tools**:
#### 1. `validate_compliance` - Comprehensive Security Analysis
```json
{
"name": "validate_compliance",
"arguments": {
"repository_path": "/path/to/your/mcp-server",
"validation_categories": ["SECURITY", "TOOLS", "PROTOCOL"],
"include_patterns": ["**/*.py"],
"exclude_patterns": ["**/test_*", "**/__pycache__/**"]
}
}
```
**Sample Response:**
```json
{
"success": true,
"analysis_summary": {
"files_analyzed": 150,
"total_findings": 23,
"security_score": 0.85,
"compliance_status": "COMPLIANT_WITH_WARNINGS"
},
"findings": [
{
"rule_id": "OAUTH-001",
"severity": "high",
"message": "PKCE not required for OAuth flows",
"recommendation": "Require PKCE for all OAuth authorization flows",
"file_path": "/path/to/oauth.py",
"line_number": 42
}
]
}
```
#### 2. `analyze_mcp_tools` - MCP Tool Implementation Analysis
```json
{
"name": "analyze_mcp_tools",
"arguments": {
"repository_path": "/path/to/your/mcp-server",
"tool_patterns": ["@mcp.tool", "@tool", "def.*tool.*\\("]
}
}
```
#### 3. `get_mcp_spec_version` - Latest MCP Specification Info
```json
{
"name": "get_mcp_spec_version",
"arguments": {}
}
```
#### 4. `monitor_mcp_docs` - MCP Documentation Change Monitoring
Monitor official MCP documentation repositories for recent changes and analyze their compliance impact:
```json
{
"name": "monitor_mcp_docs",
"arguments": {
"days_back": 30,
"severity_filter": "medium",
"github_token": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
```
**Sample Response:**
```json
{
"success": true,
"monitoring_summary": {
"monitoring_period": {
"days_back": 30,
"start_date": "2025-08-27T13:04:14.986886+00:00",
"end_date": "2025-09-26T13:04:21.509954+00:00"
},
"repositories_checked": [
"modelcontextprotocol/specification",
"modelcontextprotocol/python-sdk",
"modelcontextprotocol/typescript-sdk"
],
"raw_commits_found": 21,
"changes_detected": 44,
"changes_after_filtering": 39
},
"compliance_report": {
"priority_summary": {
"critical": 0,
"high": 15,
"medium": 24,
"low": 0
},
"changes_requiring_validation_updates": 28
}
}
```
#### 5. `analyze_mcp_tools_comprehensive` - Comprehensive Analysis
Perform comprehensive MCP tools analysis including documentation monitoring:
```json
{
"name": "analyze_mcp_tools_comprehensive",
"arguments": {
"repository_path": ".",
"include_docs_analysis": true,
"docs_monitoring_days": 7,
"github_token": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
```
#### 6. `monitor_tools_compliance_drift` - Compliance Drift Monitoring
Monitor compliance drift by comparing current tools status with recent documentation changes:
```json
{
"name": "monitor_tools_compliance_drift",
"arguments": {
"repository_path": ".",
"baseline_days": 30,
"comparison_days": 7,
"github_token": "ghp_xxxxxxxxxxxxxxxxxxxx"
}
}
```
**Note**: The documentation monitoring tools require a GitHub personal access token to avoid API rate limits and access recent commit history.
### Direct API Usage
Use the security validators directly in your Python applications:
```python
from mcp_compliance_validator.validators.auth_security import AuthSecurityValidator
# Initialize validator
validator = AuthSecurityValidator()
# Validate OAuth 2.1 configuration
oauth_config = {
"oauth": {
"pkce_required": True,
"state_required": True,
"redirect_uri_validation": {"enabled": True},
"authorization_code": {"expiration_seconds": 600},
"client_authentication": {"required": True}
}
}
result = validator.validate_oauth_implementation(oauth_config)
print(f"OAuth Security: {'SECURE' if result.is_secure else 'INSECURE'}")
# Validate JWT configuration
jwt_config = {
"algorithm": "RS256",
"expiration_hours": 1,
"issuer_validation": {"enabled": True},
"audience_validation": {"enabled": True}
}
jwt_result = validator.validate_jwt_security(jwt_config)
print(f"JWT Security: {'SECURE' if jwt_result.is_secure else 'INSECURE'}")
```
### CI/CD Integration
Integrate security validation into your development pipeline:
```yaml
# .github/workflows/security-validation.yml
name: Security Validation
on: [push, pull_request]
jobs:
security-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: '3.11'
- name: Install MCP Validator
run: |
git clone https://github.com/your-org/mcp-compliance-validator.git
cd mcp-compliance-validator
pip install -r requirements.txt
- name: Run Security Validation
run: |
cd mcp-compliance-validator
python -c "
import asyncio, sys
from mcp_compliance_validator.tools.validate_compliance import validate_compliance
async def validate():
result = await validate_compliance('$GITHUB_WORKSPACE',
validation_categories=['SECURITY'])
score = result['analysis_summary']['security_score']
print(f'Security Score: {score:.2f}')
# Fail if critical issues found
critical_findings = [f for f in result['findings']
if f['severity'] == 'critical']
if critical_findings:
print(f'ERROR: {len(critical_findings)} critical security issues found')
sys.exit(1)
else:
print('No critical security issues')
asyncio.run(validate())
"
```
## Security Rules
### OAuth 2.1 Security Rules
| Rule ID | Severity | Description | Fix |
|---------|----------|-------------|-----|
| `OAUTH-001` | HIGH | PKCE not required | Enable `pkce_required: true` |
| `OAUTH-003` | HIGH | State parameter not required | Enable `state_required: true` |
| `OAUTH-004` | CRITICAL | Redirect URI validation disabled | Enable `redirect_uri_validation.enabled: true` |
| `OAUTH-005` | HIGH | No authorization code expiration | Set `authorization_code.expiration_seconds` |
| `OAUTH-006` | HIGH | Client authentication not required | Enable `client_authentication.required: true` |
### JWT Security Rules
| Rule ID | Severity | Description | Fix |
|---------|----------|-------------|-----|
| `JWT-001` | CRITICAL | Insecure algorithm (none, HS256) | Use RS256 or ES256 |
| `JWT-002` | HIGH | No token expiration | Set `expiration_hours` |
| `JWT-004` | HIGH | No issuer validation | Enable `issuer_validation.enabled: true` |
| `JWT-005` | HIGH | No audience validation | Enable `audience_validation.enabled: true` |
### API Key Security Rules
| Rule ID | Severity | Description | Fix |
|---------|----------|-------------|-----|
| `API-001` | HIGH | Key too short (< 32 chars) | Use `key_length >= 32` |
| `API-002` | MEDIUM | No rotation policy | Enable `rotation_enabled: true` |
| `API-006` | HIGH | No revocation capability | Enable `revocation.enabled: true` |
## Configuration
### Environment Variables
```bash
# GitHub integration (required for MCP documentation monitoring)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
# Security settings
export MCP_SECURITY_MIN_ENTROPY=8.0
export MCP_SECURITY_FALSE_POSITIVE_RATE=0.01
# Performance settings
export MCP_ANALYSIS_MAX_WORKERS=4
export MCP_ANALYSIS_TIMEOUT_SECONDS=300
# Logging
export MCP_LOG_LEVEL=INFO
export MCP_LOG_FORMAT=json
```
### Configuration File
Create `config.yaml` for advanced settings:
```yaml
github:
token: "ghp_xxxxxxxxxxxxxxxxxxxx" # GitHub personal access token
security:
min_secret_entropy: 8.0
false_positive_rate: 0.01
allowed_path_prefixes:
- "/safe/path"
analysis:
max_workers: 4
timeout_seconds: 300
chunk_size: 100
logging:
level: INFO
format: json
file_path: "/var/log/mcp-validator.log"
```
## Documentation Monitoring
### MCP Documentation Monitoring Feature
This system provides automated tracking of changes in official MCP repositories and analyzes how these changes might affect MCP compliance validation.
#### Features
1. **Repository Monitoring**
- Monitors official MCP repositories: `specification`, `python-sdk`, `typescript-sdk`
- Tracks changes in documentation, specifications, and code examples
- Configurable monitoring periods and severity filters
2. **Change Detection**
- Categorizes changes by type: specification, protocol, schema, security, tools, resources
- Assesses severity levels: critical, high, medium, low
- Extracts relevant keywords and metadata
3. **Compliance Impact Analysis**
- Analyzes how documentation changes affect compliance validation
- Identifies validation rules that may need updates
- Suggests new compliance rules based on changes
- Provides actionable recommendations
#### Usage Examples
##### Basic Documentation Monitoring
```python
from mcp_compliance_validator.tools.monitor_mcp_docs import monitor_mcp_docs
# Monitor last 7 days with medium+ severity
result = await monitor_mcp_docs(
days_back=7,
severity_filter="medium"
)
if result["success"]:
print(f"Found {len(result['detailed_changes'])} relevant changes")
for change in result['detailed_changes']:
print(f"- {change['title']} ({change['severity']})")
```
##### Comprehensive Analysis with Cross-Reference
```python
from mcp_compliance_validator.tools.analyze_mcp_tools import analyze_mcp_tools_comprehensive
# Analyze tools with documentation monitoring
result = await analyze_mcp_tools_comprehensive(
repository_path="/path/to/your/mcp/project",
include_docs_analysis=True,
docs_monitoring_days=14
)
if result["success"]:
# View tool analysis
tools = result["tools_analysis"]
print(f"Tools found: {tools['tools_found']}")
print(f"Compliant: {tools['tools_compliant']}")
# View cross-reference insights
insights = result.get("cross_reference_insights", {})
for recommendation in insights.get("recommendations", []):
print(f"Recommendation: {recommendation}")
```
#### GitHub Token Configuration
For enhanced functionality and higher rate limits, configure a GitHub personal access token:
1. Go to GitHub Settings > Developer settings > Personal access tokens
2. Create a new token with `public_repo` scope
3. Set the environment variable:
```bash
export GITHUB_TOKEN=your_token_here
```
Without a token, the system uses unauthenticated requests with lower rate limits (60 requests/hour vs 5000 requests/hour).
## Documentation
### Avoiding False Positives
The validator analyzes source code for MCP specification compliance. To avoid analyzing external dependencies and get accurate results:
#### Recommended Exclude Patterns
```bash
# Using the MCP tool directly
mcp_validate_compliance \
--repository_path /path/to/your/repo \
--exclude_patterns "test_env/**/*" "**/__pycache__/**" "**/site-packages/**" \
--exclude_test_files true
```
#### Default Exclusions
The validator automatically excludes:
- `**/node_modules/**` - Node.js dependencies
- `**/.git/**` - Git repository files
- `**/venv/**`, `**/.venv/**`, `**/test_env/**` - Python virtual environments
- `**/__pycache__/**` - Python cache files
- `**/site-packages/**` - Installed Python packages
- `**/htmlcov/**` - Coverage reports
- `**/.pytest_cache/**` - Pytest cache
- `**/*.pyc`, `**/*.pyo`, `**/*.pyd` - Compiled Python files
#### Configuration File
Create a `.mcp-compliance-ignore` file in your repository root:
```gitignore
# External dependencies
test_env/**/*
**/site-packages/**
lib/python*/site-packages/**
# Cache and build files
**/__pycache__/**
*.pyc
*.pyo
*.pyd
# Virtual environments
venv/*
.venv/*
env/*
# IDE files
.vscode/*
.idea/*
```
### Best Practices
#### 1. Focus on Your Source Code
Only analyze the code you write, not external dependencies:
- Include: `src/**/*.py`, `lib/**/*.py`, your main code directories
- Exclude: Virtual environments, installed packages, cache files
#### 2. Use Appropriate Severity Thresholds
```bash
# For development - see all issues
--severity_threshold INFO
# For CI/CD - only critical issues
--severity_threshold ERROR
```
#### 3. Categories of Validation
Choose relevant validation categories:
- `PROTOCOL` - MCP protocol compliance
- `SCHEMA` - JSON schema validation
- `SECURITY` - Security pattern analysis
- `TOOLS` - MCP tool implementation
- `RESOURCES` - MCP resource handling
- `PACKAGING` - MCPB bundle packaging recommendations (optional)
Example:
```bash
--validation_categories "PROTOCOL,SCHEMA,TOOLS"
# Include packaging recommendations
--validation_categories "PROTOCOL,SCHEMA,TOOLS,PACKAGING"
```
### MCPB (MCP Bundle) Support
The validator provides **optional recommendations** for MCPB packaging to improve distribution and installation experience. MCPB validation:
- **Never fails validation** for missing MCPB support
- **Suggests MCPB packaging** for local MCP servers
- **Validates manifest.json** structure if present
- **Provides guidance** on distribution best practices
#### What is MCPB?
MCPB (MCP Bundle) is a standardized packaging format for local MCP servers:
- **Similar to browser extensions** (.crx) or VS Code extensions (.vsix)
- **Enables one-click installation** in desktop applications like Claude
- **Contains**: MCP server files + `manifest.json` metadata
- **Optional but recommended** for better user experience
#### MCPB Validation Rules
| Rule ID | Severity | Description |
|---------|----------|-------------|
| `PACKAGING-001` | INFO | Consider MCPB packaging for easier distribution |
| `PACKAGING-002` | WARNING | Invalid manifest.json structure detected |
| `PACKAGING-003` | INFO | Valid MCPB manifest.json detected |
| `PACKAGING-004` | INFO | MCP server appears to be for remote deployment |
#### When to Use MCPB
**Recommended for:**
- Local MCP servers for desktop integration
- Tools meant for end-user installation
- Servers requiring easy configuration
**Not needed for:**
- Remote/cloud MCP servers
- API services
- CI/CD or development tools
## Performance
### Benchmarks
- **Response Time**: < 2 seconds for typical repositories
- **Throughput**: 596,592 characters/second processing capability
- **Auth Validation Rate**: 58,917 validations/second
- **MCP Server Performance**: 2.38M requests/second
- **Memory Usage**: < 200MB for large codebases
### Optimization Features
- **Parallel Processing**: Multi-threaded analysis for large codebases
- **Memory Efficient**: Bounded memory usage with streaming analysis
- **Caching**: Intelligent caching of validation results
- **Incremental Analysis**: Only analyze changed files when possible
## Examples
### Complete Security Assessment
```python
import asyncio
from mcp_compliance_validator.tools.validate_compliance import validate_compliance
async def comprehensive_security_check():
"""Run a complete security assessment."""
result = await validate_compliance(
repository_path="/path/to/your/mcp-server",
validation_categories=["SECURITY", "TOOLS", "PROTOCOL"],
include_patterns=["**/*.py"],
exclude_patterns=["**/tests/**", "**/__pycache__/**"]
)
# Print summary
summary = result["analysis_summary"]
print(f"Security Assessment Results:")
print(f" Files Analyzed: {summary['files_analyzed']}")
print(f" Security Score: {summary['security_score']:.2f}/1.00")
print(f" Status: {summary['compliance_status']}")
# Print findings by severity
findings_by_severity = {}
for finding in result["findings"]:
severity = finding["severity"]
findings_by_severity.setdefault(severity, []).append(finding)
for severity in ["critical", "high", "medium", "low"]:
if severity in findings_by_severity:
count = len(findings_by_severity[severity])
print(f" {severity.upper()}: {count} findings")
# Print critical findings
critical_findings = findings_by_severity.get("critical", [])
if critical_findings:
print("\\nCritical Security Issues:")
for finding in critical_findings:
print(f" {finding['rule_id']}: {finding['message']}")
print(f" Location: {finding['file_path']}:{finding['line_number']}")
print(f" Recommendation: {finding['recommendation']}")
print()
return result
# Run the assessment
asyncio.run(comprehensive_security_check())
```
### Multi-Configuration Validation
```python
from mcp_compliance_validator.validators.auth_security import AuthSecurityValidator
def validate_multiple_configs():
"""Validate multiple authentication configurations."""
validator = AuthSecurityValidator()
configs = {
"Production OAuth": {
"oauth": {
"pkce_required": True,
"state_required": True,
"redirect_uri_validation": {"enabled": True},
"client_authentication": {"required": True}
}
},
"Development JWT": {
"algorithm": "HS256", # Intentionally weak for demo
"expiration_hours": 24,
"issuer_validation": {"enabled": False}
},
"Secure API Keys": {
"key_length": 64,
"rotation_enabled": True,
"revocation": {"enabled": True}
}
}
print("Authentication Configuration Validation\\n")
for name, config in configs.items():
print(f"Testing: {name}")
# Choose appropriate validator
if "oauth" in config:
result = validator.validate_oauth_implementation(config)
elif "algorithm" in config:
result = validator.validate_jwt_security(config)
else:
result = validator.validate_api_key_security(config)
# Display results
status = "SECURE" if result.is_secure else "INSECURE"
print(f" Status: {status}")
if result.findings:
print(f" Findings: {len(result.findings)}")
for finding in result.findings[:3]: # Show first 3
print(f" [{finding.severity}] {finding.message}")
if len(result.findings) > 3:
print(f" ... and {len(result.findings) - 3} more")
print()
validate_multiple_configs()
```
## Development
### Setting Up Development Environment
```bash
# Clone repository
git clone <repository-url>
cd mcp-compliance-validator
# Install development dependencies
pip install -r requirements-dev.txt
# Set up pre-commit hooks
make setup
# Run tests
make test
# Run type checking
make type-check
# Format code
make format
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=mcp_compliance_validator
# Run specific test categories
pytest tests/contract/ # Contract tests
pytest tests/unit/ # Unit tests
# Run performance tests
pytest -m "not slow" # Skip slow tests
```
### Code Style Guidelines
- **Python 3.x**: Type hints required via `typing` module, async/await patterns for tools
- **Imports**: Standard library first, then external deps, then local modules (from .. import)
- **Naming**: snake_case for functions/variables, PascalCase for classes/enums, UPPER_SNAKE for constants
- **Models**: Use Pydantic BaseModel with Field descriptors for validation models
- **Enums**: Use str-based Enums (class MyEnum(str, Enum)) for string constants
- **Error Handling**: Return structured error responses in JSON-RPC format with proper error codes
- **Async**: All tool functions must be async (async def) for MCP compatibility
- **Dataclasses**: Use @dataclass for simple data containers, Pydantic for validation
- **Path Handling**: Use pathlib.Path for file operations, not os.path
- **Testing**: pytest with fixtures, mark contract tests with @pytest.mark.contract
- **MCP Protocol**: Follow JSON-RPC 2.0 spec, handle initialize/tools/list/tools/call methods
This project follows:
- **Black** for code formatting
- **isort** for import sorting
- **flake8** for linting
- **mypy** for type checking
Run `make format` to apply all formatting rules.
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Quick Contribution Steps
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'feat: add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request
### Development Workflow
- All code must pass tests and linting
- Add tests for new functionality
- Update documentation for API changes
- Follow semantic commit conventions
## Project Status
- **Phase 1**: Setup (Completed)
- **Phase 2**: Tests (Completed)
- **Phase 3**: Implementation (Completed)
- **Phase 4**: Integration (Completed)
- **Phase 5**: Documentation (Completed)
### Recent Updates
- Complete OAuth 2.1 security validation
- Advanced JWT security checks
- API key security validation
- Full MCP protocol integration
- Performance optimization (590K+ chars/sec)
- Comprehensive documentation
- MCP documentation monitoring system
- Compliance drift detection
## Roadmap
- **Additional Protocol Support**: WebSocket, HTTP/2
- **Advanced Threat Detection**: ML-based vulnerability detection
- **Integration Extensions**: GitHub Actions, GitLab CI, Jenkins
- **Dashboard Interface**: Web-based validation dashboard
- **Custom Rule Engine**: User-defined security rules
- **Real-time Notifications**: Webhook integration for documentation changes
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- **Model Context Protocol** team for the excellent protocol specification
- **Python Security** community for security best practices
- **Open Source** contributors who make projects like this possible
## Support
- **Documentation**: [docs/](docs/)
- **Issues**: [GitHub Issues](../../issues)
- **Discussions**: [GitHub Discussions](../../discussions)
---
<div align="center">
**Built with care for the MCP community**
[Quick Start](#quick-start) •
[Documentation](#documentation) •
[Security Features](#security-features) •
[Performance](#performance)
</div>
