Ruff MCP Server

An MCP (Model Context Protocol) server providing comprehensive Ruff linting, formatting, and code analysis tools with advanced logging capabilities.## Usage

Installation

# Install from source (recommended for development)
pip install -e .

# Or install directly
pip install .

Running the MCP Server

After installation, you can start the server using any of these methods:

# Method 1: Use the installed command (recommended)
ruff-mcp-server

# Method 2: Run as Python module
python -m ruff_mcp_server

# Method 3: Use convenience script
./scripts/run_server.sh

# Method 4: Run directly from source
python src/ruff_mcp_server/main.py

Command Line Options

# Disable online documentation fetching (use static docs only)
ruff-mcp-server --no-online-docs

# Configure logging
ruff-mcp-server --log-level DEBUG                    # Set log level
ruff-mcp-server --log-file /path/to/logfile.log      # Log to file
ruff-mcp-server --no-console-log                     # Disable console logging

# Combined example: Debug mode with file logging
ruff-mcp-server --log-level DEBUG --log-file ./logs/ruff-mcp-debug.log

# Show help
ruff-mcp-server --help

MCP Client Configuration

The server uses stdio communication (not HTTP ports). Configure your MCP client with:

{
  "servers": {
    "ruff-mcp-server": {
      "command": "ruff-mcp-server",
      "args": ["--log-level", "INFO"]
    }
  }
}

Server Status: When running, you'll see:

============================================================
🚀 RUFF MCP SERVER  
============================================================
📡 Communication: Standard I/O (stdin/stdout)
🔗 Protocol: Model Context Protocol (MCP)  
📚 Online Docs: Enabled
🛑 Shutdown: Press Ctrl+C for graceful shutdown
============================================================

See docs/MCP_CONFIGURATION.md for detailed configuration examples and troubleshooting.

Configuration Philosophy

The Ruff MCP server follows a stateless, agent-driven configuration approach:

• No Server-Side Config: The server doesn't store default Ruff configurations
• Agent Provides Context: The AI agent passes configuration with each request
• Auto-Discovery: When no config is specified, Ruff automatically finds pyproject.toml or ruff.toml in the project
• Flexible Overrides: Agents can override specific settings (rules, line length) per request

Example: Agent-Driven Configuration

{
  "name": "ruff_check",
  "arguments": {
    "path": "src/",
    "config_path": "pyproject.toml",     // Use project's config
    "select": ["F", "E4", "W"],         // Focus on specific rule categories  
    "ignore": ["E203", "W503"]          // Ignore specific rules
  }
}

This approach ensures the server respects the agent's workspace context and project-specific requirements.

Testing the Server

Test scripts are provided to verify the server works correctly:

# Test basic server functionality
python test_server.py

# Test logging system
python test_logging.py

Logging & Monitoring

The Ruff MCP Server includes comprehensive logging capabilities for debugging, monitoring, and performance analysis.

Quick Logging Setup

# Basic logging to console (default)
ruff-mcp-server

# Debug mode with file logging
ruff-mcp-server --log-level DEBUG --log-file ./logs/ruff-mcp-debug.log

# Production mode - warnings and errors only
ruff-mcp-server --log-level WARNING --log-file /var/log/ruff-mcp.log --no-console-log

Log Categories

• Server Operations: Startup, shutdown, tool management
• Tool Execution: Individual tool performance and results
• Ruff Commands: Command execution with timing
• Documentation: Online documentation fetching and caching
• Performance: Automatic execution time tracking

Detailed Logging Guide

See docs/LOGGING.md for comprehensive logging documentation including:

• Log levels and categories
• Performance monitoring
• Production monitoring setup
• Debug techniques
• Log analysis examples

Using with MCP Clients

The server implements the Model Context Protocol and can be used with any MCP-compatible AI coding assistant. Configure your client to connect to this server and you'll have access to the following tools:

1. ruff_check - Lint Python files and get detailed violation reports
2. ruff_format - Format Python code or check formatting
3. ruff_fix - Automatically fix linting violations where possible

Example Tool Usage

Linting a file

{
  "name": "ruff_check",
  "arguments": {
    "path": "my_script.py",
    "format": "json"
  }
}

Formatting code

{
  "name": "ruff_format", 
  "arguments": {
    "path": "my_script.py",
    "check_only": false
  }
}

Auto-fixing violations

{
  "name": "ruff_fix",
  "arguments": {
    "path": "my_script.py",
    "unsafe": false
  }
}
```rver that provides Ruff linting and code analysis tools for AI coding assistants.

## Features

- 🔧 **Ruff Integration**: Run linting and formatting through MCP tools
- 📊 **Code Analysis**: Detailed code quality reports and suggestions
- � **Inline Documentation**: Get immediate explanations and fix suggestions for violations
- �🛠️ **Configurable**: Support for custom Ruff configurations
- 🚀 **Fast**: Leverages Ruff's speed for real-time analysis

## Tools Provided

### `ruff_check`
Run Ruff linting on files or directories
- **Parameters**: `path` (file or directory), `config_path` (optional)
- **Returns**: Linting results with violations and suggestions

### `ruff_format`
Format Python code using Ruff
- **Parameters**: `path` (file or directory), `check_only` (optional)
- **Returns**: Formatted code or formatting diff

### `ruff_fix`
Auto-fix linting violations where possible
- **Parameters**: `path` (file or directory), `unsafe` (optional)
- **Returns**: Applied fixes and remaining violations

## Installation

```bash
# Clone the repository
git clone <repository-url>
cd ruff-mcp-server

# Install dependencies
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Usage

Running the MCP Server

# Start the server
ruff-mcp-server

# Or run with custom configuration
ruff-mcp-server --config /path/to/ruff.toml

Connecting to AI Clients

Add this server to your MCP client configuration:

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

Configuration

You can customize Ruff behavior by providing a configuration file:

ruff-mcp-server --config pyproject.toml
# or  
ruff-mcp-server --config ruff.toml

See ruff.toml.example for a sample configuration file.

Development

Setup Development Environment

# Clone the repository
git clone <repository-url>
cd ruff-mcp-server

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

# Install in development mode
pip install -e ".[dev]"

Running Tests

# Test the MCP server
python test_server.py

# Check code quality
ruff check .
ruff format .

Extending Rule Documentation

The server includes inline documentation for common Ruff rules in the get_rule_documentation() function in main.py. To add documentation for additional rules:

1. Find the rule code (e.g., "E401", "F401")
2. Add an entry to the rule_docs dictionary with a helpful explanation
3. Focus on providing actionable fix suggestions rather than just describing the problem

Example:

"E401": "Combine multiple imports on separate lines. Use 'import os, sys' → 'import os\\nimport sys'"

Features

• ✅ Fast and Reliable: Built on Ruff's lightning-fast Python linter and formatter
• ✅ MCP Compatible: Works with any Model Context Protocol client
• ✅ Rich Output: Beautifully formatted violation reports with emojis and inline documentation
• ✅ Inline Help: Provides immediate explanations and fix suggestions for each violation
• ✅ Configurable: Supports all Ruff configuration options
• ✅ Error Handling: Robust error handling with helpful error messages
• ✅ Multiple Formats: Supports JSON, text, GitHub, GitLab, JUnit, and SARIF output formats

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.