Vscode MCP Python

🚀 MCP Server - Model Context Protocol Server

A production-ready MCP (Model Context Protocol) server for integrating VSCode and Claude, featuring comprehensive tool support, performance monitoring, and diagnostics.

🚀 Quick Start

This MCP server is designed to integrate VSCode with Claude, offering a range of features such as technical optimizations, workflow automation, and private data context support. Here's how you can get started:

Prerequisites

• Python 3.8 or higher
• VSCode (optional, for VSCode integration features)
• Windows, Linux, or macOS

Setup

1. Clone or download this repository.

2. Ensure all files are in the same directory:

   • mcp_server.py - Main server
   • tools.py - Tool implementations
   • vscode_detector.py - VSCode integration
   • diagnostics.py - Health checks
   • performance_monitor.py - Performance tracking
   • languages.json - Language configuration

3. Configure your Artificial intelligence Desktop (for Claude) to use this server (see Configuration section).

Quick Start Commands

# Test server compilation
python -m py_compile mcp_server.py

# Run diagnostics
python diagnostics.py

# Start server (usually called by Claude)
python mcp_server.py

✨ Features

⚡ Technical Optimizations

• Reduced Token Overhead: Instead of pasting large datasets into the chat, the MCP server allows Claude to query only the specific data it needs. This results in faster responses and lower cost/token usage.
• Asynchronous Execution: By leveraging Python’s asynchronous capabilities, the server can handle multiple data requests simultaneously without freezing the interaction.
• Custom Tool Mapping: You can wrap complex Python libraries (like pandas, beautifulsoup, or os) into simple tools that Claude can call instantly.

🌟 Value Added to Projects

• Bridging the Gap: It turns Claude from a "chatbot" into a "developer agent" that can actually see and modify your local code or databases.
• Workflow Automation: You can automate repetitive tasks like log analysis, local file reorganization, or database querying simply by talking to Claude.
• Private Data Context: Since the server runs locally, you can provide Claude with context from private documents or internal company data without ever uploading those files to the cloud.

Core Capabilities

• 10 Professional Process - Complete file operations, code analysis, and VSCode integration
• LRU Caching - Intelligent request caching for 2 - 3x performance improvement
• Type Safety - 100% type hints (PEP 484 compliant)
• Enterprise Architecture - SOLID principles, design patterns, professional structure
• Comprehensive Logging - Structured logging to stderr for debugging
• Error Handling - Production - grade error handling with specific exceptions

📦 Installation

Prerequisites

• Python 3.8 or higher
• VSCode (optional, for VSCode integration features)
• Windows, Linux, or macOS

Setup

1. Clone or download this repository.

2. Ensure all files are in the same directory:

   • mcp_server.py - Main server
   • tools.py - Tool implementations
   • vscode_detector.py - VSCode integration
   • diagnostics.py - Health checks
   • performance_monitor.py - Performance tracking
   • languages.json - Language configuration

3. Configure your Artificial intelligence Desktop (for Claude) to use this server (see Configuration section).

💻 Usage Examples

Reading Files

User: "Read the contents of mcp_server.py"
Claude: Uses read_file tool
Result: File contents displayed

Code Analysis

User: "Analyze the code in tools.py"
Claude: Uses analyze_code tool
Result: Functions, classes, and imports listed with line numbers

Writing Code

User: "Write a Python calculator"
Claude: Uses write_code_to_project tool
System: Permission prompt appears
User: Approves
Result: calculator.py created with detailed feedback

Modifying Code

User: "In calculator.py, add error handling to the divide function"
Claude: Uses change_code tool
System: Permission prompt appears
User: Approves
Result: Function updated with before/after preview

Project Overview

User: "Show me the project structure"
Claude: Uses get_project_structure tool
Result: Files organized by programming language

📚 Documentation

Configuration

Add to your Claude Desktop config file:

Windows

%APPDATA%\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Configuration Example

{
  "mcpServers": {
    "vscode-mcp": {
      "command": "python",
      "args": ["C:\\path\\to\\mcp_server.py"]
    }
  }
}

Architecture

Main Components

• MCPServer Class: Protocol handler implementing MCP 2024 - 11 - 05, JSON - RPC 2.0 communication, Async/await patterns, Request/response management.
• ToolRegistry Class: Tool registration and management, Input schema validation, Tool invocation.
• RequestCache Class: LRU caching mechanism, Configurable cache size, Automatic eviction.
• LanguageConfig Class: Language configuration management, Pattern matching for code analysis, File extension handling.

Design Patterns

• Registry Pattern - Tool management
• Cache Pattern - Request caching
• Dataclass Pattern - Type - safe metadata
• Dependency Injection - Configuration management
• Strategy Pattern - Tool execution

Performance

Optimization Features

• LRU cache for safe tool requests
• Async/await for non - blocking operations
• Efficient file system scanning
• Smart VSCode process detection
• Minimal memory footprint

Performance Metrics

Diagnostics

Health Checks

Run comprehensive diagnostics:

# Full diagnostic suite
python diagnostics.py

# Quick check
python diagnostics.py --mode quick

# Health status (JSON)
python diagnostics.py --mode health

Diagnostic Tests

• Python version compatibility
• Required files existence
• File permissions
• Configuration validity
• Module imports
• Syntax checking
• Disk space
• Memory usage
• VSCode status
• Network connectivity

Development

Code Quality Standards

• PEP 8 - Style guide compliance
• PEP 257 - Docstring conventions
• PEP 484 - Type annotations
• Google Style - Docstring format

Testing

# Syntax check all files
python -m py_compile *.py

# Run diagnostics
python diagnostics.py

# Test tool imports
python -c "import tools; import mcp_server"

Troubleshooting

Common Issues

• Server Won't Start:
  • Check Python version: python --version (must be 3.8+)
  • Run diagnostics: python diagnostics.py
  • Check syntax: python -m py_compile mcp_server.py
• Tools Not Working:
  • Verify file permissions
  • Check languages.json is valid JSON
  • Run import test: python -c "import tools"
• VSCode Detection Fails:
  • Ensure VSCode is running
  • Check process permissions (Windows)
  • Verify workspace directory is accessible
• Permission Errors:
  • Run as administrator (if needed)
  • Check file/directory permissions
  • Verify paths in configuration

Code Contribution Guidelines

1. Follow PEP 8 style guide.
2. Add type hints to all functions.
3. Write comprehensive docstrings.
4. Include error handling.
5. Add tests for new features.
6. Update README for new tools.

Adding New Tools

1. Implement tool function in tools.py.
2. Add tool definition in mcp_server.py TOOL_DEFINITIONS.
3. Register tool in main() function.
4. Update README documentation.
5. Add diagnostic checks if needed.

📄 License

This project is under the MIT License. See the LICENSE file for details.

Support

Documentation

• Full API reference in code docstrings.
• Usage examples in this README.
• Diagnostic tools for troubleshooting.

Getting Help

1. Run diagnostics: python diagnostics.py.
2. Check logs in stderr output.
3. Review error messages carefully.
4. Verify configuration files.

Credits

Author: Kommandant
Version: 1.0.0
License: MIT
Status: Development