architectgbt-mcp 0.2.4 → 0.3.0

package/README.md

@@ -7,6 +7,18 @@ Get instant AI model recommendations for your projects directly in Cursor IDE or
 [![npm version](https://img.shields.io/npm/v/architectgbt-mcp.svg)](https://www.npmjs.com/package/architectgbt-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+## Quick Start (No Signup Required!)
+
+**Just run it** - no API key, no signup, no configuration:
+
+```bash
+npx -y architectgbt-mcp
+```
+
+You get **3 free recommendations per day** instantly. Perfect for trying it out!
+
+Want unlimited? [Upgrade to Pro](#pricing) ($15/month) and add an API key.
+
 ## Features
 
 ### 🎯 AI Model Recommendations
@@ -30,9 +42,14 @@ Get instant AI model recommendations for your projects directly in Cursor IDE or
 
 ## Installation
 
-### Cursor IDE
+### Option 1: Anonymous (Free, No Setup)
+
+**Works immediately** - no configuration, no API key, no signup:
+
+#### Cursor IDE
 
 1. Create `.cursor/mcp.json` in your project:
+
 ```json
 {
   "mcpServers": {
@@ -45,17 +62,16 @@ Get instant AI model recommendations for your projects directly in Cursor IDE or
 ```
 
 2. Restart Cursor
+3. Ask Claude: "Recommend an AI model for my chatbot"
+4. ✅ **Works instantly** - 3 free recommendations/day
 
-3. Ask Claude:
-   - "Recommend an AI model for a customer support chatbot"
-   - "Show me all available AI models"
-   - "Give me Claude Sonnet code in TypeScript"
-
-### Claude Desktop
+#### Claude Desktop
 
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+1. **Open config:**
+   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+2. **Add this:**
 
 ```json
 {
@@ -68,67 +84,128 @@ Get instant AI model recommendations for your projects directly in Cursor IDE or
 }
 ```
 
-### VS Code (with Continue or other MCP extensions)
+3. Restart Claude Desktop
+4. ✅ **Works instantly** - 3 free recommendations/day
+
+---
 
-Install an MCP-compatible extension, then add to settings:
+### Option 2: Pro (Unlimited with API Key)
+
+Want unlimited recommendations? [Upgrade to Pro](https://architectgbt.com/pricing) then:
+
+#### Cursor IDE (Pro)
+
+1. Create `.cursor/mcp.json`:
 
 ```json
 {
-  "mcp.servers": {
+  "mcpServers": {
     "architectgbt": {
       "command": "npx",
-      "args": ["-y", "architectgbt-mcp@latest"]
+      "args": ["-y", "architectgbt-mcp@latest"],
+      "env": {
+        "ARCHITECTGBT_API_KEY": "agbt_your_key_here"
+      }
     }
   }
 }
 ```
 
-### Zed Editor
+2. Get API key from [Settings](https://architectgbt.com/dashboard/settings)
+3. Replace `agbt_your_key_here` with your key
+4. Restart Cursor
+5. ✅ **Unlimited recommendations**
 
-Add to `~/.config/zed/settings.json`:
+#### Claude Desktop (Pro)
+
+1. **Open config:**
+   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+2. **Edit the config:**
 
 ```json
 {
-  "context_servers": {
+  "mcpServers": {
     "architectgbt": {
       "command": "npx",
-      "args": ["-y", "architectgbt-mcp@latest"]
+      "args": ["-y", "architectgbt-mcp@latest"],
+      "env": {
+        "ARCHITECTGBT_API_KEY": "agbt_your_key_here"
+      }
     }
   }
 }
 ```
 
-### Any MCP-Compatible Client
+3. Get API key from [Settings](https://architectgbt.com/dashboard/settings)
+4. Replace `agbt_your_key_here` with your key
+5. Restart Claude Desktop
+6. ✅ **Unlimited recommendations**
 
-This server follows the [Model Context Protocol](https://modelcontextprotocol.io) standard and works with any MCP-compatible client. Run it via stdio:
+5. **Test it** - Look for 🔌 icon in bottom right, then ask:
+   - "Show me all available AI models"
 
-```bash
-npx architectgbt-mcp@latest
-```
+### VS Code (with Continue or other MCP extensions)
 
-### With API Key (Unlimited Access)
+---
 
-Add your API key to any config above:
+### Other Editors
+
+#### VS Code (with Continue extension)
 
 ```json
 {
-  "mcpServers": {
+  "mcp.servers": {
     "architectgbt": {
       "command": "npx",
-      "args": ["-y", "architectgbt-mcp@latest"],
-      "env": {
-        "ARCHITECTGBT_API_KEY": "agbt_your_key_here"
-      }
+      "args": ["-y", "architectgbt-mcp@latest"]
     }
   }
 }
 ```
 
-## Pricing
+**For unlimited:** Add `"env": { "ARCHITECTGBT_API_KEY": "agbt_your_key" }` and [upgrade to Pro](https://architectgbt.com/pricing).
+
+#### Zed Editor
 
-| Tier | Recommendations | Cost | API Key |
-|------|----------------|------|---------|
-| **Free** | 3/day | $0 | Not needed |
+Add to `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "architectgbt": {
+      "command": "npx",
+      "args": ["-y", "architectgbt-mcp@latest"]
+    }
+  }
+}
+```
+
+**For unlimited:** Add `"env": { "ARCHITECTGBT_API_KEY": "agbt_your_key" }` and [upgrade to Pro](https://architectgbt.com/pricing).
+```bash
+npx architectgbt-mcp@latest
+```
+MCP Access | Cost | Setup Required |
+|------|-----------|------|---------------|
+| **Anonymous** | 3/day | $0 | None - works instantly |
+| **Free Account** | 3/day + 10/month web | $0 | Signup only (no API key) |
+| **Pro** | Unlimited | $15-29/month | API key required |
+
+### Free Tier
+- ✅ **No signup needed** - works immediately
+- ✅ **3 recommendations/day** via MCP (IP-based)
+- ✅ **No configuration** - just `npx -y architectgbt-mcp`
+- 📈 Perfect for trying it out!
+
+### Pro Tier
+- ✅ **Unlimited recommendations** (MCP + web app)
+- ✅ **API key access** (up to 5 keys)
+- ✅ **Priority support**
+- ✅ **Advanced features**
+- 💳 [$15-29/month →](https://architectgbt.com/pricing)
+
+**Getting the free tier limit?** [Upgrade to Pro](https://architectgbt.com/pricing) for unlimited access.
 | **Pro** | Unlimited | $15/month | Required |
 
 [Get your API key →](https://architectgbt.com/dashboard/settings)
@@ -178,14 +255,31 @@ Perfect for customer support with fast responses, strong reasoning...
   • Extremely fast (sub-second)
   • Cost-effective at scale
   ...
-```
 
-**Parameters:**
-- `prompt` (required): Your project description
-- `budget` (optional): "low" | "medium" | "high" | "unlimited"
-- `priority` (optional): "cost" | "speed" | "quality" | "balanced"
+**Free tier:** You've used 3 free recommendations today.
+
+**Options:**
+1. ✅ Wait for reset (resets every 24 hours)
+2. 📈 [Upgrade to Pro](https://architectgbt.com/pricing) for unlimited access
+
+### "API Key Invalid" (Pro users)
+
+1. Check key starts with `agbt_`
+2. Regenerate from [Settings](https://architectgbt.com/dashboard/settings)
+3. Make sure it's in the `env` section of your config
+4. Verify you're on a Pro plan
+
+### Not Working at All?
+
+**First time user:**
+- ✅ No API key needed for free tier
+- ✅ Remove the `env` section from config if present
+- ✅ Just use: `"args": ["-y", "architectgbt-mcp@latest"]`
 
-- `language` (required): "typescript" | "python"
+**Pro user:**
+- ❌ Check API key is valid
+- ❌ Ensure you've upgraded to Pro at [architectgbt.com/pricing](https://architectgbt.com/pricing)
+- ❌ Free accounts cannot use API keys
 
 ## Environment Variables
 

package/TESTING.md

@@ -2,56 +2,96 @@
 
 ## Quick Test Guide
 
-### 1. Set Your API Key
+### Option 1: Test Anonymous (No Setup)
+
+**Easiest way** - works immediately:
+
+1. **Configure Cursor IDE** - Create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "architectgbt": {
+      "command": "npx",
+      "args": ["-y", "architectgbt-mcp@latest"]
+    }
+  }
+}
+```
+
+2. **Restart Cursor**
+
+3. **Test it** - Ask Claude:
+   - "Show me all available AI models"
+   - "Recommend an AI model for a chatbot"
+
+✅ **Expected:** Works instantly - 3 free recommendations/day
+
+---
+
+### Option 2: Test with Pro (Unlimited)
+
+**For unlimited access** - requires Pro account:
+
+1. **Upgrade to Pro:** [architectgbt.com/pricing](https://architectgbt.com/pricing)
+
+2. **Get API Key:** [architectgbt.com/dashboard/settings](https://architectgbt.com/dashboard/settings)
+
+3. **Set Environment Variable:**
 
 **Windows (PowerShell):**
 ```powershell
-$env:ARCHITECTGBT_API_KEY = "your_api_key_here"
+$env:ARCHITECTGBT_API_KEY = "agbt_your_key_here"
 ```
 
 **macOS/Linux:**
 ```bash
-export ARCHITECTGBT_API_KEY=your_api_key_here
+export ARCHITECTGBT_API_KEY=agbt_your_key_here
 ```
 
-### 2. Configure Cursor IDE
-
-Create or edit `.cursor/mcp.json` in your project:
+4. **Configure Cursor** - Edit `.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "architectgbt": {
       "command": "npx",
-      "args": ["-y", "architectgbt-mcp@0.2.0"]
+      "args": ["-y", "architectgbt-mcp@latest"],
+      "env": {
+        "ARCHITECTGBT_API_KEY": "agbt_your_key_here"
+      }
     }
   }
 }
 ```
 
-### 3. Restart Cursor
+5. **Restart Cursor**
+
+6. **Test it** - Ask Claude same questions as above
+
+✅ **Expected:** Unlimited recommendations, no daily limits
 
-Close and reopen Cursor IDE to load the MCP server with your API key.
+---
 
-### 4. Test Commands
+## Test Commands
 
-#### Test 1: List Models
+### Test 1: List Models
 Ask Claude in Cursor:
 ```
 Show me all available AI models
 ```
 
-Expected: List of models with pricing
+Expected: List of 50+ models with pricing
 
-#### Test 2: Get Recommendation
+### Test 2: Get Recommendation
 Ask Claude:
 ```
 Recommend an AI model for building a chatbot with 100k daily users and $500/month budget
 ```
 
-Expected: Top 3 model recommendations with cost breakdown
+Expected: Top recommendations with cost breakdown
 
-#### Test 3: Get Template
+### Test 3: Get Template
 Ask Claude:
 ```
 Show me the Next.js SaaS template
@@ -59,66 +99,136 @@ Show me the Next.js SaaS template
 
 Expected: Template code and description
 
-### 5. Verify Unlimited Access
+---
 
-With your API key set:
-- ✅ No rate limits (unlimited recommendations)
-- ✅ Usage tracked in your dashboard
-- ✅ `last_used_at` updates in Settings → API Keys
+## Verify Access Level
 
-### 6. Test Without API Key
+### Anonymous/Free (No API Key)
+- ✅ First 3 requests work
+- ❌ 4th request shows rate limit error
+- ✅ Resets after 24 hours
+- ✅ No signup required
 
-Remove the environment variable:
-```powershell
-Remove-Item Env:\ARCHITECTGBT_API_KEY
-```
-
-Restart Cursor and try again:
-- ✅ First 3 requests work (anonymous tier)
-- ✅ 4th request shows rate limit error
+### Pro (With API Key)
+- ✅ Unlimited requests
+- ✅ No rate limits
+- ✅ Usage tracked in dashboard
+---
 
 ## Troubleshooting
 
-### API Key Not Working
+### Anonymous Not Working
 
-1. **Check environment variable is set:**
+**Common issue:** API key in config but not valid
+
+**Solution:**
+1. Remove the `env` section from `.cursor/mcp.json`
+2. Use just: `"args": ["-y", "architectgbt-mcp@latest"]`
+3. Restart Cursor
+4. ✅ Should work with free tier (3/day)
+
+### API Key Not Working (Pro Users)
+
+1. **Check you've upgraded:**
+   - Free accounts cannot use API keys
+   - [Upgrade to Pro](https://architectgbt.com/pricing)
+
+2. **Verify environment variable:**
    ```powershell
    echo $env:ARCHITECTGBT_API_KEY
    ```
 
-2. **Verify format:**
+3. **Check format:**
    - Must start with `agbt_`
    - Should be 37+ characters long
 
-3. **Check Cursor loaded it:**
-   - Restart Cursor after setting the variable
-   - Check Cursor's MCP logs
+4. **Regenerate key:**
+   - Go to [Settings](https://architectgbt.com/dashboard/settings)
+   - Generate new key
+   - Update config
 
-### MCP Server Not Found
+### MCP Server Not Loading
 
+**Test directly:**
 ```powershell
-# Test MCP server directly
-npx -y architectgbt-mcp@0.2.0
+npx -y architectgbt-mcp@latest
 ```
 
-### Still Getting Rate Limited
+**Common fixes:**
+- Ensure Node.js >= 18.0.0
+- Check internet connection
+- Verify JSON syntax in config
+- Restart Cursor after config changes
+## Troubleshooting
+
+### API Key Not Working
+
+1. **Check environment variable is set:**
+   ```powershell
+   echo $env:ARCHITECTGBT_API_KEY
+   ```
+
+2. **Verify format:**
+   - Must start with `agbt_`
+   - Should be 37+ characters long
+
+---
 
-- Verify API key is in environment variables
-- Check it matches the key in your dashboard
-- Ensure Cursor was restarted after setting the variable
+## Testing Checklist
 
-## Production Testing Checklist
+### Anonymous Tier
+- [ ] Works without signup
+- [ ] Works without API key
+- [ ] First 3 requests succeed
+- [ ] 4th request shows rate limit
+- [ ] Rate limit resets after 24 hours
+- [ ] Error message shows upgrade path
 
-- [ ] Anonymous access works (3/day limit)
+### Pro Tier
+- [ ] Requires Pro subscription
 - [ ] API key provides unlimited access
 - [ ] Usage count increments in dashboard
-- [ ] last_used_at updates after each request
-- [ ] Rate limit resets after 24 hours
-- [ ] All 3 tools work (list_models, get_ai_recommendation, get_template)
+- [ ] `last_used_at` updates after requests
+- [ ] All tools work (list_models, get_ai_recommendation, get_template)
+- [ ] No rate limits
+
+### General
 - [ ] Error messages are user-friendly
-- [ ] MCP works in both Cursor and Claude Desktop
+- [ ] Works in Cursor IDE
+- [ ] Works in Claude Desktop
+- [ ] Handles network errors gracefully
+
+---
+
+## API Endpoints Used
+
+### Anonymous (No API Key)
+- **GET** `https://architectgbt.com/api/models` - Public endpoint
+- **POST** `https://architectgbt.com/api/recommend/public` - Rate limited (3/day)
+
+### Pro (With API Key)
+- **GET** `https://architectgbt.com/api/models` - Public endpoint
+- **POST** `https://architectgbt.com/api/recommend` - Unlimited
+
+**Headers sent:**
+```
+Authorization: Bearer agbt_your_key_here
+Content-Type: application/json
+```
+
+---
+
+## Next Steps
+
+### For Free Users
+1. Try anonymous tier (3/day)
+2. Sign up at [architectgbt.com](https://architectgbt.com) for web access (10/month)
+3. [Upgrade to Pro](https://architectgbt.com/pricing) when ready for unlimited
 
-## API Endpoints Being Used
+### For Pro Users
+1. Monitor usage in [Settings → API Keys](https://architectgbt.com/dashboard/settings)
+2. Generate multiple keys for different projects (max 5)
+3. Share MCP setup with your team
 
 When using MCP with API key:
 - **GET** `https://architectgbt.com/api/models` - List models

package/dist/tools/get-recommendation.js

@@ -34,7 +34,7 @@ export async function handleGetRecommendation(args) {
     const input = InputSchema.parse(args);
     try {
         // Determine which endpoint to use
-        const endpoint = API_KEY ? `${API_BASE}/api/recommend` : `${API_BASE}/api/recommend/public`;
+        const endpoint = API_KEY ? `${API_BASE}/api/recommend` : `${API_BASE}/api/recommend/anonymous`;
         // Build headers
         const headers = {
             "Content-Type": "application/json",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "architectgbt-mcp",
-  "version": "0.2.4",
-  "description": "Model Context Protocol server for ArchitectGBT - AI architecture recommendations",
+  "version": "0.3.0",
+  "description": "Model Context Protocol server for ArchitectGBT - AI model recommendations with zero-friction onboarding",
   "type": "module",
   "bin": {
     "architectgbt-mcp": "./dist/index.js"

package/src/tools/get-recommendation.ts

@@ -41,7 +41,7 @@ export async function handleGetRecommendation(args: unknown) {
 
   try {
     // Determine which endpoint to use
-    const endpoint = API_KEY ? `${API_BASE}/api/recommend` : `${API_BASE}/api/recommend/public`;
+    const endpoint = API_KEY ? `${API_BASE}/api/recommend` : `${API_BASE}/api/recommend/anonymous`;
     
     // Build headers
     const headers: HeadersInit = {