MCP Python Toolbox

# MCP Python Toolbox A Model Context Protocol (MCP) server that provides a comprehensive set of tools for Python development, enabling AI assistants like Claude to effectively work with Python code and projects. ## Overview MCP Python Toolbox implements a Model Context Protocol server that gives Claude the ability to perform Python development tasks through a standardized interface. It enables Claude to: - Read, write, and manage files within a workspace - Analyze, format, and lint Python code - Manage virtual environments and dependencies - Execute Python code safely ## Features ### File Operations (`FileOperations`) - Safe file operations within a workspace directory - Path validation to prevent unauthorized access outside workspace - Read and write files with line-specific operations - Create and delete files and directories - List directory contents with detailed metadata (size, type, modification time) - Automatic parent directory creation when writing files ### Code Analysis (`CodeAnalyzer`) - Parse and analyze Python code structure using AST - Extract detailed information about: - Import statements and their aliases - Function definitions with arguments and decorators - Class definitions with base classes and methods - Global variable assignments - Format code using: - Black (default) - PEP8 (using autopep8) - Comprehensive code linting using Pylint with detailed reports ### Project Management (`ProjectManager`) - Create and manage virtual environments with pip support - Flexible dependency management: - Install from requirements.txt - Install from pyproject.toml - Support for specific package versions - Advanced dependency handling: - Check for version conflicts between packages - List all installed packages with versions - Update packages to specific versions - Generate requirements.txt from current environment ### Code Execution (`CodeExecutor`) - Execute Python code in a controlled environment - Uses project's virtual environment for consistent dependencies - Temporary file management for code execution - Capture stdout, stderr, and exit codes - Support for custom working directories ## Installation 1. Clone the repository: ```bash git clone https://github.com/gianlucamazza/mcp_python_toolbox.git cd mcp_python_toolbox ``` 2. Create and activate a virtual environment: ```bash python -m venv .venv source .venv/bin/activate # Linux/Mac # or .venv\Scripts\activate # Windows ``` 3. Install the package in development mode: ```bash pip install -e ".[dev]" ``` ## Usage ### Running as a CLI Tool The simplest way to start the server is using the CLI: ```bash # Start with current directory as workspace python -m mcp_python_toolbox # Or specify a workspace directory python -m mcp_python_toolbox --workspace /path/to/your/project ``` ### Setting Up with Claude Desktop Claude Desktop can automatically launch and manage the MCP Python Toolbox server. Here's how to configure it: 1. Install and set up the MCP Python Toolbox as described above 2. Add a configuration entry for the Python Toolbox in Claude Desktop's MCP tools configuration: ```json "python-toolbox": { "command": "/Users/username/path/to/mcp_python_toolbox/.venv/bin/python", "args": [ "-m", "mcp_python_toolbox", "--workspace", "/Users/username/path/to/workspace" ], "env": { "PYTHONPATH": "/Users/username/path/to/mcp_python_toolbox/src", "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin", "VIRTUAL_ENV": "/Users/username/path/to/mcp_python_toolbox/.venv", "PYTHONHOME": "" } } ``` 3. Customize the paths to match your environment 4. Claude Desktop will automatically start the MCP server when needed 5. Claude will now have access to Python development tools through the MCP interface ### Programmatic Usage ```python from mcp_python_toolbox import PythonToolboxServer server = PythonToolboxServer(workspace_root="/path/to/your/project") server.setup() server.run() ``` ### Core Module Examples #### File Operations ```python from mcp_python_toolbox.core import FileOperations file_ops = FileOperations(workspace_root="/path/to/project") # Read file contents content = file_ops.read_file("src/example.py") # Read specific lines lines = file_ops.read_file("src/example.py", start_line=10, end_line=20) # Write to file file_ops.write_file("output.txt", "Hello, World!") # Append to file file_ops.write_file("log.txt", "New entry\n", mode='a') # List directory contents contents = file_ops.list_directory("src") for item in contents: print(f"{item['name']} - {item['type']} - {item['size']} bytes") ``` #### Code Analysis ```python from mcp_python_toolbox.core import CodeAnalyzer analyzer = CodeAnalyzer(workspace_root="/path/to/project") # Analyze Python file structure analysis = analyzer.parse_python_file("src/example.py") print(f"Found {len(analysis['functions'])} functions") print(f"Found {len(analysis['classes'])} classes") # Format code formatted = analyzer.format_code(code, style='black') # Lint code issues = analyzer.lint_code("src/example.py") for issue in issues: print(f"Line {issue['line']}: {issue['message']}") ``` #### Project Management ```python from mcp_python_toolbox.core import ProjectManager pm = ProjectManager(workspace_root="/path/to/project") # Create virtual environment pm.create_virtual_environment() # Install dependencies pm.install_dependencies() # from requirements.txt or pyproject.toml pm.install_dependencies("requirements-dev.txt") # from specific file # Check for conflicts conflicts = pm.check_dependency_conflicts() if conflicts: print("Found dependency conflicts:") for conflict in conflicts: print(f"{conflict['package']} requires {conflict['requires']}") # Update packages pm.update_package("requests") # to latest pm.update_package("flask", version="2.0.0") # to specific version ``` #### Code Execution ```python from mcp_python_toolbox.core import CodeExecutor executor = CodeExecutor(workspace_root="/path/to/project") code = ''' def greet(name): return f"Hello, {name}!" print(greet("World")) ''' result = executor.execute_code(code) print(f"Output: {result['stdout']}") print(f"Errors: {result['stderr']}") print(f"Exit code: {result['exit_code']}") ``` ## Development ### Running Tests ```bash pytest ``` ### Type Checking ```bash mypy src/mcp_python_toolbox ``` ### Linting ```bash pylint src/mcp_python_toolbox ``` ### Formatting ```bash black src/mcp_python_toolbox ``` ## Contributing 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Acknowledgments - Implements the [Model Context Protocol](https://github.com/modelcontextprotocol/servers) specification - Built with modern Python development tools and best practices - Uses industry-standard formatting (Black) and linting (Pylint) tools