@basicsu/courses-mcp/README.md

Interactive programming courses from Basics - MCP server for Cursor

# @basicsu/courses-mcp

Access interactive programming courses from Basics directly in your Cursor IDE using the Model Context Protocol (MCP).

## ✨ Zero Configuration Required!

**Just install and use** - no API keys, no environment variables, no setup needed!

The MCP server includes built-in publishable keys that are safe to use. These keys are protected by Row Level Security (RLS) in Supabase, ensuring users can only access appropriate course content.

## 🚀 Quick Setup

### Method 1: Full NPX Path (Recommended)

1. Find your full NPX path:
   ```bash
   which npx
   ```

2. Add to your Cursor MCP settings:
   ```json
   {
     "mcpServers": {
       "basics-courses": {
         "command": "/opt/homebrew/bin/npx",
         "args": ["@basicsu/courses-mcp@latest"]
       }
     }
   }
   ```

### Method 2: Direct Node (Most Reliable)

1. Install globally:
   ```bash
   npm install -g @basicsu/courses-mcp@latest
   ```

2. Find your paths:
   ```bash
   which node
   npm root -g
   ```

3. Add to your Cursor MCP settings:
   ```json
   {
     "mcpServers": {
       "basics-courses": {
         "command": "/opt/homebrew/bin/node",
         "args": ["/opt/homebrew/lib/node_modules/@basicsu/courses-mcp/dist/stdio.js"]
       }
     }
   }
   ```

## 📚 Usage

1. **Get your auth code** from [basicsu.com/settings/account](https://basicsu.com/settings/account)
2. **Restart Cursor** completely
3. **Switch to Agent mode** (not Composer)
4. **Start learning**:
   - `"Please use the startBasics tool to help me learn programming"`
   - `"Please use startBasics to start the mastra course"`
   - `"Please use nextBasicsCourseStep to continue"`
   - `"Please use getBasicsCourseStatus to check my progress"`

## 🔧 Available Tools

- **`startBasics`** - Authenticate and start courses
- **`nextBasicsCourseStep`** - Continue to next step
- **`getBasicsCourseStatus`** - Check your progress
- **`startBasicsCourseLesson`** - Jump to specific lesson
- **`clearBasicsCourseHistory`** - Reset course progress

## 🐛 Troubleshooting "Zero Tools Available"

### Most Common Issue: Cursor can't find `npx`

**Solution**: Use full paths instead of relative commands.

### Why This Happens
- Cursor's GUI environment doesn't inherit your shell's PATH
- `npx` isn't found, causing `spawn npx ENOENT` errors
- Server appears connected but tools never register

### Debugging Steps
1. **Test manually**: Run `npx @basicsu/courses-mcp@1.1.38` in terminal
2. **Check paths**: Run `which node` and `which npx`
3. **Use Agent mode**: Switch to Agent mode in Cursor
4. **Restart fully**: Close Cursor completely and reopen
5. **Verify tools**: Should see 5 tools listed (not just green connection)

### Common Paths by System
- **Mac (Homebrew)**: `/opt/homebrew/bin/npx`, `/opt/homebrew/bin/node`
- **Mac (Node.js)**: `/usr/local/bin/npx`, `/usr/local/bin/node`
- **Linux**: `/usr/bin/npx`, `/usr/bin/node`
- **Windows**: `C:\\Program Files\\nodejs\\npx.cmd`

## 🔐 Authentication

1. Visit [basicsu.com/settings/account](https://basicsu.com/settings/account)
2. Copy your MCP Auth Code
3. When prompted in Cursor, provide:
   - Your email address
   - Your auth code
4. Progress is automatically synced with your account

## 📞 Support

- **Website**: [basicsu.com](https://basicsu.com)
- **Documentation**: [basicsu.com/docs](https://basicsu.com/docs)
- **GitHub Issues**: [Report bugs and issues](https://github.com/basicsu/basicsu-courses-mcp/issues)

## License

MIT © Basics Team