Servidor MCP de Python para la extracción de gráficos de código

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

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:

TOKEN_LIMIT : Límite máximo de tokens para la extracción de código (predeterminado: 8000)

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 .

Python MCP Server

Integrations

Servidor MCP de Python para la extracción de gráficos de código

Características

La herramienta `get_python_code`

Instalación

Variables de entorno

Uso

Configuración para clientes MCP

Ejemplos de uso

Llamada de función directa

Ejemplo de respuesta (llamada de función directa)

Usando el protocolo MCP

Listado de herramientas disponibles

Ejemplo de respuesta (herramientas/lista)

Llamar a la herramienta get_python_code

Ejemplo de respuesta (herramientas/llamada)

Manejo de errores

Ejemplo de respuesta de error

Pruebas

Componentes clave

Detalles del formato de respuesta

Objeto de archivo de destino

Objeto de archivo referenciado

Objeto de archivo adicional

Uso del servidor SDK de MCP

Iniciando el servidor

Uso del modo de desarrollo MCP

Integración de escritorio de Claude

Implementación de servidor personalizado

Uso del cliente MCP

Agregar herramientas adicionales

Integración del protocolo de contexto del modelo

Beneficios de la integración de MCP

Versión del protocolo MCP

Related Resources

Appeared in Searches

Integrations

Servidor MCP de Python para la extracción de gráficos de código

Características

La herramienta get_python_code

Instalación

Variables de entorno

Uso

Configuración para clientes MCP

Ejemplos de uso

Llamada de función directa

Ejemplo de respuesta (llamada de función directa)

Usando el protocolo MCP

Listado de herramientas disponibles

Ejemplo de respuesta (herramientas/lista)

Llamar a la herramienta get_python_code

Ejemplo de respuesta (herramientas/llamada)

Manejo de errores

Ejemplo de respuesta de error

Pruebas

Componentes clave

Detalles del formato de respuesta

Objeto de archivo de destino

Objeto de archivo referenciado

Objeto de archivo adicional

Uso del servidor SDK de MCP

Iniciando el servidor

Uso del modo de desarrollo MCP

Integración de escritorio de Claude

Implementación de servidor personalizado

Uso del cliente MCP

Agregar herramientas adicionales

Integración del protocolo de contexto del modelo

Beneficios de la integración de MCP

Versión del protocolo MCP

Related Resources

Appeared in Searches

La herramienta `get_python_code`