Сервер Python MCP для извлечения графа кода
Этот сервер MCP (Model Context Protocol) предоставляет инструменты для извлечения и анализа структур кода Python, фокусируясь на отношениях импорта/экспорта между файлами. Это легкая реализация, не требующая агентской системы, что позволяет легко интегрировать ее в любое приложение Python.
Функции
Обнаружение взаимосвязей кода : анализ взаимосвязей импорта между файлами Python.
Интеллектуальное извлечение кода : извлекайте только самые важные разделы кода, чтобы не выходить за рамки ограничений по токенам.
Контекст каталога : включение файлов из того же каталога для предоставления лучшего контекста.
Включение документации : всегда включайте файлы README.md (или их варианты) для предоставления проектной документации.
Форматирование, удобное для LLM : форматирование кода с использованием соответствующих метаданных для языковых моделей.
Поддержка протокола MCP : полная совместимость со стандартом Model Context Protocol JSON-RPC
Related MCP server: MCP Python SDK
Инструмент 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 в вашей системе.
Вы также можете настроить переменные среды:
Примеры использования
Прямой вызов функции
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 можно найти в официальной документации .
