Ruff MCP Server

Ruff MCP服务器

MCP（模型上下文协议）服务器，提供全面的Ruff linting、格式化和代码分析工具，并具有高级日志记录功能。##使用方法

安装

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

# Or install directly
pip install .

运行MCP服务器

安装后，您可以使用以下任何方法启动服务器：

# 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

命令行选项

# 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客户端配置

服务器使用 stdio通信 （不是HTTP端口）。使用以下配置您的MCP客户端：

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

服务器状态：跑步时，您将看到：

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

看 docs/MCP_CONFIGURATION.md 了解详细的配置示例和故障排除。

配置原理

Ruff MCP服务器遵循 无状态、代理驱动的配置 方法：

• 无服务器端配置：服务器不存储默认的Ruff配置
• 代理提供上下文：AI代理在每次请求时传递配置
• 自动发现：当没有指定配置时，Ruff会自动查找 pyproject.toml 或 ruff.toml 在项目中
• 灵活的覆盖：代理可以覆盖每个请求的特定设置（规则、行长度）

示例：代理驱动配置

{
  "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
  }
}

这种方法确保服务器尊重代理的工作区上下文和特定于项目的要求。

测试服务器

提供测试脚本以验证服务器是否正常工作：

# Test basic server functionality
python test_server.py

# Test logging system
python test_logging.py

记录和监控

Ruff MCP Server包括用于调试、监控和性能分析的全面日志记录功能。

快速日志记录设置

# 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

日志类别

• 服务器操作：启动、关闭、工具管理
• 工具执行：单个工具的性能和结果
• Ruff命令：带定时的命令执行
• 文档：在线文档获取和缓存
• 演出：自动执行时间跟踪

详细日志记录指南

看 docs/LOGGING.md 用于全面的日志记录，包括：

• 日志级别和类别
• 性能监控
• 生产监控设置
• 调试技术
• 日志分析示例

与MCP客户端一起使用

该服务器实现了模型上下文协议，可以与任何兼容MCP的AI编码助手一起使用。配置您的客户端以连接到此服务器，您将可以访问以下工具：

1. ruff_check -抓取Python文件并获取详细的违规报告
2. ruff_format -设置Python代码格式或检查格式
3. ruff_fix -在可能的情况下自动修复linting违规

工具使用示例

翻动文件

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

格式化代码

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

汽车修理违规

{
  "name": "ruff_fix",
  "arguments": {
    "path": "my_script.py",
    "unsafe": false
  }
}

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

# Clone the repository
git clone 
cd ruff-mcp-server

# Install dependencies
pip install -e .

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

用法

运行MCP服务器

# Start the server
ruff-mcp-server

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

连接到AI客户端

将此服务器添加到MCP客户端配置中：

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

配置

您可以通过提供配置文件来自定义Ruff行为：

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

看 ruff.toml.example 查看示例配置文件。

发展

设置开发环境

# Clone the repository
git clone 
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]"

运行测试

# Test the MCP server
python test_server.py

# Check code quality
ruff check .
ruff format .

扩展规则文档

该服务器在 get_rule_documentation() 功能在 main.py。要添加其他规则的文档：

1. 查找规则代码（例如“E401”、“F401”）
2. 向添加条目 rule_docs 附有有用解释的词典
3. 专注于提供可操作的修复建议，而不仅仅是描述问题

例子：

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

特性

• ✅ 快速可靠：基于Ruff闪电般快速的Python linter和格式化程序构建
• ✅ MCP兼容：适用于任何模型上下文协议客户端
• ✅ 丰富的输出：格式精美的违规报告，带有表情符号和内联文档
• ✅ 内联帮助：为每个违规行为提供即时解释和修复建议
• ✅ 可配置的：支持所有Ruff配置选项
• ✅ 错误处理：强大的错误处理功能，提供有用的错误消息
• ✅ 多种格式：支持JSON、文本、GitHub、GitLab、JUnit和SARIF输出格式

贡献

欢迎投稿！请随时提交拉取请求。

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。