Python MCP-сервер

Сервер Python MCP для извлечения графа кода

Этот сервер MCP (Model Context Protocol) предоставляет инструменты для извлечения и анализа структур кода Python, фокусируясь на отношениях импорта/экспорта между файлами. Это легкая реализация, не требующая агентской системы, что позволяет легко интегрировать ее в любое приложение Python.

Функции

Обнаружение взаимосвязей кода : анализ взаимосвязей импорта между файлами Python.
Интеллектуальное извлечение кода : извлекайте только самые важные разделы кода, чтобы не выходить за рамки ограничений по токенам.
Контекст каталога : включение файлов из того же каталога для предоставления лучшего контекста.
Включение документации : всегда включайте файлы README.md (или их варианты) для предоставления проектной документации.
Форматирование, удобное для LLM : форматирование кода с использованием соответствующих метаданных для языковых моделей.
Поддержка протокола MCP : полная совместимость со стандартом Model Context Protocol JSON-RPC

Инструмент `get_python_code`

Сервер предоставляет мощный инструмент извлечения кода, который:

Анализирует целевой файл Python и обнаруживает все импортированные модули, классы и функции.
Возвращает полный код целевого файла
Включает код для всех указанных объектов из других файлов.
Добавляет дополнительные контекстные файлы из того же каталога
Соблюдает ограничения токенов, чтобы избежать перегрузки языковых моделей

Установка

# 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

Переменные среды

Создайте файл .env на основе предоставленного .env.example :

# Token limit for extraction
TOKEN_LIMIT=8000

Использование

Настройка для клиентов MCP

Чтобы настроить этот сервер MCP для использования в клиентах, совместимых с MCP (например, Codeium Windsurf), добавьте следующую конфигурацию в файл конфигурации MCP вашего клиента:

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

Замените /path/to/python-mcp-new/server.py на абсолютный путь к файлу server.py в вашей системе.

Вы также можете настроить переменные среды:

TOKEN_LIMIT : Максимальный лимит токенов для извлечения кода (по умолчанию: 8000)

Примеры использования

Прямой вызов функции

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']}")

Пример ответа (прямой вызов функции)

{
    "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
}

Использование протокола MCP

Список доступных инструментов

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))

Пример ответа (инструменты/список)

{
  "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"]
        }
      }
    ]
  }
}

Вызов инструмента 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))

Пример ответа (инструменты/звонок)

{
  "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
  }
}

Обработка ошибок

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))

Пример ответа об ошибке

{
  "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
  }
}

Тестирование

Запустите тесты для проверки функциональности:

python -m unittest discover tests

Ключевые компоненты

agent.py : содержит функцию get_python_code и пользовательские обработчики протокола MCP
code_grapher.py : реализует класс CodeGrapher для анализа кода Python
server.py : Полная реализация сервера MCP с использованием MCP Python SDK
run_server.py : CLI-инструмент для запуска сервера MCP
examples/ : Примеры скриптов, показывающие, как использовать сервер и клиент MCP
tests/ : Комплексные тестовые случаи для всех функций

Подробности формата ответа

Инструмент get_python_code возвращает структурированный объект JSON со следующими полями:

Поле	Тип	Описание
`target_file`	Объект	Информация о целевом файле Python
`referenced_files`	Множество	Список объектов, импортированных целевым файлом
`additional_files`	Множество	Дополнительные файлы контекста из того же каталога
`total_files`	Число	Общее количество файлов, включенных в ответ
`token_count`	Число	Приблизительное количество токенов во всем включенном коде
`token_limit`	Число	Максимальный лимит токенов, настроенный для извлечения

Целевой объект файла

Поле	Тип	Описание
`file_path`	Нить	Относительный путь к файлу от корня репозитория
`code`	Нить	Полный исходный код файла
`type`	Нить	Всегда «цель»
`docstring`	Нить	Строка документации на уровне модуля, если доступна

Ссылочный объект файла

Поле	Тип	Описание
`file_path`	Нить	Относительный путь к файлу
`object_name`	Нить	Имя импортируемого объекта (класс, функция и т. д.)
`object_type`	Нить	Тип объекта («класс», «функция» и т. д.)
`code`	Нить	Исходный код конкретного объекта
`docstring`	Нить	Строка документации объекта, если доступна
`truncated`	Булев	Был ли код усечен из-за ограничений токенов

Дополнительный файловый объект

Поле	Тип	Описание
`file_path`	Нить	Относительный путь к файлу
`code`	Нить	Полный исходный код файла
`type`	Нить	Тип связи (например, «related_by_directory»)
`docstring`	Нить	Строка документации на уровне модуля, если доступна

Использование сервера MCP SDK

Этот проект теперь включает полнофункциональный сервер Model Context Protocol (MCP), созданный с официальным Python MCP SDK . Сервер предоставляет нашу функциональность извлечения кода стандартизированным способом, который может использоваться с любым клиентом MCP, включая Claude Desktop.

Запуск сервера

# 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

Использование режима разработки MCP

Установив MCP SDK, вы можете запустить сервер в режиме разработки с помощью MCP CLI:

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

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

Это запустит MCP Inspector — веб-интерфейс для тестирования и отладки вашего сервера.

Интеграция рабочего стола Клода

Вы можете установить сервер в Claude Desktop, чтобы получить доступ к инструментам исследования кода непосредственно из Claude:

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

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

Развертывание индивидуального сервера

Для пользовательских развертываний вы можете использовать сервер MCP напрямую:

from server import mcp

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

# Run the server
mcp.run()

Использование MCP-клиента

Вы можете использовать MCP Python SDK для программного подключения к серверу. Смотрите предоставленный пример в 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()

Запустите пример:

python examples/mcp_client_example.py [optional_target_file.py]

Добавление дополнительных инструментов

Вы можете добавить дополнительные инструменты на сервер MCP, декорировав функции с помощью декоратора @mcp.tool() в 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()]

Вы также можете добавить конечные точки ресурсов для предоставления данных напрямую:

@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

Интеграция протокола контекста модели

Этот проект полностью соответствует стандарту Model Context Protocol (MCP) и предлагает два варианта реализации:

Собственная интеграция MCP : исходная реализация в agent.py обеспечивает прямой интерфейс JSON-RPC, совместимый с MCP.
Интеграция MCP SDK : новая реализация в server.py использует официальный MCP Python SDK для более надежного и многофункционального опыта.

Преимущества интеграции MCP

Стандартизированный интерфейс : делает ваши инструменты доступными для любого MCP-совместимого клиента.
Повышенная безопасность : встроенная модель разрешений и контроль ресурсов
Лучшая интеграция LLM : бесшовная интеграция с Claude Desktop и другими платформами LLM
Улучшенный опыт разработчика : комплексный инструментарий, такой как MCP Inspector

Версия протокола MCP

Данная реализация поддерживает протокол MCP версии 0.7.0.

Более подробную информацию о MCP можно найти в официальной документации .

Integrations