@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:

   which npx

2. Add to your Cursor MCP settings:

   {
     "mcpServers": {
       "basics-courses": {
         "command": "/opt/homebrew/bin/npx",
         "args": ["@basicsu/courses-mcp@latest"]
       }
     }
   }

Method 2: Direct Node (Most Reliable)

1. Install globally:

   npm install -g @basicsu/courses-mcp@latest

2. Find your paths:

   which node
   npm root -g

3. Add to your Cursor MCP settings:

   {
     "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
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/[email protected] 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
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
• Documentation: basicsu.com/docs
• GitHub Issues: Report bugs and issues

License

MIT © Basics Team