Python Code Explorer

Python MCP Server for Code Graph Extraction

This MCP (Model Context Protocol) server provides tools for extracting and analyzing Python code structures, focusing on import/export relationships between files. This is a lightweight implementation that doesn't require an agent system, making it easy to integrate into any Python application.

Features

**Code Relationship Discovery**: Analyze import relationships between Python files

**Smart Code Extraction**: Extract only the most relevant code sections to stay within token limits

**Directory Context**: Include files from the same directory to provide better context

**Documentation Inclusion**: Always include README.md files (or variants) to provide project documentation

**LLM-Friendly Formatting**: Format code with proper metadata for language models

**MCP Protocol Support**: Fully compatible with the Model Context Protocol JSON-RPC standard

The `get_python_code` Tool

The server exposes a powerful code extraction tool that:

Analyzes a target Python file and discovers all imported modules, classes, and functions

Returns the complete code of the target file

Includes code for all referenced objects from other files

Adds additional contextual files from the same directory

Respects token limits to avoid overwhelming language models

Installation

Environment Variables

Create a `.env` file based on the provided `.env.example`:

Usage

Configuring for MCP Clients

To configure this MCP server for use in MCP-compatible clients (like Codeium Windsurf), add the following configuration to your client's MCP config file:

Replace `/path/to/python-mcp-new/server.py` with the absolute path to the server.py file on your system.

You can also customize the environment variables:

`TOKEN_LIMIT`: Maximum token limit for code extraction (default: 8000)

Usage Examples

Direct Function Call

Example Response (Direct Function Call)

Using the MCP Protocol

Listing Available Tools

Example Response (tools/list)

Calling get_python_code Tool

Example Response (tools/call)

Handling Errors

Example Error Response

Testing

Run the tests to verify functionality:

Key Components

**agent.py**: Contains the `get_python_code` function and custom MCP protocol handlers

**code_grapher.py**: Implements the `CodeGrapher` class for Python code analysis

**server.py**: Full MCP server implementation using the MCP Python SDK

**run_server.py**: CLI tool for running the MCP server

**examples/**: Example scripts showing how to use the MCP server and client

**tests/**: Comprehensive test cases for all functionality

Response Format Details

The `get_python_code` tool returns a structured JSON object with the following fields:

[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]

Target File Object

[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]

Referenced File Object

[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]

Additional File Object

[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]
[object Object]	[object Object]	[object Object]

Using the MCP SDK Server

This project now includes a full-featured Model Context Protocol (MCP) server built with the official [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk). The server exposes our code extraction functionality in a standardized way that can be used with any MCP client, including Claude Desktop.

Starting the Server

Using the MCP Development Mode

With the MCP SDK installed, you can run the server in development mode using the MCP CLI:

This will start the MCP Inspector, a web interface for testing and debugging your server.

Claude Desktop Integration

You can install the server into Claude Desktop to access your code exploration tools directly from Claude:

Custom Server Deployment

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

Using the MCP Client

You can use the MCP Python SDK to connect to the server programmatically. See the provided example in `examples/mcp_client_example.py`:

Run the example:

Adding Additional Tools

You can add additional tools to the MCP server by decorating functions with the `@mcp.tool()` decorator in `server.py`:

You can also add resource endpoints to provide data directly:

Model Context Protocol Integration

This project fully embraces the Model Context Protocol (MCP) standard, providing two implementation options:

**Native MCP Integration**: The original implementation in `agent.py` provides a direct JSON-RPC interface compatible with MCP.

**MCP SDK Integration**: The new implementation in `server.py` leverages the official MCP Python SDK for a more robust and feature-rich experience.

Benefits of MCP Integration

**Standardized Interface**: Makes your tools available to any MCP-compatible client

**Enhanced Security**: Built-in permissions model and resource controls

**Better LLM Integration**: Seamless integration with Claude Desktop and other LLM platforms

**Improved Developer Experience**: Comprehensive tooling like the MCP Inspector

MCP Protocol Version

This implementation supports MCP Protocol version 0.7.0.

For more information about MCP, refer to the [official documentation](https://modelcontextprotocol.io).