aiworkflow-mcp
Version:
MCP Server for BRD → Miro → Figma → Full-Stack Application Workflow
274 lines (203 loc) • 6.42 kB
Markdown
# MCP Server Troubleshooting Guide
## 🔴 NPM Global Install Shows No Tools & Red Icon
### Problem
After running `npm install -g aiworkflow-mcp`, Cursor shows:
- ❌ Red indicator for the MCP server
- ❌ No tools available
- ❌ Server appears disconnected
**🪟 Windows Users**: See [WINDOWS_NPM_INSTALL.md](./WINDOWS_NPM_INSTALL.md) for complete Windows installation guide.
### ✅ Solution: Fix Command Path on Windows
The issue is that Windows npm global installs don't resolve the bin command properly in Cursor's MCP configuration.
#### Fix 1: Use npx (Recommended - Always Works)
Edit your `C:\Users\YourName\.cursor\mcp.json`:
```json
{
"mcpServers": {
"aiworkflow": {
"command": "npx",
"args": ["-y", "aiworkflow-mcp"],
"env": {
"MIRO_ACCESS_TOKEN": "your_token_here",
"FIGMA_ACCESS_TOKEN": "your_token_here",
"OPENAI_API_KEY": "your_key_here"
}
}
}
}
```
**Why this works**: `npx` properly resolves packages and works consistently on Windows.
#### Fix 2: Use Full Path to Global Installation
Find where npm installed the package:
```powershell
npm root -g
# Example output: C:\Users\YourName\AppData\Roaming\npm\node_modules
```
Then configure with the full path:
```json
{
"mcpServers": {
"aiworkflow": {
"command": "node",
"args": [
"C:/Users/YourName/AppData/Roaming/npm/node_modules/aiworkflow-mcp/dist/index.js"
],
"env": {
"MIRO_ACCESS_TOKEN": "your_token_here",
"FIGMA_ACCESS_TOKEN": "your_token_here",
"OPENAI_API_KEY": "your_key_here"
}
}
}
}
```
**Important**: Use forward slashes `/` not backslashes `\`
#### Fix 3: Use CMD Wrapper (Windows-Specific)
If npm created a `.cmd` wrapper, you can use:
```json
{
"mcpServers": {
"aiworkflow": {
"command": "cmd",
"args": ["/c", "aiworkflow-mcp"],
"env": {
"MIRO_ACCESS_TOKEN": "your_token_here",
"FIGMA_ACCESS_TOKEN": "your_token_here",
"OPENAI_API_KEY": "your_key_here"
}
}
}
}
```
#### After Configuration
1. **Save the file**
2. **Completely close Cursor** (check Task Manager - kill all `Cursor.exe` processes)
3. **Wait 10 seconds**
4. **Reopen Cursor**
5. **Check the indicator** - should now be green ✅
#### Verify It Works
In Cursor chat, type:
```
List available MCP tools
```
You should see all 6 tools:
- `parse_brd`
- `create_miro_board`
- `export_miro_data`
- `generate_figma_design`
- `select_tech_stack`
- `generate_application`
## 🔴 Red Indicator in Cursor - SOLVED!
### ✅ Solutions Applied
#### 1. **Cleared npx Cache**
Windows cache location: `%LOCALAPPDATA%\npm-cache\_npx`
- This cache can prevent MCP servers from connecting properly
#### 2. **Renamed Server (CRITICAL!)**
Changed from: `aiworkflow` → `aiworkflow-server`
**Why?** Cursor caches MCP server names! When a server has connection issues, Cursor remembers the failure even after you fix it. Renaming bypasses this cache.
#### 3. **Fixed Path Format**
- ❌ Wrong: `C:\\Trimble Projects 2025\\AIWorkflowMCP\\dist\\index.js`
- ✅ Right: `C:/Trimble Projects 2025/AIWorkflowMCP/dist/index.js`
## 🎯 Current Configuration
**File**: `C:\Users\SLAKSHM\.cursor\mcp.json`
```json
{
"mcpServers": {
"aiworkflow-server": {
"command": "node",
"args": [
"C:/Trimble Projects 2025/AIWorkflowMCP/dist/index.js"
],
"env": {}
}
}
}
```
## ✅ Next Steps
1. **Close Cursor Completely**
- Check Task Manager: Kill all `Cursor.exe` processes
2. **Wait 15 seconds**
- Let the system clear any locks
3. **Reopen Cursor**
- Server should now show GREEN indicator
4. **Verify Tools**
In chat, type:
```
List available MCP tools
```
You should see:
- `parse_brd`
- `create_miro_board`
- `export_miro_data`
- `generate_figma_design`
- `select_tech_stack`
- `generate_application`
## 🧪 Manual Server Test
Test the server works:
```powershell
cd "C:\Trimble Projects 2025\AIWorkflowMCP"
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | node dist/index.js
```
Expected output:
```
✨ AIWorkflow MCP Server is running
Available tools: ["parse_brd","create_miro_board","export_miro_data"...]
{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}}...
```
## 🐛 Still Red? Try These
### Option 1: Different Server Name
Change `aiworkflow-server` to something unique like `brd-workflow-2024`
### Option 2: Full Node Path
```json
{
"command": "C:/Program Files/nodejs/node.exe",
"args": ["C:/Trimble Projects 2025/AIWorkflowMCP/dist/index.js"]
}
```
### Option 3: Check Cursor Developer Console
1. **Help → Toggle Developer Tools**
2. **Console tab**
3. Filter by "MCP" or "aiworkflow"
4. Look for error messages
### Option 4: Rebuild Server
```powershell
cd "C:\Trimble Projects 2025\AIWorkflowMCP"
npm run build
```
## 📋 Common Issues & Solutions
| Issue | Solution |
|-------|----------|
| Red indicator persists | Rename server in config |
| "Cannot find module" | Run `npm install` |
| "node not found" | Add Node.js to PATH |
| Tools not showing | Restart Cursor completely |
| Server won't start | Check logs: `logs/error.log` |
## ✨ Server Status: WORKING
The server has been **tested and confirmed working**:
- ✅ Starts correctly
- ✅ Returns 6 tools
- ✅ Responds to MCP protocol
- ✅ All tools functional
The issue is **only** Cursor's configuration/cache - not the server itself!
## 🆘 Last Resort
If nothing works:
1. **Delete Cursor's MCP cache**:
```powershell
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\User\globalStorage\*mcp*"
```
2. **Reinstall Cursor** (latest version)
3. **Contact Support**: Share this file + logs from `logs/combined.log`
## 📝 Changes Made
1. Cleared npx cache
2. Changed server name: `aiworkflow` → `aiworkflow-server`
3. Fixed path format (forward slashes)
4. Verified server works manually
**Date**: 2025-10-24