mcp-python/README.md

# MCP Python Project Manager Server

A Model Context Protocol (MCP) server for managing and debugging Python projects on Windows 11.

## 🚀 Features

### Project Management
- **Project Info**: Get comprehensive information about Python projects including structure, dependencies, and environment
- **File Operations**: List, read, and analyze project files with filtering options
- **Directory Tree**: Visualize project structure with configurable depth

### Execution & Debugging
- **Run Scripts**: Execute Python scripts with custom arguments and environment variables
- **Debug Info**: Get information about running Python processes and scripts
- **Environment Details**: Inspect Python interpreter, packages, and sys.path

### Package Management
- **Install Packages**: Install packages via pip with requirements file support
- **List Packages**: View installed packages in JSON or text format
- **Dependency Analysis**: Analyze requirements files and detect potential issues

### Code Quality
- **Linting**: Run flake8, pylint, and black checks on your code
- **Formatting**: Auto-format code using black or autopep8
- **Testing**: Execute tests with pytest or unittest framework

### Environment Management
- **Virtual Environments**: Create and manage Python virtual environments
- **Environment Detection**: Auto-detect and use project venvs
- **Python Version Support**: Configure specific Python versions

### File Watching
- **Change Notifications**: Watch files for modifications (configurable patterns)
- **Pattern Filtering**: Include/exclude files by glob patterns

## 📦 Installation

### Prerequisites

**Option A: Using uv (Recommended ⚡)**
- [`uv`](https://github.com/astral-sh/uv) installed on Windows 11
- Install uv: `winget install astral-sh.uv` or `pip install uv`

**Option B: Traditional Python**
- Python 3.10+ installed on Windows 11
- pip package manager

### Setup with uv (Recommended)

```cmd
# 1. Navigate to project directory
cd C:\Users\dimir\proects\mcp-python

# 2. Install and run directly with uvx (no venv needed!)
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager
```

### Setup with pip (Traditional)

```cmd
# 1. Clone or create project directory:
cd C:\Users\dimir\proects
mkdir mcp-python
cd mcp-python

# 2. Create virtual environment:
python -m venv .venv
.venv\Scripts\activate

# 3. Install dependencies:
pip install -r requirements.txt

# 4. Optional: Install development tools:
pip install py-spy safety pip-audit
```

## ⚙️ Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_PYTHON_WORKSPACE` | Root directory for projects | `C:/Users/dimir/projects` |
| `MCP_PYTHON_DEBUG` | Enable debug logging | `false` |
| `MCP_PYTHON_LOG_LEVEL` | Logging level | `INFO` |
| `MCP_PYTHON_MAX_EXEC_TIME` | Command timeout (seconds) | `300` |

### Config File (`config.py`)

Customize server behavior by editing `config.py`:

```python
from config import ServerConfig

config = ServerConfig(
    workspace_root=Path("C:/Users/dimir/projects"),
    venv_name=".venv",
    debug_mode=True,
    allowed_commands=["python", "pip", "pytest", "black", "flake8", "pylint"],
    max_execution_time=600,
)
```

## 🔌 Usage

### Running the Server

#### 🚀 With uvx (Recommended)

```cmd
# Run directly without installation
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager

# With custom workspace
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --workspace "C:\MyProjects"

# With debug mode
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --debug

# SSE transport
uvx --from C:/Users/dimir/proects/mcp-python mcp-python-manager --transport sse --port 8000
```

#### 🐍 With Python (Traditional)

**Stdio Transport (Default for MCP clients):**
```cmd
# Direct execution
python server.py

# Via MCP stdio module
python -m mcp.server.stdio server:main
```

**SSE Transport (HTTP-based clients):**
```cmd
python server.py --transport sse --host localhost --port 8000
```

**With Options:**
```cmd
python server.py --debug --workspace "C:\MyProjects"
```

### Connecting from Claude Desktop

#### ⚡ Using uvx (Recommended)

Add to your Claude Desktop config (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "python-manager": {
      "command": "uvx",
      "args": [
        "--from",
        "C:/Users/dimir/proects/mcp-python",
        "mcp-python-manager",
        "--transport",
        "stdio"
      ],
      "env": {
        "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects",
        "UV_NO_CACHE": "0",
        "UV_LINK_MODE": "copy"
      }
    }
  }
}
```

#### 🐍 Using Python (Traditional)

```json
{
  "mcpServers": {
    "python-manager": {
      "command": "python",
      "args": [
        "C:/Users/dimir/proects/mcp-python/server.py"
      ],
      "env": {
        "MCP_PYTHON_WORKSPACE": "C:/Users/dimir/projects"
      }
    }
  }
}
```

### Connecting from Cursor/VS Code

#### ⚡ Using uvx (Recommended)

```json
{
  "mcp": {
    "servers": {
      "python-manager": {
        "type": "stdio",
        "command": "uvx",
        "args": [
          "--from",
          "C:/Users/dimir/proects/mcp-python",
          "mcp-python-manager",
          "--transport",
          "stdio"
        ],
        "env": {
          "UV_NO_CACHE": "0",
          "UV_LINK_MODE": "copy"
        }
      }
    }
  }
}
```

#### 🐍 Using Python (Traditional)

```json
{
  "mcp": {
    "servers": {
      "python-manager": {
        "type": "stdio",
        "command": "python",
        "args": ["C:/Users/dimir/proects/mcp-python/server.py"],
        "env": {
          "PYTHONUNBUFFERED": "1"
        }
      }
    }
  }
}
```

## 🛠️ Available Tools

### `get_project_info`
Get comprehensive project information.
```json
{
  "project_path": "C:/Users/dimir/projects/my-app"
}
```

### `run_python_script`
Execute a Python script.
```json
{
  "script_path": "main.py",
  "args": ["--config", "prod.yaml"],
  "env": {"DEBUG": "false"},
  "use_venv": true,
  "cwd": "C:/Users/dimir/projects/my-app"
}
```

### `install_package`
Install Python packages.
```json
{
  "packages": ["requests", "fastapi"],
  "upgrade": true,
  "use_venv": true
}
```
Or with requirements file:
```json
{
  "requirements_file": "requirements.txt",
  "use_venv": true
}
```

### `list_packages`
List installed packages.
```json
{
  "project_path": "C:/Users/dimir/projects/my-app",
  "format": "json"
}
```

### `run_tests`
Execute tests.
```json
{
  "test_path": "tests/",
  "test_framework": "pytest",
  "args": ["-x", "--cov"],
  "verbose": true
}
```

### `lint_code`
Run code linters.
```json
{
  "file_path": "src/",
  "linter": "all",
  "fix": false
}
```

### `create_venv`
Create virtual environment.
```json
{
  "project_path": "C:/Users/dimir/projects/new-project",
  "venv_name": ".venv",
  "python_version": "3.11"
}
```

### `get_debug_info`
Get debugging information.
```json
{
  "script_path": "main.py",
  "include_stack": true
}
```
Or by PID:
```json
{
  "pid": 12345,
  "include_stack": true
}
```

### `list_project_files`
List project files.
```json
{
  "directory": "C:/Users/dimir/projects/my-app",
  "pattern": "*.py",
  "recursive": true,
  "exclude_dirs": ["__pycache__", ".git"]
}
```

### `read_file`
Read file contents.
```json
{
  "file_path": "main.py",
  "start_line": 1,
  "end_line": 50,
  "encoding": "utf-8"
}
```

### `execute_command`
Execute allowed shell commands.
```json
{
  "command": "python -m pytest tests/ -v",
  "cwd": "C:/Users/dimir/projects/my-app",
  "timeout": 120
}
```

### `get_python_env`
Get Python environment info.
```json
{
  "project_path": "C:/Users/dimir/projects/my-app"
}
```

### `format_code`
Format Python code.
```json
{
  "file_path": "src/",
  "formatter": "black",
  "check_only": false
}
```

### `analyze_dependencies`
Analyze project dependencies.
```json
{
  "project_path": "C:/Users/dimir/projects/my-app",
  "check_updates": false,
  "check_security": false
}
```

### `watch_files`
Configure file watching.
```json
{
  "directory": "C:/Users/dimir/projects/my-app/src",
  "patterns": ["*.py", "*.json"],
  "recursive": true
}
```

## 🔒 Security

### Allowed Commands
By default, only these commands can be executed:
- `python` - Run Python scripts
- `pip` - Package management
- `pytest` - Run tests
- `black` - Code formatting
- `flake8` - Linting
- `pylint` - Advanced linting

Modify `config.allowed_commands` to customize.

### Path Validation
All file paths are validated to prevent directory traversal attacks.

### Output Truncation
Command output is limited to `max_output_length` characters (default: 50,000).

## 🐛 Debugging

### Enable Debug Logging
```cmd
set MCP_PYTHON_DEBUG=true
set MCP_PYTHON_LOG_LEVEL=DEBUG
python server.py
```

### Log File
Configure logging to file in `config.py`:
```python
config.log_file = Path("C:/Users/dimir/proects/mcp-python/server.log")
```

### Common Issues

| Issue | Solution |
|-------|----------|
| "Command not allowed" | Add command to `config.allowed_commands` |
| "Virtual environment not found" | Create venv with `create_venv` tool or manually |
| "Timeout executing command" | Increase `max_execution_time` in config |
| "Permission denied" | Run terminal as Administrator or check file permissions |

## 🧪 Testing the Server

### Manual Test with MCP Inspector
```cmd
# Install MCP inspector
npm install -g @modelcontextprotocol/inspector

# Run server and inspector
python server.py
# In another terminal:
mcp-inspector
```

### Python Test Script
```python
import asyncio
from mcp.client.session import ClientSession
from mcp.client.stdio import stdio_client

async def test_server():
    async with stdio_client(["python", "server.py"]) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")
            
            # Test get_project_info
            result = await session.call_tool(
                "get_project_info",
                {"project_path": "C:/Users/dimir/projects"}
            )
            print(result)

asyncio.run(test_server())
```

## 📁 Project Structure

```
mcp-python/
├── server.py           # Main server entry point
├── tools.py            # MCP tool implementations
├── config.py           # Configuration settings
├── requirements.txt    # Python dependencies
├── README.md          # This file
├── .gitignore         # Git ignore rules
└── logs/              # Log files (created at runtime)
```

## 🔄 Development

### Adding New Tools

1. Add tool definition in `tools.py` `_register_tools()` method
2. Implement the async method in `PythonProjectTools` class
3. Add handler case in `handle_tool_call()` method
4. Update this README with documentation

### Example Tool Addition
```python
# In _register_tools():
Tool(
    name="my_new_tool",
    description="What this tool does",
    inputSchema={...}
)

# Implementation:
async def my_new_tool(self, arg1: str) -> ToolResult:
    # Your logic here
    return ToolResult(success=True, message="Done", data={...})

# Handler:
elif name == "my_new_tool":
    result = await self.my_new_tool(**arguments)
```

## 📄 License

MIT License - Feel free to use and modify for your projects.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## 🔗 Resources

- [MCP Specification](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Windows Python Setup Guide](https://docs.python.org/3/using/windows.html)

---

**Author**: dimir  
**Created**: 2026  
**Platform**: Windows 11, Python 3.10+