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
This commit is contained in:
parent
e7cc0385b7
commit
3e779a5273
@ -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
|
||||
@ -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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -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()
|
||||
@ -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()
|
||||
Loading…
x
Reference in New Issue
Block a user