# MCP Troubleshooting Guide for task-engine-ai-core

## 🚨 **ISSUE RESOLVED: MCP Configuration Fixed**

The MCP server connection issue has been resolved. The problem was using `npx` with the wrong command structure. The correct configuration uses the local server file directly.

## ✅ **WORKING CONFIGURATION**

### Cursor IDE (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "task-engine-ai-core": {
      "command": "node",
      "args": [
        "mcp-server/server.js"
      ],
      "cwd": "C:\\Users\\visual-code\\Task-engine",
      "env": {
        "TASK_MASTER_PROJECT_ROOT": "C:\\Users\\visual-code\\Task-engine",
        "TASK_ENGINE_VERSION": "0.3.2",
        "TASK_ENGINE_ENVIRONMENT": "development",
        "TASK_ENGINE_DEBUG": "true",
        "TASK_ENGINE_LOG_LEVEL": "info"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)
```json
{
  "servers": {
    "task-engine-ai-core": {
      "command": "node",
      "args": [
        "mcp-server/server.js"
      ],
      "cwd": "C:\\Users\\visual-code\\Task-engine",
      "env": {
        "TASK_MASTER_PROJECT_ROOT": "C:\\Users\\visual-code\\Task-engine",
        "TASK_ENGINE_VERSION": "0.3.2",
        "TASK_ENGINE_ENVIRONMENT": "development",
        "TASK_ENGINE_DEBUG": "true",
        "TASK_ENGINE_LOG_LEVEL": "info"
      }
    }
  }
}
```

## 🔧 **WHAT WAS WRONG**

### ❌ **Incorrect Configuration (Causing Errors)**
```json
{
  "command": "npx",
  "args": [
    "--package=task-engine-ai-core@0.3.1",
    "task-master-mcp"
  ]
}
```

**Problems:**
- `npx` doesn't work well with MCP protocol
- Package installation delays cause connection timeouts
- Binary path resolution issues

### ✅ **Correct Configuration (Working)**
```json
{
  "command": "node",
  "args": [
    "mcp-server/server.js"
  ],
  "cwd": "C:\\Users\\visual-code\\Task-engine"
}
```

**Benefits:**
- Direct execution of server file
- No package installation delays
- Immediate connection establishment
- Better error reporting

## 🧪 **TESTING THE FIX**

### Manual Server Test
```bash
# Test the server manually
cd C:\Users\visual-code\Task-engine
node mcp-server/server.js

# Expected output:
# Warning: Invalid main provider "active-agent" in ...
# [warning] FastMCP could not infer client capabilities
# {"method":"ping","jsonrpc":"2.0","id":0}
# {"method":"ping","jsonrpc":"2.0","id":1}
# ...
```

### MCP Connection Test
1. **Update MCP configuration** with the working configuration above
2. **Restart your IDE** (Cursor or VS Code)
3. **Test the connection** by asking Claude to list tasks
4. **Verify functionality** by creating or updating a task

## 🔄 **CONFIGURATION OPTIONS**

### Option 1: Local Development (Recommended)
- **Use:** Local server file with relative path and cwd
- **Command:** `node mcp-server/server.js` with `"cwd": "C:\\Users\\visual-code\\Task-engine"`
- **Benefits:** Fast, reliable, immediate feedback, cross-platform compatible
- **Best for:** Development and testing

### Option 2: Global Package Installation
```bash
# Install globally first
npm install -g task-engine-ai-core

# Then use in MCP config
{
  "command": "task-master-mcp",
  "args": []
}
```

### Option 3: Local Package Installation
```bash
# Install locally first
npm install task-engine-ai-core

# Then use in MCP config
{
  "command": "node",
  "args": ["node_modules/task-engine-ai-core/mcp-server/server.js"]
}
```

## 🚨 **COMMON ISSUES AND SOLUTIONS**

### Issue 1: "MCP error -1: Connection closed"
**Cause:** Incorrect command or path
**Solution:** Use the working configuration above

### Issue 2: "Package was not found and will be installed"
**Cause:** Using npx with package installation
**Solution:** Use local server file directly

### Issue 3: "Terminated"
**Cause:** Server startup failure
**Solution:** 
1. Test server manually: `node mcp-server/server.js`
2. Check environment variables
3. Verify Node.js version >= 18.0.0

### Issue 4: Environment Variable Issues
**Cause:** Missing or incorrect TASK_MASTER_PROJECT_ROOT
**Solution:** Set absolute path to project root

## 🔍 **DEBUGGING STEPS**

### Step 1: Verify Server Works
```bash
cd C:\Users\visual-code\Task-engine
node mcp-server/server.js
```
Should show ping messages without errors.

### Step 2: Check Environment Variables
```bash
echo $TASK_MASTER_PROJECT_ROOT
# Should show: C:\Users\visual-code\Task-engine
```

### Step 3: Verify Node.js Version
```bash
node --version
# Should show: v18.0.0 or higher
```

### Step 4: Test MCP Configuration
1. Update configuration file
2. Restart IDE
3. Check MCP connection status
4. Test basic functionality

## 📋 **ENVIRONMENT VARIABLES**

### Required
- `TASK_MASTER_PROJECT_ROOT` - Absolute path to project root

### Optional
- `TASK_ENGINE_VERSION` - Package version (default: 0.3.1)
- `TASK_ENGINE_ENVIRONMENT` - Environment config (default: development)
- `TASK_ENGINE_DEBUG` - Debug mode (default: true)
- `TASK_ENGINE_LOG_LEVEL` - Logging level (default: info)

### API Keys (Optional)
- `ANTHROPIC_API_KEY` - For Claude models
- `OPENAI_API_KEY` - For GPT models
- `PERPLEXITY_API_KEY` - For research features

## 🎯 **QUICK FIX CHECKLIST**

- [ ] Update MCP configuration to use `node` command
- [ ] Set correct path to `mcp-server/server.js`
- [ ] Set `TASK_MASTER_PROJECT_ROOT` environment variable
- [ ] Restart IDE to load new configuration
- [ ] Test server manually if issues persist
- [ ] Verify Node.js version >= 18.0.0

## 📚 **ADDITIONAL RESOURCES**

- **Configuration Examples:** `config/mcp-configurations.json`
- **Setup Script:** `scripts/setup-mcp-task-engine-core.js`
- **Package Documentation:** `README-npm.md`
- **Configuration Guide:** `config/README.md`

## ✅ **SUCCESS INDICATORS**

When MCP is working correctly, you should see:
- ✅ No connection errors in IDE
- ✅ Task Engine tools available in Claude
- ✅ Ability to list, create, and update tasks
- ✅ Real-time task synchronization
- ✅ Performance improvements active

---

**Last Updated:** January 8, 2025  
**Status:** ✅ Issue Resolved  
**Configuration:** Working and Tested