williamzujkowski/mcp-standards-server

MCP Standards Server

A Model Context Protocol (MCP) server that provides intelligent, context-aware access to development standards. This system enables LLMs to automatically select and apply appropriate standards based on project requirements.

Project Status

Recent Improvements (January 2025)

This project underwent significant remediation to restore functionality:

✅ Issues Resolved:

• Fixed critical CI/CD workflow failures and security vulnerabilities
• Resolved Python 3.12 compatibility issues (aioredis, type hints)
• Consolidated dependency management to pyproject.toml
• Fixed hundreds of code quality violations (flake8, mypy, black)
• Optimized GitHub workflows for 40% better performance

⚠️ Components Requiring Verification:

• Standards synchronization from GitHub repository
• Web UI deployment and functionality
• Full E2E integration testing
• Performance benchmarking baselines

See for detailed implementation status.

Features

Core Capabilities

• 25 Comprehensive Standards: Complete coverage of software development lifecycle
• Intelligent Standard Selection: Rule-based engine with 40+ detection rules
• MCP Server Implementation: Full Model Context Protocol support with multiple tools
• Standards Generation System: Template-based creation with quality assurance
• Hybrid Vector Storage: ChromaDB + in-memory for semantic search
• Multi-Language Analyzers: Python, JavaScript, Go, Java, Rust, TypeScript support

Advanced Features

• Redis Caching Layer: L1/L2 architecture for performance optimization
• Web UI: React/TypeScript interface for browsing and testing standards
• CLI Tools: Comprehensive command-line interface with documentation
• Performance Benchmarking: Continuous monitoring and optimization
• Token Optimization: Multiple compression formats for LLM efficiency
• NIST Compliance: NIST 800-53r5 control mapping and validation
• Community Features: Review process, contribution guidelines, analytics

Requirements

• Python 3.10 or higher
• Redis (optional, for caching)
• Node.js 16+ (optional, for web UI)

Quick Start

Installation

# Clone the repository
git clone https://github.com/williamzujkowski/mcp-standards-server.git
cd mcp-standards-server

# Create and activate virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Or install with specific feature sets:
pip install -e ".[full]"         # All features including web API
pip install -e ".[test]"         # Testing tools only
pip install -e ".[dev]"          # Development tools (linting, formatting)
pip install -e ".[performance]"  # Performance monitoring tools

# Install all development dependencies
pip install -e ".[dev,test,performance,visualization,full]"

# Install Redis (optional but recommended for caching)
# macOS: 
brew install redis
brew services start redis

# Ubuntu/Debian:
sudo apt-get update
sudo apt-get install redis-server
sudo systemctl start redis-server

# Windows (using WSL2):
wsl --install  # If not already installed
# Then follow Ubuntu instructions inside WSL

# Or use Docker:
docker run -d -p 6379:6379 redis:alpine

Verifying Installation

# Run basic tests to verify core functionality
pytest tests/unit/core/standards/test_rule_engine.py -v

# Check if the project is properly installed
python -c "import src; print('Installation successful')"

# Note: The CLI command (mcp-standards) requires the package to be installed
# in the current environment. If you see import errors, ensure you've run:
# pip install -e .

Basic Usage

from pathlib import Path
from src.core.standards.rule_engine import RuleEngine

# Load the rule engine
rules_path = Path("data/standards/meta/standard-selection-rules.json")
engine = RuleEngine(rules_path)

# Define your project context
context = {
    "project_type": "web_application",
    "framework": "react",
    "language": "javascript",
    "requirements": ["accessibility", "performance"]
}

# Get applicable standards
result = engine.evaluate(context)
print(f"Selected standards: {result['resolved_standards']}")

Running the MCP Server

# Start the MCP server (stdio mode for tool integration)
python -m src

# Or use the CLI
mcp-standards --help

# Start MCP server with specific options
mcp-standards serve --stdio         # For direct tool integration
mcp-standards serve --port 3000     # HTTP server mode
mcp-standards serve --daemon        # Run as background service

# Start the web UI (requires separate setup)
cd web && ./start.sh

MCP Tools Available

The MCP server exposes the following tools for LLM integration:

• get_applicable_standards: Get relevant standards based on project context
• validate_against_standard: Check code compliance with specific standards
• suggest_improvements: Get improvement recommendations
• search_standards: Semantic search across all standards
• get_compliance_mapping: Map standards to NIST controls
• analyze_code: Analyze code files for standard compliance
• get_standard_content: Retrieve full or compressed standard content

MCP Integration Examples

# Example: Using with MCP client
import mcp

# Connect to the MCP server
async with mcp.Client("stdio://python -m src") as client:
    # Get applicable standards for a project
    result = await client.call_tool(
        "get_applicable_standards",
        context={
            "project_type": "web_application",
            "framework": "react",
            "requirements": ["accessibility", "security"]
        }
    )
    
    # Validate code against standards
    validation = await client.call_tool(
        "validate_against_standard",
        code_path="./src",
        standard_id="react-18-patterns"
    )
    
    # Search for specific guidance
    search_results = await client.call_tool(
        "search_standards",
        query="authentication best practices",
        limit=5
    )

Using the Universal Project Kickstart

# Copy the kickstart prompt for any LLM
cat kickstart.md

Synchronizing Standards

The server can automatically sync standards from the GitHub repository:

# Check for updates
mcp-standards sync --check

# Perform synchronization
mcp-standards sync

# Force sync all files (ignore cache)
mcp-standards sync --force

# View sync status
mcp-standards status

# Manage cache
mcp-standards cache --list
mcp-standards cache --clear

Configure synchronization in data/standards/sync_config.yaml.

Generating Standards

Create new standards using the built-in generation system:

# List available templates
mcp-standards generate list-templates

# Generate a new standard interactively
mcp-standards generate --interactive

# Generate from a specific template
mcp-standards generate --template standards/technical.j2 --title "My New Standard"

# Generate domain-specific standard
mcp-standards generate --domain ai_ml --title "ML Pipeline Standards"

# Validate an existing standard
mcp-standards generate validate path/to/standard.md

Web UI

The project includes a React-based web UI for browsing and testing standards:

# Start the web UI
cd web
./start.sh

# Or run components separately:
# Backend API
cd web/backend
pip install -r requirements.txt
python main.py

# Frontend
cd web/frontend
npm install
npm start

The web UI provides:

• Standards browser with search and filtering
• Rule testing interface
• Real-time updates via WebSocket
• Standards analytics dashboard

Access the UI at http://localhost:3000 (frontend) and API at http://localhost:8000 (backend).

Additional CLI Commands

The enhanced CLI provides additional functionality:

# Query standards based on project context
mcp-standards query --project-type web --framework react --language javascript

# Validate code against standards
mcp-standards validate src/ --format json --severity warning

# Auto-fix code issues (preview mode)
mcp-standards validate src/ --fix --dry-run

# Configuration management
mcp-standards config --init        # Initialize configuration
mcp-standards config --show        # Display current config
mcp-standards config --validate    # Validate config file

Rule Configuration

Rules are defined in JSON format in data/standards/meta/standard-selection-rules.json. Each rule specifies:

• Conditions for when it applies
• Standards to apply when matched
• Priority for conflict resolution
• Tags for categorization

Example rule:

{
  "id": "react-web-app",
  "name": "React Web Application Standards",
  "priority": 10,
  "conditions": {
    "logic": "AND",
    "conditions": [
      {
        "field": "project_type",
        "operator": "equals",
        "value": "web_application"
      },
      {
        "field": "framework",
        "operator": "in",
        "value": ["react", "next.js", "gatsby"]
      }
    ]
  },
  "standards": [
    "react-18-patterns",
    "javascript-es2025",
    "frontend-accessibility"
  ],
  "tags": ["frontend", "react", "web"]
}

Available Standards

The system includes 25 comprehensive standards:

Specialty Domains (8)

• AI/ML Operations, Blockchain/Web3, IoT/Edge Computing, Gaming Development
• AR/VR Development, Advanced API Design, Database Optimization, Green Computing

Testing & Quality (3)

• Advanced Testing, Code Review, Performance Optimization

Security & Compliance (3)

• Security Review & Audit, Data Privacy, Business Continuity

Documentation & Communication (4)

• Technical Content, Documentation Writing, Team Collaboration, Project Planning

Operations & Infrastructure (4)

• Deployment & Release, Monitoring & Incident Response, SRE, Technical Debt

User Experience (3)

• Advanced Accessibility, Internationalization, Developer Experience

See for details.

Architecture

mcp-standards-server/
├── src/
│   ├── core/
│   │   ├── mcp/              # MCP server implementation
│   │   ├── standards/        # Standards engine & storage
│   │   └── cache/            # Redis caching layer
│   ├── analyzers/            # Language-specific analyzers
│   ├── generators/           # Standards generation system
│   └── cli/                  # CLI interface
├── web/                      # React/TypeScript UI (separate app)
│   ├── frontend/            # React application
│   └── backend/             # FastAPI backend
├── data/
│   └── standards/            # 25 comprehensive standards
│       ├── meta/            # Rule engine configuration
│       └── cache/           # Local file cache
├── templates/                # Standard generation templates
├── tests/                    # Comprehensive test suite
├── benchmarks/              # Performance benchmarking
└── docs/                    # Documentation

Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=term-missing

# Run specific test categories
pytest tests/unit/          # Unit tests only
pytest tests/integration/   # Integration tests
pytest tests/e2e/          # End-to-end tests

# Run specific test file
pytest tests/unit/core/standards/test_rule_engine.py

# Run performance tests
python run_performance_tests.py

# Run tests in parallel (faster)
python run_tests_parallel.py

Development Workflow

Setting Up Development Environment

# Clone the repository
git clone https://github.com/williamzujkowski/mcp-standards-server.git
cd mcp-standards-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,test,performance,visualization,full]"

# Install pre-commit hooks (if available)
pre-commit install

Running Benchmarks

# Run all benchmarks
python benchmarks/run_benchmarks.py

# Run specific benchmark suites
python benchmarks/analyzer_performance.py
python benchmarks/semantic_search_benchmark.py
python benchmarks/token_optimization_benchmark.py

# Generate performance reports
python benchmarks/run_benchmarks.py --report

CI/CD Integration

The project uses GitHub Actions for continuous integration:

• CI Badge: Runs tests on every push and pull request
• Release Badge: Automates releases to PyPI
• Benchmark Badge: Tracks performance metrics over time

Using in Your CI/CD Pipeline

# Example GitHub Actions workflow
- name: Validate Standards
  run: |
    pip install mcp-standards-server
    mcp-standards validate . --format sarif --output results.sarif
    
- name: Upload SARIF results
  uses: github/codeql-action/upload-sarif@v2
  with:
    sarif_file: results.sarif

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Documentation

Quick Start

• - Copy-paste prompt for any LLM
• - All 25 standards
• - How to create new standards

Technical Documentation

• - Current project status and roadmap
• - Main system documentation

License

This project is licensed under the MIT License.

Troubleshooting

Common Issues

1. Redis connection errors: Ensure Redis is running or disable caching:

   export MCP_STANDARDS_NO_CACHE=true
   

2. Import errors: Make sure you installed in development mode:

   pip install -e .
   

3. MCP server not starting: Check for port conflicts:

   lsof -i :3000  # Check if port is in use
   

Environment Variables

The following environment variables can be used to configure the server:

• MCP_STANDARDS_CONFIG: Path to custom configuration file
• MCP_STANDARDS_CACHE_DIR: Override default cache directory
• MCP_STANDARDS_NO_CACHE: Disable caching (set to true)
• MCP_STANDARDS_LOG_LEVEL: Set logging level (DEBUG, INFO, WARNING, ERROR)
• REDIS_URL: Custom Redis connection URL
• NO_COLOR: Disable colored output in CLI

Performance Tips

1. Enable Redis caching for better performance with large codebases
2. Use token optimization when working with LLMs with limited context
3. Run analyzers in parallel for faster code validation
4. Use the rule engine for efficient standard selection

Acknowledgments

This project is part of the williamzujkowski/standards ecosystem, designed to improve code quality and consistency through intelligent standard selection and application.