README.md
Enables Python code linting by integrating the Model Context Protocol
MCP Python Linter
Overview
This project demonstrates the use of the Model Context Protocol (MCP) to enable linting capabilities for Python code. The MCP framework allows seamless integration between tools and LLMs, where tools perform the actual work, and LLMs orchestrate and interpret the results.
Key Features
- MCP Integration: Implements a true MCP flow for linting Python code.
- Tool Discovery and Invocation: Dynamically lists and invokes tools registered on the MCP server.
- Linting with OpenAI: Uses OpenAI's API to analyze code and return structured linting results.
How It Works
Workflow
- Client Initialization: The client reads the code to be analyzed and connects to the MCP server.
- Tool Discovery: The client retrieves the list of available tools from the server.
- Tool Invocation: The client invokes the linting tool, passing the code to be analyzed.
- Linting Execution: The server processes the request, runs the linting logic, and returns the results.
- Result Interpretation: The client displays the raw linting results and optionally uses an LLM to interpret them.
Architecture
Client → MCP Server → Lint Engine → OpenAI API
- Client: Handles user interaction and communicates with the MCP server.
- MCP Server: Manages tool registration and invocation.
- Lint Engine: Implements the actual linting logic.
- OpenAI API: Provides advanced code analysis capabilities.
Updated MCP-Based Linting Workflow
Overview
This project demonstrates a real MCP-based linting scenario where the LLM is used for both tool selection and result refinement. The workflow ensures that the MCP server handles the actual linting, while the LLM orchestrates and interprets the results.
Workflow
- Tool Selection:
- The client retrieves the list of available tools from the MCP server.
- The LLM selects the most appropriate tool for the given code.
- Linting Execution:
- The selected tool is invoked via the MCP server to analyze the code.
- The MCP server returns raw linting results.
- Result Refinement:
- The raw linting results are sent to the LLM for detailed analysis and suggestions.
Example Output
======================================================================
MCP-BASED LINTER
======================================================================
Connecting to MCP server...
✓ Connected to MCP server
✓ Available tools: ['pylint', 'eslint', 'tflint']
LLM selected tool: pylint
======================================================================
STEP 2: Executing selected linter tool
======================================================================
✓ Linter tool executed successfully
Raw linting results:
----------------------------------------------------------------------
[{'line': 1, 'message': 'Missing docstring', 'severity': 'warning'}]
----------------------------------------------------------------------
======================================================================
STEP 3: Refining linting results with LLM
======================================================================
✓ LLM refined the linting results
Refined analysis:
- Line 1: Missing docstring. Add a docstring to describe the function's purpose.
Key Benefits
- Dynamic Tool Selection: The LLM dynamically selects the most appropriate tool based on the available options.
- Separation of Concerns: The MCP server handles linting, while the LLM focuses on orchestration and interpretation.
- Extensibility: Easily add new tools to the MCP server without modifying the client logic.
Usage
Prerequisites
- Python 3.8+
- Install dependencies:
pip install -r requirements.txt - Ensure the OpenAI API key is set in the
.envfile:OPENAI_API_KEY=your-api-key
Running the Linter
- Start the MCP server:
python server/mcp_server.py - Run the client:
python client/mcp_client.py
Example Output
======================================================================
MCP-BASED LINTER
======================================================================
Connecting to MCP server...
✓ Connected to MCP server
✓ Available tools: ['analyze_python_code']
======================================================================
STEP 2: Executing linter tool directly
======================================================================
✓ Linter tool executed successfully
Raw linting results:
----------------------------------------------------------------------
[{'line': 1, 'message': 'Missing docstring', 'severity': 'warning'}]
----------------------------------------------------------------------
Project Structure
.
├── README.md
├── requirements.txt
├── client/
│ ├── mcp_client.py # Client implementation
├── server/
│ ├── mcp_server.py # MCP server implementation
│ ├── li
Tools (1)
analyze_python_codeAnalyzes Python code for linting issues and returns structured results.Environment Variables
OPENAI_API_KEYrequiredAPI key for OpenAI to enable refined analysis of linting resultsConfiguration
claude_desktop_config.json
{"mcpServers": {"python-linter": {"command": "python", "args": ["/path/to/server/mcp_server.py"], "env": {"OPENAI_API_KEY": "your-api-key"}}}}Try it
→Analyze the following Python code for potential issues: [paste code]
→Run a linting check on my current script and suggest improvements for the identified warnings.
→Use the python linter to check for missing docstrings or style violations in this file.
→Refine the raw linting results for this code to provide actionable suggestions.