Este servidor MCP (Protocolo de Contexto de Modelo) proporciona herramientas para extraer y analizar estructuras de código Python, centrándose en las relaciones de importación/exportación entre archivos. Se trata de una implementación ligera que no requiere un sistema de agente, lo que facilita su integración en cualquier aplicación Python.
Características
Descubrimiento de relaciones de código : Analice las relaciones de importación entre archivos de Python
Extracción de código inteligente : extraiga solo las secciones de código más relevantes para mantenerse dentro de los límites de tokens
Contexto de directorio : incluya archivos del mismo directorio para proporcionar un mejor contexto
Inclusión de documentación : incluya siempre archivos README.md (o variantes) para proporcionar documentación del proyecto
Formato compatible con LLM : formatee el código con metadatos adecuados para los modelos de lenguaje
Compatibilidad con el protocolo MCP : totalmente compatible con el estándar JSON-RPC del protocolo de contexto de modelo
Related MCP server: MCP Python SDK
La herramienta get_python_code
El servidor expone una potente herramienta de extracción de código que:
Analiza un archivo Python de destino y descubre todos los módulos, clases y funciones importados
Devuelve el código completo del archivo de destino.
Incluye código para todos los objetos referenciados desde otros archivos
Agrega archivos contextuales adicionales del mismo directorio
Respeta los límites de tokens para evitar saturar los modelos de lenguaje
Instalación
# 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
Variables de entorno
Cree un archivo .env basado en el .env.example proporcionado:
# Token limit for extraction
TOKEN_LIMIT=8000
Uso
Configuración para clientes MCP
Para configurar este servidor MCP para su uso en clientes compatibles con MCP (como Codeium Windsurf), agregue la siguiente configuración al archivo de configuración MCP de su cliente:
{
"mcpServers": {
"python-code-explorer": {
"command": "python",
"args": [
"/path/to/python-mcp-new/server.py"
],
"env": {
"TOKEN_LIMIT": "8000"
}
}
}
}
Reemplace /path/to/python-mcp-new/server.py con la ruta absoluta al archivo server.py en su sistema.
También puedes personalizar las variables de entorno:
Ejemplos de uso
Llamada de función directa
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']}")
Ejemplo de respuesta (llamada de función directa)
{
"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
}
Usando el protocolo MCP
Listado de herramientas disponibles
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))
Ejemplo de respuesta (herramientas/lista)
{
"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"]
}
}
]
}
}
Llamar a la herramienta 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))
Ejemplo de respuesta (herramientas/llamada)
{
"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
}
}
Manejo de errores
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))
Ejemplo de respuesta de error
{
"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
}
}
Pruebas
Ejecute las pruebas para verificar la funcionalidad:
python -m unittest discover tests
Componentes clave
agent.py : contiene la función get_python_code y controladores de protocolo MCP personalizados
code_grapher.py : Implementa la clase CodeGrapher para el análisis de código Python
server.py : Implementación completa del servidor MCP utilizando el SDK de Python de MCP
run_server.py : herramienta CLI para ejecutar el servidor MCP
ejemplos/ : Scripts de ejemplo que muestran cómo utilizar el servidor y el cliente MCP
pruebas/ : Casos de prueba completos para todas las funcionalidades
Detalles del formato de respuesta
La herramienta get_python_code devuelve un objeto JSON estructurado con los siguientes campos:
Campo | Tipo | Descripción |
target_file
| Objeto | Información sobre el archivo Python de destino |
referenced_files
| Formación | Lista de objetos importados por el archivo de destino |
additional_files
| Formación | Archivos de contexto adicionales del mismo directorio |
total_files
| Número | Número total de archivos incluidos en la respuesta |
token_count
| Número | Recuento aproximado de tokens en todo el código incluido |
token_limit
| Número | Límite máximo de tokens configurado para la extracción |
Objeto de archivo de destino
Campo | Tipo | Descripción |
file_path
| Cadena | Ruta relativa al archivo desde la raíz del repositorio |
code
| Cadena | Código fuente completo del archivo |
type
| Cadena | Siempre "apunta" |
docstring
| Cadena | Cadena de documentación a nivel de módulo, si está disponible |
Objeto de archivo referenciado
Campo | Tipo | Descripción |
file_path
| Cadena | Ruta relativa al archivo |
object_name
| Cadena | Nombre del objeto importado (clase, función, etc.) |
object_type
| Cadena | Tipo del objeto ("clase", "función", etc.) |
code
| Cadena | Código fuente del objeto específico |
docstring
| Cadena | Cadena de documentación del objeto si está disponible |
truncated
| Booleano | Si el código se truncó debido a límites de tokens |
Objeto de archivo adicional
Campo | Tipo | Descripción |
file_path
| Cadena | Ruta relativa al archivo |
code
| Cadena | Código fuente completo del archivo |
type
| Cadena | Tipo de relación (por ejemplo, "related_by_directory") |
docstring
| Cadena | Cadena de documentación a nivel de módulo, si está disponible |
Uso del servidor SDK de MCP
Este proyecto ahora incluye un servidor completo de Protocolo de Contexto de Modelo (MCP), desarrollado con el SDK oficial de MCP de Python . El servidor expone nuestra funcionalidad de extracción de código de forma estandarizada, compatible con cualquier cliente MCP, incluido Claude Desktop.
Iniciando el servidor
# 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
Uso del modo de desarrollo MCP
Con el SDK de MCP instalado, puede ejecutar el servidor en modo de desarrollo utilizando la CLI de MCP:
# Install the MCP CLI
pip install "mcp[cli]"
# Start the server in development mode with the Inspector UI
mcp dev server.py
Esto iniciará el Inspector MCP, una interfaz web para probar y depurar su servidor.
Integración de escritorio de Claude
Puede instalar el servidor en Claude Desktop para acceder a sus herramientas de exploración de código directamente desde Claude:
# Install the server in Claude Desktop
mcp install server.py
# With custom configuration
mcp install server.py --name "Python Code Explorer" -f .env
Implementación de servidor personalizado
Para implementaciones personalizadas, puede utilizar el servidor MCP directamente:
from server import mcp
# Configure the server
mcp.name = "Custom Code Explorer"
# Run the server
mcp.run()
Uso del cliente MCP
Puede usar el SDK de Python de MCP para conectarse al servidor mediante programación. Consulte el ejemplo proporcionado en 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()
Ejecute el ejemplo:
python examples/mcp_client_example.py [optional_target_file.py]
Agregar herramientas adicionales
Puede agregar herramientas adicionales al servidor MCP decorando funciones con el decorador @mcp.tool() en server.py :
@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()]
También puedes agregar puntos finales de recursos para proporcionar datos directamente:
@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
Integración del protocolo de contexto del modelo
Este proyecto adopta en su totalidad el estándar del Protocolo de Contexto de Modelo (MCP), proporcionando dos opciones de implementación:
Integración nativa de MCP : la implementación original en agent.py proporciona una interfaz JSON-RPC directa compatible con MCP.
Integración del SDK de MCP : la nueva implementación en server.py aprovecha el SDK oficial de Python de MCP para una experiencia más sólida y con más funciones.
Beneficios de la integración de MCP
Interfaz estandarizada : hace que sus herramientas estén disponibles para cualquier cliente compatible con MCP
Seguridad mejorada : modelo de permisos integrado y controles de recursos
Mejor integración LLM : integración perfecta con Claude Desktop y otras plataformas LLM
Experiencia de desarrollador mejorada : herramientas integrales como el Inspector MCP
Versión del protocolo MCP
Esta implementación es compatible con el protocolo MCP versión 0.7.0.
Para obtener más información sobre MCP, consulte la documentación oficial .
