Python Code Explorer

🚀 Python Code Analysis Tool

This project offers a variety of Python code analysis functions and fully supports the Model Context Protocol (MCP) standard.

✨ Features

Main Features

1. Code Extraction
2. Dependency Analysis
3. Resource Provision
4. Custom Tools

MCP Integration

This project has two implementation methods to support the MCP protocol:

1. Native MCP Implementation: A direct JSON-RPC interface located in agent.py, which is compatible with MCP.
2. MCP SDK Implementation: Located in server.py, it uses the official Python MCP SDK to provide a more powerful and feature-rich experience.

Advantages

• Standardized Interface: Makes your tools available to any MCP-compatible client.
• Enhanced Security: Built-in permission model and resource control.
• Better LLM Integration: Seamlessly integrates with Claude Desktop and other LLM platforms.
• Improved Developer Experience: Comprehensive tool support, such as the MCP Inspector.

MCP Protocol Version

This implementation supports MCP protocol version 0.7.0. For more detailed information, please refer to the official documentation.

🚀 Quick Start

Install Dependencies

Install the Python packages required for the project:

pip install mcp[yaml]

Clone the Repository

Clone this repository to your local machine:

git clone https://github.com/yourusername/python-code-analyzer.git
cd python-code-analyzer

Start the Agent or Server

Start the agent of the native MCP implementation or the server of the MCP SDK implementation according to your needs.

📦 Installation

Native MCP Implementation (agent.py)

Start the Agent

# Start with default settings
python agent.py

# Specify a custom name
python agent.py --name "My Code Explorer"

# Use a specific .env file
python agent.py --env-file .env.production

Development Mode

Start the agent in development mode using the MCP CLI:

# Install the MCP CLI
pip install "mcp[cli]"

# Start the agent in development mode with the Inspector UI
mcp dev agent.py

MCP SDK Implementation (server.py)

Start the Server

# Start the server with default settings
python server.py

# Specify a custom name
python server.py --name "Custom Code Explorer"

# Use a specific configuration file
python server.py --config config.yaml

Integration in Claude Desktop

Install this agent to Claude Desktop:

# Install the agent to Claude Desktop
mcp install agent.py

# Specify a custom name and configuration file
mcp install agent.py --name "Python Code Analyzer" -f config.yaml

Custom Deployment

For custom deployment, you can directly use the MCP server:

from server import Server

# Configure the server
server.name = "Custom Python Analyzer"

# Start the server
server.run()

💻 Usage Examples

Using the MCP Client

You can find an example in examples/mcp_client_example.py:

from mcp.client import Client, Transport

# Connect to the server
client = Client(Transport.subprocess(["python", "server.py"]))
client.initialize()

# List all available tools
for tool in client.tools:
    print(f"Tool: {tool.name}")

# Use the get_code tool
result = client.tools.get_code(target_file="path/to/your/file.py")
print(f"Found {len(result['referenced_files'])} referenced files")

# Close the connection
client.shutdown()

Run the example:

python examples/mcp_client_example.py [optional_target_file.py]

Native MCP Implementation Example

Use the functions in agent.py:

# Extract code and analyze dependencies
python agent.py extract --file /path/to/your/script.py

# Analyze resources
python agent.py analyze-resources --source /path/to/resource

📚 Documentation

Configuration

Native MCP Implementation Configuration

You can find the default configuration in config.yaml:

log_level: INFO
bind: 0.0.0.0
port: 5000

MCP SDK Implementation Configuration

You can find the default configuration in server_config.yaml:

name: Python Code Analyzer Server
bind: 0.0.0.0
port: 8000
tools:
  enabled:
    analyze_imports: true
    get_stats: true

Project Structure

• agent.py - Agent for the native MCP implementation
• server.py - Server for the MCP SDK implementation
• examples/ - Example code
• config.yaml - Default configuration file

🔧 Technical Details

Adding More Tools

You can add other tools in server.py using the decorator @mcp.tool():

@mcp.tool()
def analyze_imports(target_file: str) -> Dict[str, Any]:
    """Analyze all imported modules in a Python file"""
    # Implementation code
    return {
        "file": target_file,
        "imports": [],  # List of imported modules
        "analysis": ""  # Import analysis result
    }

Adding Resource Endpoints

You can add resource endpoints to provide data:

@mcp.resource("python_stats://{directory}")
def get_stats(directory: str) -> Dict[str, Any]:
    """Get statistics of Python files in the specified directory"""
    from pathlib import Path
    stats = {
        "directory": directory,
        "file_count": 0,
        "total_lines": 0,
        "average_lines": 0
    }
    
    files = list(Path(directory).glob("**/*.py"))
    stats["file_count"] = len(files)
    
    if files:
        total_lines = 0
        for file in files:
            with open(file, "r") as f:
                total_lines += len(f.readlines())
        stats["total_lines"] = total_lines
        stats["average_lines"] = total_lines / len(files)
    
    return stats