Multi-Agent MCP Server

![License: MIT](https://opensource.org/licenses/MIT) ![Python 3.10+](https://www.python.org/downloads/) ![MCP](https://modelcontextprotocol.io/) ![Smithery](https://smithery.ai/)

A production-ready, modular multi-agent MCP server for automated codebase review and documentation generation. Built with the Model Context Protocol (MCP) for seamless integration with AI development workflows and compatible with Smithery for easy deployment.

🚀 Features

🤖 Multi-Agent Architecture: Specialized AI agents for different analysis types
Debt Agent: Technical debt and maintainability analysis
Improvement Agent: Code quality improvement recommendations
Critical Agent: Security vulnerabilities and reliability issues
Documentation Agent: Comprehensive project documentation generation
📡 MCP Integration: Full Model Context Protocol support for AI tool integration
🔀 Workflow Orchestration: Advanced DSPy workflow integration for intelligent analysis
✅ Strict Validation: Comprehensive output validation with Pydantic schemas
🏭 Production Ready: Comprehensive testing, logging, and professional packaging
☁️ Smithery Compatible: Ready for deployment on Smithery platform
⚡ Flexible Execution: Quick scan for fast analysis or deep scan with LLM integration

🛠️ Installation

Via Smithery (Recommended)

The easiest way to use this MCP server is through Smithery:

Visit Smithery
Search for "multi-agent-code-review"
Add to your AI workflow with one click

Python Package

# Using uv (recommended)
uv add multiagent-mcp-server

# Using pip
pip install multiagent-mcp-server

# Using conda
conda install -c conda-forge multiagent-mcp-server

From Source

# Clone the repository
git clone https://github.com/Arpit-Moga/Vibechecker.git
cd Vibechecker

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

🚀 Quick Start

As MCP Server

# Run the MCP server
python -m multiagent_mcp_server

# Or using the installed script
multiagent-mcp-server

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Continue, etc.):

{
  "mcpServers": {
    "multi-agent-code-review": {
      "command": "python",
      "args": ["-m", "multiagent_mcp_server"],
      "env": {
        "CODE_DIRECTORY": "./",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

With Environment Variables

# Set API keys for LLM analysis (optional for quick mode)
export GOOGLE_API_KEY="your-google-api-key"
export OPENAI_API_KEY="your-openai-api-key"

# Configure analysis settings
export CODE_DIRECTORY="/path/to/your/project"
export MAX_FILE_SIZE_MB="10.0"
export LOG_LEVEL="INFO"

# Run the server
python -m multiagent_mcp_server

🔧 MCP Tools Reference

The server provides the following MCP tools for AI agents:

`issue_detection_review`

Runs unified issue detection analysis on the specified code directory.

Parameters:

code_directory (string, optional): Path to analyze (default: current directory)
output_directory (string, optional): Output path (default: ./DOCUMENTATION)
output_format (enum): "md" or "json" (default: "md")
scan_mode (enum): "quick" or "deep" (default: "quick")

Example: ``json { "tool": "issue_detection_review", "arguments": { "code_directory": "./src", "scan_mode": "deep", "output_format": "json" } } ``

`documentation_generate`

Generates comprehensive project documentation.

Parameters:

code_directory (string, optional): Path to analyze
output_directory (string, optional): Output path

`comprehensive_review`

Runs all analyses in a coordinated workflow for complete project review.

Parameters: Same as issue_detection_review

☁️ Smithery Integration

This MCP server is fully compatible with Smithery, providing:

Easy Deployment: One-click deployment to Smithery cloud
Automatic Discovery: Server is automatically indexed in Smithery registry
Configuration Schema: Full JSON schema validation for parameters
HTTP Transport: Optional HTTP endpoint for remote access
Security Scanning: Passes Smithery security validation

Smithery Configuration

The server includes a smithery.yaml configuration file that defines:

Server metadata and capabilities
Connection methods (stdio and HTTP)
Tool schemas and validation
Security settings

Publishing to Smithery

Ensure your code is in a public GitHub repository
Add proper tags and description in smithery.yaml
Smithery will automatically discover and index your server
Users can then find and use your server through the Smithery platform

⚙️ Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | CODE_DIRECTORY | Default directory to analyze | . | | GOOGLE_API_KEY | Google AI API key for LLM analysis | None | | OPENAI_API_KEY | OpenAI API key for LLM analysis | None | | MAX_FILE_SIZE_MB | Maximum file size to process | 5.0 | | MAX_FILES_TO_PROCESS | Maximum number of files | 100 | | LOG_LEVEL | Logging level | INFO |

Scan Modes

Quick Mode: Fast static analysis using linting tools (ruff, bandit, mypy)
Deep Mode: Comprehensive analysis including LLM-powered review

Output Formats

Markdown: Human-readable reports with formatting
JSON: Structured data for programmatic consumption

📚 API Documentation

Response Format

All tools return a consistent response structure:

interface AgentReport {
  issues: IssueOutput[];
  review: string;
  total_issues?: number;
  high_severity_count?: number;
  documentation_files?: number;
  error?: boolean;
}

interface IssueOutput {
  type: "maintainability" | "security" | "performance" | "compliance" | "other";
  severity: "low" | "medium" | "high";
  description: string;
  file: string;
  line: number;
  suggestion?: string;        // For maintainability/performance
  remediation?: string;       // For security/compliance
  reference?: string;
}

Error Handling

The server implements comprehensive error handling:

Input validation with detailed error messages
Graceful degradation when tools are unavailable
Structured error responses with error codes
Comprehensive logging for debugging

🧪 Development

Prerequisites

Python 3.10+
uv package manager (recommended) or pip

Setup Development Environment

# Clone the repository
git clone https://github.com/Arpit-Moga/Vibechecker.git
cd Vibechecker

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=multiagent_mcp_server

# Run specific test file
pytest tests/test_models.py -v

Code Quality

# Format code
black src tests
isort src tests

# Lint code
flake8 src tests
mypy src

# Security scan
bandit -r src

Project Structure

multiagent-mcp-server/
├── src/multiagent_mcp_server/    # Main package
│   ├── __init__.py               # Package exports
│   ├── __main__.py               # Module entry point
│   ├── server.py                 # MCP server implementation
│   ├── models.py                 # Pydantic models
│   ├── config.py                 # Configuration management
│   ├── base_agent.py             # Base agent class
│   ├── issue_detection_agent.py  # Issue detection logic
│   ├── documentation_agent.py    # Documentation generation
│   └── ...                       # Other modules
├── tests/                        # Test suite
├── docs/                         # Documentation
├── smithery.yaml                 # Smithery configuration
├── mcp.json                      # MCP manifest
├── pyproject.toml                # Package configuration
└── README.md                     # This file

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow PEP 8 style guidelines
Add type hints to all functions
Write comprehensive tests for new features
Update documentation as needed
Ensure backwards compatibility

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol for the excellent protocol specification
Smithery for the amazing MCP server registry and deployment platform
FastMCP for the simplified MCP server framework
DSPy for advanced workflow orchestration
All contributors and the open-source community

🔗 Links

GitHub Repository: https://github.com/Arpit-Moga/Vibechecker
Smithery Registry: https://smithery.ai/
Model Context Protocol: https://modelcontextprotocol.io/
Documentation: https://github.com/Arpit-Moga/Vibechecker/tree/main/docs
Issue Tracker: https://github.com/Arpit-Moga/Vibechecker/issues

---

Ready to supercharge your code review process? Try the Multi-Agent MCP Server today! 🚀

🚦 Quick Start

Start the Server

# Using the installed package
multiagent-mcp-server

# Or using Python module
python -m multiagent_mcp_server.server

🧩 MCP Tools Reference

The server exposes agent tools via the Model Context Protocol (MCP), not RESTful HTTP endpoints.

Available MCP Tools

| Tool Name | Description | |----------------------------|--------------------------------------------------| | issue_detection_review | Unified code issue detection and analysis | | documentation_generate | Generate comprehensive project documentation | | comprehensive_review | Run all agents for complete codebase analysis |

Refer to the MCP documentation for integration details.

📖 Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started Guide - Quick start tutorial
Architecture Guide - System architecture overview
Development Guide - Development setup and guidelines
Agent Documentation - Agent-specific documentation

🏗️ System Architecture

flowchart TD
    subgraph Agents
        A1[Documentation Agent]
        A2[Unified Issue Detection Agent]
    end
    subgraph Plugins
        P1[Bandit Plugin]
        P2[Mypy Plugin]
        P3[Ruff Plugin]
        P4[Semgrep Plugin]
    end
    U[User/Client] --> S[MCP Server]
    S --> Agents
    S --> Plugins
    Agents --> R[Aggregated Report]
    Plugins --> R
    R --> U

🔧 Development