Python MCP-Server

Python MCP-Server zur Code-Graph-Extraktion

Dieser MCP-Server (Model Context Protocol) bietet Tools zum Extrahieren und Analysieren von Python-Codestrukturen mit Schwerpunkt auf Import-/Exportbeziehungen zwischen Dateien. Es handelt sich um eine leichtgewichtige Implementierung, die kein Agentensystem benötigt und sich daher problemlos in jede Python-Anwendung integrieren lässt.

Merkmale

Code Relationship Discovery : Analysieren Sie Importbeziehungen zwischen Python-Dateien
Intelligente Code-Extraktion : Extrahieren Sie nur die relevantesten Codeabschnitte, um innerhalb der Token-Grenzen zu bleiben
Verzeichniskontext : Fügen Sie Dateien aus demselben Verzeichnis ein, um einen besseren Kontext bereitzustellen
Einbeziehung der Dokumentation : Fügen Sie immer README.md-Dateien (oder Varianten) ein, um die Projektdokumentation bereitzustellen
LLM-freundliche Formatierung : Formatieren Sie Code mit den richtigen Metadaten für Sprachmodelle
MCP-Protokollunterstützung : Vollständig kompatibel mit dem Model Context Protocol JSON-RPC-Standard

Das `get_python_code` Tool

Der Server stellt ein leistungsstarkes Tool zur Codeextraktion bereit, das:

Analysiert eine Python-Zieldatei und erkennt alle importierten Module, Klassen und Funktionen
Gibt den vollständigen Code der Zieldatei zurück
Enthält Code für alle referenzierten Objekte aus anderen Dateien
Fügt zusätzliche Kontextdateien aus demselben Verzeichnis hinzu
Beachtet Token-Grenzen, um eine Überlastung der Sprachmodelle zu vermeiden

Installation

# Clone the repository
git clone https://github.com/yourusername/python-mcp-new.git
cd python-mcp-new

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Umgebungsvariablen

Erstellen Sie eine .env Datei basierend auf dem bereitgestellten .env.example :

# Token limit for extraction
TOKEN_LIMIT=8000

Verwendung

Konfigurieren für MCP-Clients

Um diesen MCP-Server für die Verwendung in MCP-kompatiblen Clients (wie Codeium Windsurf) zu konfigurieren, fügen Sie der MCP-Konfigurationsdatei Ihres Clients die folgende Konfiguration hinzu:

{
  "mcpServers": {
    "python-code-explorer": {
      "command": "python",
      "args": [
        "/path/to/python-mcp-new/server.py"
      ],
      "env": {
        "TOKEN_LIMIT": "8000"
      }
    }
  }
}

Ersetzen Sie /path/to/python-mcp-new/server.py durch den absoluten Pfad zur Datei server.py auf Ihrem System.

Sie können die Umgebungsvariablen auch anpassen:

TOKEN_LIMIT : Maximales Token-Limit für die Codeextraktion (Standard: 8000)

Anwendungsbeispiele

Direkter Funktionsaufruf

from agent import get_python_code

# Get Python code structure for a specific file
result = get_python_code(
    target_file="/home/user/project/main.py",
    root_repo_path="/home/user/project"  # Optional, defaults to target file directory
)

# Process the result
target_file = result["target_file"]
print(f"Main file: {target_file['file_path']}")
print(f"Docstring: {target_file['docstring']}")

# Display related files
for ref_file in result["referenced_files"]:
    print(f"Related file: {ref_file['file_path']}")
    print(f"Object: {ref_file['object_name']}")
    print(f"Type: {ref_file['object_type']}")

# See if we're close to the token limit
print(f"Token usage: {result['token_count']}/{result['token_limit']}")

Beispielantwort (direkter Funktionsaufruf)

{
    "target_file": {
        "file_path": "main.py",
        "code": "import os\nimport sys\nfrom utils.helpers import format_output\n\ndef main():\n    args = sys.argv[1:]\n    if not args:\n        print('No arguments provided')\n        return\n    \n    result = format_output(args[0])\n    print(result)\n\nif __name__ == '__main__':\n    main()",
        "type": "target",
        "docstring": ""
    },
    "referenced_files": [
        {
            "file_path": "utils/helpers.py",
            "object_name": "format_output",
            "object_type": "function",
            "code": "def format_output(text):\n    \"\"\"Format the input text for display.\"\"\"\n    if not text:\n        return ''\n    return f'Output: {text.upper()}'\n",
            "docstring": "Format the input text for display.",
            "truncated": false
        }
    ],
    "additional_files": [
        {
            "file_path": "config.py",
            "code": "# Configuration settings\n\nDEBUG = True\nVERSION = '1.0.0'\nMAX_RETRIES = 3\n",
            "type": "related_by_directory",
            "docstring": "Configuration settings for the application."
        }
    ],
    "total_files": 3,
    "token_count": 450,
    "token_limit": 8000
}

Verwenden des MCP-Protokolls

Auflisten der verfügbaren Tools

from agent import handle_mcp_request
import json

# List available tools
list_request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
}

response = handle_mcp_request(list_request)
print(json.dumps(response, indent=2))

Beispielantwort (Tools/Liste)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_python_code",
        "description": "Return the code of a target Python file and related files based on import/export proximity.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "target_file": {
              "type": "string",
              "description": "Path to the Python file to analyze."
            },
            "root_repo_path": {
              "type": "string",
              "description": "Root directory of the repository. If not provided, the directory of the target file will be used."
            }
          },
          "required": ["target_file"]
        }
      }
    ]
  }
}

Aufrufen des Tools get_python_code

from agent import handle_mcp_request
import json

# Call the get_python_code tool
tool_request = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "get_python_code",
        "arguments": {
            "target_file": "/home/user/project/main.py",
            "root_repo_path": "/home/user/project"  # Optional
        }
    }
}

response = handle_mcp_request(tool_request)
print(json.dumps(response, indent=2))

Beispielantwort (Tools/Aufruf)

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Python code analysis for /home/user/project/main.py"
      },
      {
        "type": "resource",
        "resource": {
          "uri": "resource://python-code/main.py",
          "mimeType": "application/json",
          "data": {
            "target_file": {
              "file_path": "main.py",
              "code": "import os\nimport sys\nfrom utils.helpers import format_output\n\ndef main():\n    args = sys.argv[1:]\n    if not args:\n        print('No arguments provided')\n        return\n    \n    result = format_output(args[0])\n    print(result)\n\nif __name__ == '__main__':\n    main()",
              "type": "target",
              "docstring": ""
            },
            "referenced_files": [
              {
                "file_path": "utils/helpers.py",
                "object_name": "format_output",
                "object_type": "function",
                "code": "def format_output(text):\n    \"\"\"Format the input text for display.\"\"\"\n    if not text:\n        return ''\n    return f'Output: {text.upper()}'\n",
                "docstring": "Format the input text for display.",
                "truncated": false
              }
            ],
            "additional_files": [
              {
                "file_path": "config.py",
                "code": "# Configuration settings\n\nDEBUG = True\nVERSION = '1.0.0'\nMAX_RETRIES = 3\n",
                "type": "related_by_directory",
                "docstring": "Configuration settings for the application."
              }
            ],
            "total_files": 3,
            "token_count": 450,
            "token_limit": 8000
          }
        }
      }
    ],
    "isError": false
  }
}

Fehlerbehandlung

from agent import handle_mcp_request

# Call with invalid file path
faulty_request = {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "get_python_code",
        "arguments": {
            "target_file": "/path/to/nonexistent.py"
        }
    }
}

response = handle_mcp_request(faulty_request)
print(json.dumps(response, indent=2))

Beispiel für eine Fehlerantwort

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Error processing Python code: No such file or directory: '/path/to/nonexistent.py'"
      }
    ],
    "isError": true
  }
}

Testen

Führen Sie die Tests aus, um die Funktionalität zu überprüfen:

python -m unittest discover tests

Schlüsselkomponenten

agent.py : Enthält die Funktion get_python_code und benutzerdefinierte MCP-Protokollhandler
code_grapher.py : Implementiert die CodeGrapher Klasse für die Python-Codeanalyse
server.py : Vollständige MCP-Serverimplementierung mit dem MCP Python SDK
run_server.py : CLI-Tool zum Ausführen des MCP-Servers
Beispiele/ : Beispielskripte, die die Verwendung des MCP-Servers und -Clients zeigen
tests/ : Umfassende Testfälle für alle Funktionen

Details zum Antwortformat

Das Tool get_python_code gibt ein strukturiertes JSON-Objekt mit den folgenden Feldern zurück:

Feld	Typ	Beschreibung
`target_file`	Objekt	Informationen zur Ziel-Python-Datei
`referenced_files`	Array	Liste der von der Zieldatei importierten Objekte
`additional_files`	Array	Zusätzliche Kontextdateien aus demselben Verzeichnis
`total_files`	Nummer	Gesamtzahl der in der Antwort enthaltenen Dateien
`token_count`	Nummer	Ungefähre Anzahl der Token im gesamten enthaltenen Code
`token_limit`	Nummer	Maximales Token-Limit für die Extraktion konfiguriert

Zieldateiobjekt

Feld	Typ	Beschreibung
`file_path`	Zeichenfolge	Relativer Pfad zur Datei vom Repository-Stamm
`code`	Zeichenfolge	Vollständiger Quellcode der Datei
`type`	Zeichenfolge	Immer "Ziel"
`docstring`	Zeichenfolge	Docstring auf Modulebene, falls verfügbar

Referenziertes Dateiobjekt

Feld	Typ	Beschreibung
`file_path`	Zeichenfolge	Relativer Pfad zur Datei
`object_name`	Zeichenfolge	Name des importierten Objekts (Klasse, Funktion usw.)
`object_type`	Zeichenfolge	Typ des Objekts („Klasse“, „Funktion“ usw.)
`code`	Zeichenfolge	Quellcode des spezifischen Objekts
`docstring`	Zeichenfolge	Docstring des Objekts, falls verfügbar
`truncated`	Boolesch	Ob der Code aufgrund von Token-Limits gekürzt wurde

Zusätzliches Dateiobjekt

Feld	Typ	Beschreibung
`file_path`	Zeichenfolge	Relativer Pfad zur Datei
`code`	Zeichenfolge	Vollständiger Quellcode der Datei
`type`	Zeichenfolge	Art der Beziehung (z. B. „related_by_directory“)
`docstring`	Zeichenfolge	Docstring auf Modulebene, falls verfügbar

Verwenden des MCP SDK-Servers

Dieses Projekt umfasst nun einen voll funktionsfähigen Model Context Protocol (MCP)-Server, der mit dem offiziellen Python MCP SDK erstellt wurde. Der Server stellt unsere Codeextraktionsfunktionalität standardisiert bereit und kann mit jedem MCP-Client, einschließlich Claude Desktop, verwendet werden.

Starten des Servers

# Start the server with default settings
python run_server.py

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

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

Verwenden des MCP-Entwicklungsmodus

Wenn das MCP SDK installiert ist, können Sie den Server mithilfe der MCP-CLI im Entwicklungsmodus ausführen:

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

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

Dadurch wird der MCP Inspector gestartet, eine Weboberfläche zum Testen und Debuggen Ihres Servers.

Claude Desktop Integration

Sie können den Server in Claude Desktop installieren, um direkt von Claude aus auf Ihre Code-Explorationstools zuzugreifen:

# Install the server in Claude Desktop
mcp install server.py

# With custom configuration
mcp install server.py --name "Python Code Explorer" -f .env

Benutzerdefinierte Serverbereitstellung

Für benutzerdefinierte Bereitstellungen können Sie den MCP-Server direkt verwenden:

from server import mcp

# Configure the server
mcp.name = "Custom Code Explorer"

# Run the server
mcp.run()

Verwenden des MCP-Clients

Sie können das MCP Python SDK verwenden, um programmgesteuert eine Verbindung zum Server herzustellen. Siehe das bereitgestellte Beispiel 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 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")

# Clean up
client.shutdown()

Führen Sie das Beispiel aus:

python examples/mcp_client_example.py [optional_target_file.py]

Hinzufügen zusätzlicher Tools

Sie können dem MCP-Server zusätzliche Tools hinzufügen, indem Sie Funktionen mit dem Dekorator @mcp.tool() in server.py dekorieren:

@mcp.tool()
def analyze_imports(target_file: str) -> Dict[str, Any]:
    """Analyze all imports in a Python file."""
    # Implementation code here
    return {
        "file": target_file,
        "imports": [],  # List of imports found
        "analysis": ""  # Analysis of the imports
    }
    
@mcp.tool()
def find_python_files(directory: str, pattern: str = "*.py") -> list[str]:
    """Find Python files matching a pattern in a directory."""
    from pathlib import Path
    return [str(p) for p in Path(directory).glob(pattern) if p.is_file()]

Sie können auch Ressourcenendpunkte hinzufügen, um Daten direkt bereitzustellen:

@mcp.resource("python_stats://{directory}")
def get_stats(directory: str) -> Dict[str, Any]:
    """Get statistics about Python files in a 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

Modellkontextprotokollintegration

Dieses Projekt berücksichtigt den Model Context Protocol (MCP)-Standard vollständig und bietet zwei Implementierungsoptionen:

Native MCP-Integration : Die ursprüngliche Implementierung in agent.py bietet eine direkte JSON-RPC-Schnittstelle, die mit MCP kompatibel ist.
MCP SDK-Integration : Die neue Implementierung in server.py nutzt das offizielle MCP Python SDK für eine robustere und funktionsreichere Erfahrung.

Vorteile der MCP-Integration

Standardisierte Schnittstelle : Macht Ihre Tools jedem MCP-kompatiblen Client verfügbar
Verbesserte Sicherheit : Integriertes Berechtigungsmodell und Ressourcenkontrollen
Bessere LLM-Integration : Nahtlose Integration mit Claude Desktop und anderen LLM-Plattformen
Verbesserte Entwicklererfahrung : Umfassende Tools wie der MCP Inspector

MCP-Protokollversion

Diese Implementierung unterstützt das MCP-Protokoll Version 0.7.0.

Weitere Informationen zu MCP finden Sie in der offiziellen Dokumentation .

Integrations