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