Epic: Python Language Support with Modern Tooling (pyright, ruff, uv, pytest)

[rshade]

Priority: P1 - High Priority

Milestone: 2025-Q1
Estimated Effort: 6-8 weeks
Language: Python

Epic Overview

Implement comprehensive Python language support following the proven patterns from our Go tools implementation (13 tools, 901 lines in src/tools/go-tools.ts). This epic will provide Python developers with the same level of first-class support that Go developers currently enjoy.

Modern Python Stack (2025):

• uv - Ultra-fast package manager (10-100x faster than pip)
• ruff - All-in-one linter/formatter (replaces flake8, black, isort, pyupgrade)
• pyright - Static type checker (faster than mypy, better editor integration)
• pytest - Industry-standard testing framework

Implementation Tasks

Phase 1: Core Development Tools (Week 1-2, 24-32 hours)

• Python Project Detection and Info Tool (python_project_info) #132: Python project detection and info tool (python_project_info)
• Python Testing with pytest (python_test) #133: Python testing with pytest (python_test)
• Python Linting and Formatting with ruff (python_lint, python_format) #134: Python linting and formatting with ruff (python_lint, python_format)
• Python Type Checking with pyright (python_check_types) #135: Python type checking with pyright (python_check_types)
• Python Dependency Management with uv (python_install_deps) #136: Python dependency management with uv (python_install_deps)
• Python Version Detection and Upgrade Recommendations #137: Python version detection and upgrade recommendations

Phase 2: Advanced Features (Week 3-4, 24-32 hours)

• Python Security Scanning (python_security) #138: Python security scanning (python_security)
• Python Package Building (python_build) #139: Python package building (python_build)
• Python Virtual Environment Management (python_venv) #140: Python virtual environment management (python_venv)
• Python Performance Benchmarking (python_benchmark) #141: Python performance benchmarking (python_benchmark)

Phase 3: Specialized Tools (Week 5-6, 16-24 hours)

• Python Dependency Updates and Compatibility (python_update_deps) #142: Python dependency updates (python_update_deps)
• Python Version Compatibility Checking (python_compatibility) #143: Python version compatibility checking (python_compatibility)
• Python Profiling and Optimization (python_profile) #144: Python profiling and optimization (python_profile)

Architecture Reference

This implementation follows the Go Tools pattern (src/tools/go-tools.ts):

1. Tool Class Structure

   • One tool = One method + One Zod schema + One validator
   • All tools return unified PythonToolResult interface
   • Private utility methods for common operations
   • Integration with CacheManager for performance

2. Design Patterns

   • Incremental argument assembly (build command args step-by-step)
   • Smart caching with file-based invalidation
   • Error pattern matching with actionable suggestions
   • Security-first command execution via ShellExecutor

3. Integration Points

   • ShellExecutor (secure command execution)
   • ProjectDetector (automatic Python project detection)
   • Configuration schema (Python-specific options in .mcp-devtools.json)
   • MCP Protocol (tool registration and handling in src/index.ts)

Key Features

1. Automatic Python Version Detection

• Detect Python 3.9 and older versions
• Recommend upgrading to Python 3.11+ with actionable guidance
• Support multiple Python versions in monorepos
• Warn about EOL Python versions (3.7, 3.8)

2. Modern Tool Integration

• Prefer pyright over mypy (faster, better DX, better editor integration)
• Use ruff for unified linting/formatting (single tool vs. 4-5 tools)
• Leverage uv for 10-100x faster dependency management
• pytest with coverage reporting and parallel execution

3. Smart Caching

• Cache project detection results (pyproject.toml, setup.py analysis)
• Cache dependency resolution
• File-based invalidation for requirements.txt, pyproject.toml, setup.py

4. Error Recovery Patterns

• Missing tool detection with installation instructions
• Missing dependencies with resolution suggestions
• Version conflicts with upgrade paths
• Type errors with pyright guidance
• Virtual environment issues with creation steps

Dependencies

Code Changes Required:

• src/utils/shell-executor.ts - Add Python commands to ALLOWED_COMMANDS
• src/utils/project-detector.ts - Add Python project detection patterns
• .mcp-devtools.schema.json - Add Python-specific configuration options
• src/index.ts - Register Python tools with MCP server

New Files:

• src/tools/python-tools.ts - Main Python tools class (~900-1000 lines)
• src/__tests__/tools/python-tools.test.ts - Comprehensive test suite (~800+ lines)
• examples/python-project.json - Example configuration

Documentation:

• README.md - Add Python tools documentation section
• CLAUDE.md - Add Python-specific development notes

Acceptance Criteria

Feature Complete

• 13 Python tools implemented (matching Go tools count)
• All tools follow Go tools architecture pattern
• Python project auto-detection works (pyproject.toml, setup.py, requirements.txt)
• Configuration schema supports Python-specific options
• Python version upgrade recommendations for <=3.9

Quality Gates (MUST PASS)

• 85-90%+ test coverage for all Python tools
• make lint passes with zero errors
• make test passes with 100% success rate
• make build completes successfully
• All tests are meaningful (not AI slop - see CLAUDE.md Test Quality Standards)
• Comprehensive error handling with actionable messages
• JSDoc documentation for all public APIs

Integration Complete

• All tools registered in src/index.ts with proper handlers
• ShellExecutor allowlist updated with Python commands
• Example configurations in examples/python-project.json
• README.md updated with Python tool documentation
• CLAUDE.md updated with Python development notes

Testing Complete

• Unit tests for each tool (following git-tools.test.ts pattern)
• Integration tests with real Python projects
• Cross-platform testing (Linux, macOS, Windows)
• Edge cases covered (missing tools, version mismatches, virtual envs)
• Mock ShellExecutor for fast, deterministic tests

Success Metrics

• Python developers can use MCP DevTools with zero configuration
• Python tool execution performance matches Go tools (<100ms overhead)
• Error messages provide clear, actionable guidance
• All Python tools integrate with smart suggestions system
• Cache hit rate >90% for project detection
• Python 3.9 users receive upgrade recommendations automatically

Technical Debt Prevention

• No duplicate code between tools (use shared utilities)
• Consistent error handling patterns across all tools
• Proper TypeScript types (no any types)
• All async operations have timeouts
• All shell commands properly sanitized via ShellExecutor
• Cache keys include all parameters for correctness

References

Internal:

• Go Tools Implementation: src/tools/go-tools.ts (901 lines, 13 tools)
• Go Tools Tests: src/__tests__/tools/go-tools.test.ts (817 lines)
• Git Tools Pattern: src/tools/git-tools.ts (813 lines, excellent error handling)
• Shell Executor: src/utils/shell-executor.ts (security patterns)
• Project Detector: src/utils/project-detector.ts (detection patterns)

External:

• Python Best Practices 2025: https://osquant.com/papers/python-tooling-in-2025/
• Modern Python Workflow: https://karambir.in/posts/python-programming-workflow-2025/
• uv Documentation: https://docs.astral.sh/uv/
• ruff Documentation: https://docs.astral.sh/ruff/
• pyright Documentation: https://microsoft.github.io/pyright/
• pytest Documentation: https://docs.pytest.org/

Related Issues

Phase 1 - Core Tools:
#132, #133, #134, #135, #136, #137

Phase 2 - Advanced Features:
#138, #139, #140, #141

Phase 3 - Specialized Tools:
#142, #143, #144

---

Note: This Epic tracks overall Python support progress. Individual tasks are broken into focused, completable issues (8-16 hours each) that can be worked on independently or in parallel.