코드 그래프 추출을 위한 Python MCP 서버
이 MCP(Model Context Protocol) 서버는 파일 간 가져오기/내보내기 관계에 중점을 두고 Python 코드 구조를 추출하고 분석하는 도구를 제공합니다. 에이전트 시스템이 필요 없는 가벼운 구현 방식으로 모든 Python 애플리케이션에 쉽게 통합할 수 있습니다.
특징
- 코드 관계 검색 : Python 파일 간의 가져오기 관계 분석
- 스마트 코드 추출 : 토큰 한도 내에 있도록 가장 관련성 있는 코드 섹션만 추출합니다.
- 디렉토리 컨텍스트 : 더 나은 컨텍스트를 제공하기 위해 동일한 디렉토리의 파일을 포함합니다.
- 문서 포함 : 프로젝트 문서를 제공하기 위해 항상 README.md 파일(또는 변형)을 포함합니다.
- LLM 친화적 포맷팅 : 언어 모델에 대한 적절한 메타데이터로 코드 포맷팅
- MCP 프로토콜 지원 : Model Context Protocol JSON-RPC 표준과 완벽하게 호환됩니다.
get_python_code 도구
이 서버는 다음과 같은 강력한 코드 추출 도구를 제공합니다.
- 대상 Python 파일을 분석하고 가져온 모든 모듈, 클래스 및 함수를 검색합니다.
- 대상 파일의 전체 코드를 반환합니다.
- 다른 파일의 모든 참조된 개체에 대한 코드를 포함합니다.
- 동일한 디렉토리에서 추가 컨텍스트 파일을 추가합니다.
- 과도한 언어 모델을 방지하기 위해 토큰 제한을 존중합니다.
설치
지엑스피1
환경 변수
제공된 .env.example 을 기반으로 .env 파일을 만듭니다.
# Token limit for extraction
TOKEN_LIMIT=8000
용법
MCP 클라이언트 구성
Codeium Windsurf와 같은 MCP 호환 클라이언트에서 이 MCP 서버를 사용하도록 구성하려면 클라이언트의 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 : Python 코드 분석을 위한
CodeGrapher 클래스를 구현합니다. - server.py : MCP Python SDK를 사용한 전체 MCP 서버 구현
- run_server.py : MCP 서버를 실행하기 위한 CLI 도구
- 예제/ : MCP 서버와 클라이언트를 사용하는 방법을 보여주는 예제 스크립트
- tests/ : 모든 기능에 대한 포괄적인 테스트 케이스
응답 형식 세부 정보
get_python_code 도구는 다음 필드가 포함된 구조화된 JSON 객체를 반환합니다.
| 필드 | 유형 | 설명 |
|---|
target_file | 물체 | 대상 Python 파일에 대한 정보 |
referenced_files | 정렬 | 대상 파일에 의해 가져온 객체 목록 |
additional_files | 정렬 | 동일한 디렉토리의 추가 컨텍스트 파일 |
total_files | 숫자 | 응답에 포함된 총 파일 수 |
token_count | 숫자 | 포함된 모든 코드의 토큰의 대략적인 개수 |
token_limit | 숫자 | 추출을 위해 구성된 최대 토큰 한도 |
대상 파일 객체
| 필드 | 유형 | 설명 |
|---|
file_path | 끈 | 저장소 루트에서 파일에 대한 상대 경로 |
code | 끈 | 파일의 전체 소스 코드 |
type | 끈 | 항상 "타겟" |
docstring | 끈 | 사용 가능한 경우 모듈 수준 docstring |
참조된 파일 객체
| 필드 | 유형 | 설명 |
|---|
file_path | 끈 | 파일에 대한 상대 경로 |
object_name | 끈 | 가져온 객체의 이름(클래스, 함수 등) |
object_type | 끈 | 객체의 유형("클래스", "함수" 등) |
code | 끈 | 특정 객체의 소스 코드 |
docstring | 끈 | 사용 가능한 경우 객체의 Docstring |
truncated | 부울 | 토큰 제한으로 인해 코드가 잘렸는지 여부 |
추가 파일 객체
| 필드 | 유형 | 설명 |
|---|
file_path | 끈 | 파일에 대한 상대 경로 |
code | 끈 | 파일의 전체 소스 코드 |
type | 끈 | 관계 유형(예: "related_by_directory") |
docstring | 끈 | 사용 가능한 경우 모듈 수준 docstring |
MCP SDK 서버 사용
이 프로젝트에는 공식 Python MCP SDK를 기반으로 구축된 모든 기능을 갖춘 MCP(Model Context Protocol) 서버가 포함됩니다. 이 서버는 Claude Desktop을 포함한 모든 MCP 클라이언트에서 사용할 수 있는 표준화된 방식으로 코드 추출 기능을 제공합니다.
서버 시작
# 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 데스크톱 통합
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]
추가 도구 추가
server.py 에서 @mcp.tool() 데코레이터로 함수를 데코레이션하여 MCP 서버에 추가 도구를 추가할 수 있습니다.
@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
모델 컨텍스트 프로토콜 통합
이 프로젝트는 MCP(Model Context Protocol) 표준을 완전히 수용하여 두 가지 구현 옵션을 제공합니다.
- 기본 MCP 통합 :
agent.py 의 원래 구현은 MCP와 호환되는 직접적인 JSON-RPC 인터페이스를 제공합니다. - MCP SDK 통합 :
server.py 의 새로운 구현은 보다 강력하고 기능이 풍부한 환경을 위해 공식 MCP Python SDK를 활용합니다.
MCP 통합의 이점
- 표준화된 인터페이스 : 모든 MCP 호환 클라이언트에서 도구를 사용할 수 있습니다.
- 강화된 보안 : 내장된 권한 모델 및 리소스 제어
- 더 나은 LLM 통합 : Claude Desktop 및 기타 LLM 플랫폼과의 원활한 통합
- 향상된 개발자 경험 : MCP Inspector와 같은 포괄적인 툴링
MCP 프로토콜 버전
이 구현은 MCP 프로토콜 버전 0.7.0을 지원합니다.
MCP에 대한 자세한 내용은 공식 문서를 참조하세요.