io.github.Anselmoo/mcp-server-analyzer

MCP Server Analyzer for Python 🐍🔍

A powerful Model Context Protocol (MCP) server that provides comprehensive Python code analysis using **Ruff** for linting, **ty** for type checking, and **Vulture** for dead code detection. Perfect for AI assistants, IDEs, and automated code review workflows.

🚀 Quick Start

VS Code Integration (One-Click Install)

For quick installation, use one of the one-click install buttons below...

For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing Ctrl + Shift + P and typing Preferences: Open User Settings (JSON).

Optionally, you can add it to a file called .vscode/mcp.json in your workspace. This will allow you to share the configuration with others.

Note that the mcp key is needed when using the mcp.json file.

Using uvx (recommended):

{
  "mcp": {
    "servers": {
      "analyzer": {
        "command": "uvx",
        "args": ["mcp-server-analyzer"]
      }
    }
  }
}

Using Docker:

{
  "mcp": {
    "servers": {
      "analyzer": {
        "command": "docker",
        "args": ["run", "-i", "--rm", "ghcr.io/anselmoo/mcp-server-analyzer"]
      }
    }
  }
}

Universal Installation

# Install with uvx (recommended)
uvx install mcp-server-analyzer

# Install with pip
pip install mcp-server-analyzer

# Run with Docker
docker run ghcr.io/anselmoo/mcp-server-analyzer:latest

# Install from source
git clone https://github.com/anselmoo/mcp-server-analyzer.git
cd mcp-server-analyzer
uv sync --dev
uv run mcp-server-analyzer

📋 Features

• 🔍 RUFF Analysis: Comprehensive Python linting with auto-fixes
• 🧠 ty Type Checking: Fast Python type analysis with rule-based diagnostics
• 🧹 Dead Code Detection: Find unused imports, functions, and variables with VULTURE
• ⚡ Biome JS/TS Analysis: Fast linting and formatting for JavaScript and TypeScript
• 📊 Quality Scoring: Combined analysis with quality metrics
• 🚀 FastMCP Framework: High-performance MCP server implementation
• 🐳 Docker Ready: Multi-architecture containers with security signing
• 🔒 Secure: All releases signed with Sigstore for supply chain security

📈 Analysis Examples

RUFF Linting Preview

See comprehensive linting analysis examples: 📋 RUFF Analysis Preview

VULTURE Dead Code Detection Preview

Explore dead code detection capabilities: 🧹 VULTURE Analysis Preview

🛠️ Available Tools

🔧 Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "analyzer": {
      "command": "uvx",
      "args": ["mcp-server-analyzer"]
    }
  }
}

Zed

Add to your Zed settings.json:

"context_servers": {
  "analyzer": {
    "command": "uvx",
    "args": ["mcp-server-analyzer"]
  }
}

Claude Code (project-level)

Place .mcp.json at your project root:

{
  "mcpServers": {
    "analyzer": {
      "command": "uvx",
      "args": ["mcp-server-analyzer"]
    }
  }
}

🧪 Development

Prerequisites

• Python 3.13+
• uv (recommended) or pip
• Node.js 22+ (for Biome JS/TS analysis)
• Docker (optional)

Setup

# Clone repository
git clone https://github.com/anselmoo/mcp-server-analyzer.git
cd mcp-server-analyzer

# Install Python dependencies
uv sync --dev

# Install Biome (JS/TS analyzer)
npm ci

# Run tests
uv run pytest

# Run type checks
uv run ty check src tests

# Run pre-commit hooks
uv tool run pre-commit run --all-files

# Build Docker image
docker build -t mcp-server-analyzer .

Testing

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest --cov=src/mcp_server_analyzer --cov-report=html

# Test specific functionality
uv run pytest tests/test_server.py::TestAnalyzers::test_ruff_with_sample_code

📊 Quality Metrics

The server provides quality scoring based on:

• Ruff Issues: Style violations, potential bugs, complexity metrics
• ty Diagnostics: Static typing errors and warnings
• Dead Code Detection: Unused imports, functions, variables
• Combined Score: Weighted quality assessment (0-100)

🔒 Security

• Signed Releases: All releases signed with Sigstore
• Container Signing: Docker images signed with Cosign
• Trusted Publishing: PyPI releases use GitHub OIDC trusted publishing
• Vulnerability Scanning: Automated security scanning in CI/CD
• Supply Chain Security: SLSA Build Level 3 compliance
• Security Policy: See SECURITY.md for vulnerability reporting

🔍 Data Handling & Transparency

• In-memory only: Code passed to tools is written to a temporary file, analyzed, and the file is deleted immediately — nothing is persisted between calls.
• No network calls: The server makes no outbound network connections during analysis.
• No telemetry: No usage data, analytics, or crash reports are collected.
• Subprocess isolation: ruff, ty, and vulture are invoked with fixed argument lists — no shell expansion or arbitrary command execution.

📚 Documentation

• Full Documentation - GitHub Pages docs
• Tools Reference - Detailed tool parameters and return types
• MCP Specification - Learn about Model Context Protocol
• FastMCP Framework - High-performance MCP implementation
• Ruff Documentation - Python linter and formatter
• ty Documentation - Python type checker and language server
• Vulture Documentation - Dead code finder

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using Conventional Commits
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Astral for RUFF and uv
• Jendrik Seipp for VULTURE
• Model Context Protocol team
• FastMCP framework

Made with ❤️ for better Python code quality