# Ruff MCP Server

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

### Installation

```bash
# 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:

```bash
# 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

```bash
# 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:

```json
{
  "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](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

```json
{
  "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:

```bash
# 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

```bash
# 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](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
```json
{
  "name": "ruff_check",
  "arguments": {
    "path": "my_script.py",
    "format": "json"
  }
}
```

#### Formatting code
```json
{
  "name": "ruff_format", 
  "arguments": {
    "path": "my_script.py",
    "check_only": false
  }
}
```

#### Auto-fixing violations
```json
{
  "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

```bash
# 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:

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

## Configuration

You can customize Ruff behavior by providing a configuration file:

```bash
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

```bash
# 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

```bash
# 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:
```python
"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](LICENSE) file for details.