task-engine-ai-core
Version:
Revolutionary AI-driven task management system with complete transformation trilogy: Frontend v0.1.0, Backend v0.2.0, CLI v0.3.0 - Enterprise-grade performance with 95% improvements
236 lines (193 loc) • 6.08 kB
Markdown
# 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