pylance-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pylance MCP Server Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# Pylance MCP Pro
+
+**Professional Python Intelligence Server with REST API and AI Features**
+
+A production-ready Model Context Protocol (MCP) server that provides enhanced Pylance/Pyright language server capabilities with REST API access, AI-powered code analysis, and OpenTelemetry tracing.
+
+## 🎯 What Makes This Different?
+
+Unlike Microsoft's standard Pylance server, **Pylance MCP Pro** includes:
+
+- ✅ **REST API** - HTTP endpoints for web/mobile integration
+- ✅ **AI Features** - Claude-powered type error explanations (Pro tier)
+- ✅ **API Key Authentication** - Secure access with tier-based rate limiting
+- ✅ **OpenTelemetry Tracing** - Monitor performance and debug issues
+- ✅ **Conversation Logging** - Track AI interactions for analysis
+- ✅ **Advanced Code Intelligence** - Enhanced completions and diagnostics
+- ✅ **Professional Branding** - Shows up distinctly in VS Code
+- ✅ **Custom Tools** - 12 specialized Python analysis tools
+
+## 🌐 Access Methods
+
+### 1. MCP Protocol (Claude Desktop, Continue, Cursor)
+
+Traditional MCP client integration via stdio.
+
+### 2. REST API (Web/Mobile Apps)
+
+HTTP endpoints for any application:
+```bash
+curl -X POST https://api.pylancemcp.com/api/v1/analyze \
+  -H "X-API-Key: pmcp_your_key" \
+  -H "Content-Type: application/json" \
+  -d '{"file_path": "test.py", "content": "x: int = \"hello\""}'
+```
+
+See [API_TESTING_GUIDE.md](API_TESTING_GUIDE.md) for full documentation.
+
+## 🚀 Quick Installation
+
+### One-Line Install:
+
+```bash
+python install_to_vscode.py
+```
+
+Then reload VS Code (Ctrl+Shift+P → "Developer: Reload Window")
+
+### Manual Installation:
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "pylance-mcp-pro": {
+      "command": "/path/to/.venv/Scripts/python.exe",
+      "args": ["/path/to/server.py"],
+      "env": {
+        "WORKSPACE_ROOT": "${workspaceFolder}"
+      },
+      "enabled": true
+    }
+  },
+  "chat.mcp.autostart": "always"
+}
+```
+
+## 🔧 Finding Your Tools in VS Code
+
+After installation and reload:
+
+1. **Open Copilot Chat** (Ctrl+Alt+I)
+2. **Click the 🔧 tools icon** in the chat input area
+3. **Look for "pylance-mcp-pro"** (your custom server!)
+4. You'll see all 12 tools listed
+
+**Note:** This shows up separately from Microsoft's "pylance" server.
+
+## 🛠️ Available Tools (12)
+
+### Code Intelligence:
+- `get_completions` - Intelligent code completions with full type info
+- `get_hover` - Type hints and documentation on hover
+- `get_definition` - Go to definition across workspace
+- `get_references` - Find all references to symbols
+
+### Code Quality:
+- `get_diagnostics` - Errors, warnings, and type issues
+- `format_document` - Professional code formatting
+- `rename_symbol` - Safe refactoring across files
+
+### Navigation:
+- `get_signature_help` - Function signatures and parameters
+- `get_document_symbols` - File outline and structure
+- `get_workspace_symbols` - Project-wide symbol search
+
+### Operations:
+- `apply_workspace_edit` - Apply code changes safely
+- `health_check` - Monitor server status
+
+## 📊 Features
+
+### OpenTelemetry Tracing
+Monitor your code intelligence operations in real-time with the AI Toolkit trace viewer.
+
+### Smart Environment Detection
+Automatically detects and uses:
+- Virtual environments (.venv, venv, env)
+- Python version from your project
+- Workspace-specific configurations
+
+### Professional Integration
+- Seamless Copilot Chat integration
+- Natural language queries
+- Automatic tool selection
+- Context-aware responses
+
+## 💬 Usage Examples
+
+Just ask naturally in Copilot Chat:
+
+```
+"What's the type of this variable?"
+"Show me all references to calculate_total"
+"Are there any type errors in this file?"
+"Get completions for line 42, column 10"
+"Format this document"
+```
+
+The appropriate tools are invoked automatically!
+
+## 🔍 Verification
+
+Check if it's running:
+
+1. **View → Output**
+2. **Select "pylance-mcp-pro" from dropdown**
+3. Should show: "Discovered 12 tools"
+
+Or run the test:
+```bash
+python server.py --test
+```
+
+## 🎓 For Users Installing Your Server
+
+When someone installs this:
+
+1. They run `python install_to_vscode.py`
+2. Reload VS Code
+3. Open Copilot Chat
+4. Click 🔧 → See "pylance-mcp-pro" listed
+5. Start asking Python questions!
+
+**The tools appear professionally in the Configure Tools menu!**
+
+## 🆚 vs Microsoft's Pylance
+
+| Feature | Microsoft Pylance | Pylance MCP Pro |
+|---------|------------------|-----------------|
+| Basic Language Intelligence | ✅ | ✅ |
+| OpenTelemetry Tracing | ❌ | ✅ |
+| Conversation Logging | ❌ | ✅ |
+| Custom MCP Tools | ❌ | ✅ (12 tools) |
+| Shows in Configure Tools | Default | Distinct entry |
+| Professional Branding | Generic | Branded |
+
+## 📝 Configuration
+
+All settings in `settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "pylance-mcp-pro": {
+      "command": "python.exe",
+      "args": ["server.py"],
+      "env": {
+        "WORKSPACE_ROOT": "${workspaceFolder}"
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+## 🐛 Troubleshooting
+
+### Tools not showing?
+- Reload VS Code
+- Check Output panel for "pylance-mcp-pro"
+- Verify `chat.mcp.autostart` is "always"
+
+### Wrong server running?
+- Look for "pylance-mcp-pro" not "pylance"
+- Microsoft's is built-in, yours is custom
+
+### Need help?
+- Run `python server.py --test`
+- Check MCP_USAGE.md
+- Review Output panel logs
+
+## 🎉 Success!
+
+When you see in Output:
+```
+Starting server pylance-mcp-pro
+Discovered 12 tools
+```
+
+**You're ready to go!** 🚀
+
+Your professional Python intelligence server is running and available in Copilot Chat's Configure Tools menu.

package/bin/pylance-mcp.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * Pylance MCP Server Launcher
+ * 
+ * This script launches the Python-based MCP server.
+ * It handles Python environment detection and server startup.
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Find Python executable
+function findPython() {
+  const pythonCommands = ['python3', 'python', 'py'];
+  
+  for (const cmd of pythonCommands) {
+    try {
+      const { status } = require('child_process').spawnSync(cmd, ['--version'], {
+        stdio: 'ignore'
+      });
+      
+      if (status === 0) {
+        return cmd;
+      }
+    } catch (e) {
+      continue;
+    }
+  }
+  
+  console.error('Error: Python 3.8+ is required but not found in PATH.');
+  console.error('Please install Python from https://www.python.org/downloads/');
+  process.exit(1);
+}
+
+// Get server.py path
+const serverPath = path.join(__dirname, '..', 'server.py');
+
+if (!fs.existsSync(serverPath)) {
+  console.error(`Error: server.py not found at ${serverPath}`);
+  process.exit(1);
+}
+
+// Launch server
+const python = findPython();
+const serverProcess = spawn(python, [serverPath], {
+  stdio: 'inherit',
+  env: {
+    ...process.env,
+    OTEL_SDK_DISABLED: process.env.OTEL_SDK_DISABLED || 'true',
+    WORKSPACE_PATH: process.env.WORKSPACE_PATH || process.cwd()
+  }
+});
+
+// Handle exit
+serverProcess.on('exit', (code) => {
+  process.exit(code || 0);
+});
+
+// Handle signals
+process.on('SIGINT', () => {
+  serverProcess.kill('SIGINT');
+});
+
+process.on('SIGTERM', () => {
+  serverProcess.kill('SIGTERM');
+});

package/mcp_server/__init__.py

@@ -0,0 +1,13 @@
+"""
+Pylance MCP Server Package
+
+Production-ready MCP server exposing Pylance/Pyright capabilities.
+"""
+
+__version__ = "1.0.0"
+
+from .pylance_bridge import PylanceBridge
+from .tools import PylanceTools
+from .resources import PylanceResources
+
+__all__ = ["PylanceBridge", "PylanceTools", "PylanceResources"]

package/mcp_server/ai_features.py

@@ -0,0 +1,274 @@
+"""
+AI-powered features for Pylance MCP Pro
+Requires ANTHROPIC_API_KEY in environment
+"""
+
+import os
+from typing import Dict, List, Any
+from anthropic import Anthropic
+
+client = Anthropic(api_key=os.getenv('ANTHROPIC_API_KEY'))
+
+async def explain_type_error(
+    code: str,
+    error_message: str,
+    file_path: str,
+    line_number: int
+) -> Dict[str, Any]:
+    """
+    Use Claude to explain a type error in simple terms with fix suggestions
+    
+    Args:
+        code: The code snippet containing the error
+        error_message: The raw Pyright error message
+        file_path: Path to the file with the error
+        line_number: Line number where error occurs
+    
+    Returns:
+        Dict with explanation, causes, and suggested fixes
+    """
+    
+    prompt = f"""You are a Python type error expert. A developer has encountered this type error:
+
+File: {file_path}
+Line: {line_number}
+Error: {error_message}
+
+Code snippet:
+```python
+{code}
+```
+
+Please provide:
+1. A clear, beginner-friendly explanation of what this error means
+2. Why it occurred (root causes)
+3. 2-3 concrete code fixes with examples
+4. Best practices to avoid this error in the future
+
+Be concise and practical. Focus on actionable solutions."""
+
+    try:
+        message = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1500,
+            messages=[{
+                "role": "user",
+                "content": prompt
+            }]
+        )
+        
+        explanation = message.content[0].text
+        
+        return {
+            "success": True,
+            "explanation": explanation,
+            "model": "claude-sonnet-4",
+            "tokens_used": message.usage.input_tokens + message.usage.output_tokens
+        }
+        
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+
+async def enhance_type_annotations(
+    code: str,
+    file_path: str,
+    existing_types: List[Dict[str, Any]]
+) -> Dict[str, Any]:
+    """
+    Use Claude to suggest improved type annotations for code
+    
+    Args:
+        code: The code to analyze
+        file_path: Path to the file
+        existing_types: Existing type information from Pyright
+    
+    Returns:
+        Dict with suggested type improvements
+    """
+    
+    # Format existing types
+    types_context = "\n".join([
+        f"- {t.get('symbol', 'unknown')}: {t.get('type', 'unknown')}"
+        for t in existing_types[:10]  # Limit to avoid token bloat
+    ])
+    
+    prompt = f"""You are a Python typing expert. Analyze this code and suggest improved type annotations.
+
+File: {file_path}
+
+Current types detected:
+{types_context}
+
+Code:
+```python
+{code}
+```
+
+Please suggest:
+1. Missing type annotations that should be added
+2. Generic types that could be more specific
+3. Union types that could be simplified
+4. Return type annotations for functions
+5. Type aliases that would improve readability
+
+For each suggestion, provide:
+- Line number
+- Current code
+- Suggested improvement
+- Reasoning
+
+Format as JSON array of suggestions."""
+
+    try:
+        message = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=2000,
+            messages=[{
+                "role": "user",
+                "content": prompt
+            }]
+        )
+        
+        suggestions = message.content[0].text
+        
+        return {
+            "success": True,
+            "suggestions": suggestions,
+            "model": "claude-sonnet-4",
+            "tokens_used": message.usage.input_tokens + message.usage.output_tokens
+        }
+        
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+
+async def analyze_code_patterns(
+    code: str,
+    diagnostics: List[Dict[str, Any]]
+) -> Dict[str, Any]:
+    """
+    Use Claude to identify code patterns and suggest improvements
+    
+    Args:
+        code: The code to analyze
+        diagnostics: Existing diagnostics from Pyright
+    
+    Returns:
+        Dict with pattern analysis and suggestions
+    """
+    
+    # Format diagnostics
+    diag_summary = "\n".join([
+        f"- Line {d.get('line', '?')}: {d.get('message', 'unknown')}"
+        for d in diagnostics[:5]
+    ])
+    
+    prompt = f"""Analyze this Python code for patterns and improvements.
+
+Existing issues:
+{diag_summary}
+
+Code:
+```python
+{code}
+```
+
+Identify:
+1. Anti-patterns or code smells
+2. Type safety issues
+3. Opportunities for better abstractions
+4. Performance considerations
+5. Maintainability improvements
+
+Prioritize suggestions by impact. Be specific and actionable."""
+
+    try:
+        message = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1500,
+            messages=[{
+                "role": "user",
+                "content": prompt
+            }]
+        )
+        
+        analysis = message.content[0].text
+        
+        return {
+            "success": True,
+            "analysis": analysis,
+            "model": "claude-sonnet-4",
+            "tokens_used": message.usage.input_tokens + message.usage.output_tokens
+        }
+        
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }
+
+
+async def suggest_type_stubs(
+    library_name: str,
+    usage_examples: List[str]
+) -> Dict[str, Any]:
+    """
+    Generate type stub suggestions for untyped libraries
+    
+    Args:
+        library_name: Name of the library
+        usage_examples: Code examples showing library usage
+    
+    Returns:
+        Dict with stub file suggestions
+    """
+    
+    examples = "\n\n".join(usage_examples[:3])
+    
+    prompt = f"""Generate type stub (.pyi) suggestions for the library '{library_name}'.
+
+Usage examples:
+```python
+{examples}
+```
+
+Create a type stub file that includes:
+1. Function signatures with proper types
+2. Class definitions with methods
+3. Constants and module-level variables
+4. Docstrings for complex types
+
+Format as a complete .pyi file."""
+
+    try:
+        message = client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=2000,
+            messages=[{
+                "role": "user",
+                "content": prompt
+            }]
+        )
+        
+        stub_content = message.content[0].text
+        
+        return {
+            "success": True,
+            "stub_content": stub_content,
+            "library": library_name,
+            "model": "claude-sonnet-4",
+            "tokens_used": message.usage.input_tokens + message.usage.output_tokens
+        }
+        
+    except Exception as e:
+        return {
+            "success": False,
+            "error": str(e)
+        }