From 3e779a52737989753476d96ef4dc6beac1276552 Mon Sep 17 00:00:00 2001 From: nathan Date: Mon, 13 Apr 2026 14:49:23 -0400 Subject: [PATCH] docs(repo): reorganize setup docs and drop MCP probes - Move setup docs into documentation/ and remove legacy MCP troubleshooting content and ad hoc probe files - Support the session goal of a cleaner, gated workflow with clearer restart context and less maintenance noise --- MCP_TROUBLESHOOTING.md | 210 ------------------ .../SETUP_COMPLETE.md | 0 .../VSCODE_INTEGRATION_GUIDE.md | 0 mcp_settings.json | 22 -- test_mcp_stdio.py | 90 -------- test_simple_mcp.py | 70 ------ 6 files changed, 392 deletions(-) delete mode 100644 MCP_TROUBLESHOOTING.md rename SETUP_COMPLETE.md => documentation/SETUP_COMPLETE.md (100%) rename VSCODE_INTEGRATION_GUIDE.md => documentation/VSCODE_INTEGRATION_GUIDE.md (100%) delete mode 100644 mcp_settings.json delete mode 100644 test_mcp_stdio.py delete mode 100644 test_simple_mcp.py diff --git a/MCP_TROUBLESHOOTING.md b/MCP_TROUBLESHOOTING.md deleted file mode 100644 index eebe2b3..0000000 --- a/MCP_TROUBLESHOOTING.md +++ /dev/null @@ -1,210 +0,0 @@ -# MCP Server Troubleshooting Guide - -## Issue: MCP Server Not Showing in VS Code Copilot - -### What We've Done - -1. ✅ Updated `.vscode/settings.json` with full Python path -2. ✅ Added PYTHONPATH and PYTHONUNBUFFERED environment variables -3. ✅ Verified server has proper `mcp.run(transport="stdio")` setup -4. ✅ Created alternative configuration file - -### Diagnostic Steps - -#### 1. Check VS Code Output Panel - -**How:** -1. Open: `View` → `Output` -2. Select dropdown: `GitHub Copilot Chat` -3. Look for MCP-related errors - -**What to look for:** -- `Failed to start MCP server "nexus"` -- `Python not found` -- `Module not found` -- Any error mentioning "nexus" or "mcp" - -#### 2. Verify Copilot Extension Version - -**Required:** GitHub Copilot extension **v0.12.0 or newer** - -**Check:** -1. Extensions panel (`Ctrl+Shift+X`) -2. Search: "GitHub Copilot" -3. Check version number -4. Update if needed - -**Note:** MCP support is a recent feature. Older versions won't recognize MCP servers. - -#### 3. Verify Settings Location - -**Workspace vs User Settings:** - -The configuration should be in **workspace settings**, not user settings. - -**Check:** -``` -.vscode/settings.json ← Should be here (workspace) -``` - -**Not here:** -``` -%APPDATA%\Code\User\settings.json ← User settings (wrong location) -``` - -#### 4. Alternative Configuration Locations - -VS Code Copilot may look for MCP servers in: - -**Option A: Workspace settings (recommended)** -``` -.vscode/settings.json -``` - -**Option B: User-level MCP config** -``` -%APPDATA%\Code\User\globalStorage\github.copilot-chat\mcp_settings.json -``` - -I've created `mcp_settings.json` in the workspace root as an alternative. - -**To use Option B:** -1. Copy `mcp_settings.json` to the user-level path above -2. Create the directory if it doesn't exist -3. Reload VS Code - -#### 5. Test Server Manually - -Verify the server can start: - -```bash -cd nexus-mcp -.venv\Scripts\python.exe src\main.py -``` - -**Expected:** Server starts and waits for stdio input (no output is normal) -**Press Ctrl+C to exit** - -If this fails, there's a problem with the server itself (not VS Code config). - -#### 6. Check for Python Path Issues - -Current configuration uses: -``` -${workspaceFolder}/nexus-mcp/.venv/Scripts/python.exe -``` - -**Test if VS Code resolves this:** -1. Open Terminal in VS Code -2. Run: `echo ${workspaceFolder}` -3. Should show: `C:\Users\castn1.CORP\OneDrive - Wheels\Repos\mcp_servers` - -If blank, VS Code can't resolve workspace variables. - -**Workaround:** Use absolute path in settings.json: -```json -"command": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/.venv/Scripts/python.exe" -``` - -### Common Issues & Solutions - -#### Issue: "command not found: python" - -**Solution:** Use absolute path to Python: -```json -"command": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/.venv/Scripts/python.exe" -``` - -#### Issue: "No such file or directory: main.py" - -**Solution:** Check `cwd` is correct: -```json -"cwd": "${workspaceFolder}/nexus-mcp" -``` - -#### Issue: "Module not found" errors - -**Solution:** Add PYTHONPATH: -```json -"env": { - "PYTHONPATH": "${workspaceFolder}/nexus-mcp/src:${workspaceFolder}/nexus-mcp/lib" -} -``` - -#### Issue: Server starts but tools don't appear - -**Possible causes:** -1. Copilot extension too old (update to v0.12.0+) -2. MCP protocol mismatch -3. Server responding but not following MCP spec - -**Debug:** Check Copilot output panel for protocol errors - -### Alternative: Use Claude Desktop Instead - -If VS Code Copilot continues to have issues, you can use Claude Desktop with the same MCP server: - -**Location:** `%APPDATA%\Claude\claude_desktop_config.json` - -```json -{ - "mcpServers": { - "nexus": { - "command": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/.venv/Scripts/python.exe", - "args": [ - "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/src/main.py" - ], - "env": { - "USE_MOCK": "true", - "ENABLE_AUDIT": "true" - } - } - } -} -``` - -### Still Not Working? - -**Try this minimal test:** - -1. Create a simple MCP server test: - -```python -# test_simple_mcp.py -from mcp.server.fastmcp import FastMCP - -mcp = FastMCP("test") - -@mcp.tool() -def hello() -> str: - """Say hello""" - return "Hello from MCP!" - -if __name__ == "__main__": - mcp.run(transport="stdio") -``` - -2. Add to settings.json: - -```json -"github.copilot.chat.mcpServers": { - "test": { - "command": "python", - "args": ["${workspaceFolder}/test_simple_mcp.py"] - } -} -``` - -3. Reload VS Code -4. Try `@test` in Copilot Chat - -If this works, the issue is with the Nexus server. If not, it's a VS Code/Copilot configuration issue. - -### Report Issues - -If none of these work, the issue may be: -1. VS Code Copilot doesn't support MCP yet on your version -2. Feature not available in your region/license -3. Bug in Copilot extension - -Check: https://github.com/microsoft/vscode-copilot/issues diff --git a/SETUP_COMPLETE.md b/documentation/SETUP_COMPLETE.md similarity index 100% rename from SETUP_COMPLETE.md rename to documentation/SETUP_COMPLETE.md diff --git a/VSCODE_INTEGRATION_GUIDE.md b/documentation/VSCODE_INTEGRATION_GUIDE.md similarity index 100% rename from VSCODE_INTEGRATION_GUIDE.md rename to documentation/VSCODE_INTEGRATION_GUIDE.md diff --git a/mcp_settings.json b/mcp_settings.json deleted file mode 100644 index 6557946..0000000 --- a/mcp_settings.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "mcpServers": { - "nexus": { - "command": "python", - "args": [ - "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/src/main.py" - ], - "cwd": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp", - "env": { - "USE_MOCK": "true", - "ENABLE_AUDIT": "true", - "ENABLE_IDENTITY": "true", - "ENABLE_WORKDAY": "true", - "ENABLE_ITSM": "true", - "ENABLE_ASSETS": "true", - "ENABLE_LOGISTICS": "true", - "PYTHONPATH": "C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/src;C:/Users/castn1.CORP/OneDrive - Wheels/Repos/mcp_servers/nexus-mcp/lib", - "PYTHONUNBUFFERED": "1" - } - } - } -} \ No newline at end of file diff --git a/test_mcp_stdio.py b/test_mcp_stdio.py deleted file mode 100644 index 107d21d..0000000 --- a/test_mcp_stdio.py +++ /dev/null @@ -1,90 +0,0 @@ -#!/usr/bin/env python3 -"""Test MCP server stdio communication. - -This verifies the server can start and respond to MCP protocol messages. -""" - -import subprocess -import json -import sys -from pathlib import Path - -# Path to server -server_path = Path(__file__).parent / "nexus-mcp" / "src" / "main.py" -python_path = Path(__file__).parent / "nexus-mcp" / ".venv" / "Scripts" / "python.exe" - -print("🔍 Testing MCP Server stdio Communication\n") -print(f"Python: {python_path}") -print(f"Server: {server_path}") -print() - -# Start the server -try: - proc = subprocess.Popen( - [str(python_path), str(server_path)], - stdin=subprocess.PIPE, - stdout=subprocess.PIPE, - stderr=subprocess.PIPE, - cwd=server_path.parent.parent, - env={ - "USE_MOCK": "true", - "ENABLE_AUDIT": "true", - } - ) - - print("✅ Server process started") - - # Send initialize request (MCP protocol) - init_request = { - "jsonrpc": "2.0", - "id": 1, - "method": "initialize", - "params": { - "protocolVersion": "0.1.0", - "capabilities": {}, - "clientInfo": { - "name": "test-client", - "version": "1.0.0" - } - } - } - - print("📤 Sending initialize request...") - proc.stdin.write((json.dumps(init_request) + "\n").encode()) - proc.stdin.flush() - - # Read response (with timeout) - import select - import time - - start = time.time() - timeout = 5 - - while time.time() - start < timeout: - if proc.stdout in select.select([proc.stdout], [], [], 0.1)[0]: - response = proc.stdout.readline() - if response: - print("📥 Received response:") - print(response.decode().strip()) - print("\n✅ Server is responding via stdio!") - break - else: - print("❌ No response within timeout") - stderr = proc.stderr.read().decode() - if stderr: - print("\n🔴 Server errors:") - print(stderr) - - # Cleanup - proc.terminate() - proc.wait(timeout=2) - -except FileNotFoundError as e: - print(f"❌ Error: {e}") - print("\nPossible issues:") - print(" 1. Python not found - check virtual environment") - print(" 2. Server script not found - check path") -except Exception as e: - print(f"❌ Error: {e}") - import traceback - traceback.print_exc() diff --git a/test_simple_mcp.py b/test_simple_mcp.py deleted file mode 100644 index 080ac5b..0000000 --- a/test_simple_mcp.py +++ /dev/null @@ -1,70 +0,0 @@ -#!/usr/bin/env python3 -"""Minimal MCP server for testing VS Code Copilot integration. - -This is a simplified version to help diagnose MCP server issues. -If this works, the problem is with the Nexus server configuration. -If this doesn't work, it's a VS Code/Copilot setup issue. -""" - -from mcp.server.fastmcp import FastMCP - -# Create minimal server -mcp = FastMCP( - name="test-server", - instructions="A minimal MCP server for testing VS Code integration" -) - - -@mcp.tool() -def hello(name: str = "World") -> str: - """Say hello to someone. - - Args: - name: The name to greet (default: World) - - Returns: - A friendly greeting - """ - return f"Hello, {name}! MCP server is working! 🎉" - - -@mcp.tool() -def test_connection() -> dict: - """Test that the MCP connection is working. - - Returns: - Status information about the server - """ - return { - "status": "connected", - "server": "test-server", - "message": "MCP server is responding correctly", - "tools_available": 3 - } - - -@mcp.tool() -def check_environment() -> dict: - """Check environment variables and paths. - - Returns: - Environment information - """ - import os - import sys - - return { - "python_version": sys.version, - "python_executable": sys.executable, - "current_directory": os.getcwd(), - "use_mock": os.getenv("USE_MOCK", "not set"), - } - - -def main(): - """Run the MCP server.""" - mcp.run(transport="stdio") - - -if __name__ == "__main__": - main()