VIBN Frontend for Coolify deployment
This commit is contained in:
336
MCP_API_KEYS_GUIDE.md
Normal file
336
MCP_API_KEYS_GUIDE.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 🔑 MCP API Keys for ChatGPT Integration
|
||||
|
||||
## ✅ Non-Expiring API Keys - Complete!
|
||||
|
||||
I've built a complete system for **non-expiring API keys** that users can generate directly in the Vibn UI to connect ChatGPT.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 How It Works
|
||||
|
||||
### **1. User Visits Connections Page**
|
||||
**URL:** `https://vibnai.com/your-workspace/connections`
|
||||
|
||||
### **2. Generate API Key**
|
||||
- Click **"Generate MCP API Key"** button
|
||||
- System creates a unique, long-lived key: `vibn_mcp_abc123...`
|
||||
- Key is stored in Firestore (`mcpKeys` collection)
|
||||
- **Key never expires** until explicitly revoked
|
||||
|
||||
### **3. Copy Settings to ChatGPT**
|
||||
- Click **"Copy All Settings"** button
|
||||
- Paste into ChatGPT's "New Connector" form
|
||||
- Done! ChatGPT can now access Vibn data
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ What I Built
|
||||
|
||||
### **1. API Key Generation Endpoint**
|
||||
**File:** `app/api/mcp/generate-key/route.ts`
|
||||
|
||||
```typescript
|
||||
POST /api/mcp/generate-key
|
||||
- Generates: vibn_mcp_{64-character-hex}
|
||||
- Stores in Firestore with userId
|
||||
- Returns existing key if one already exists
|
||||
```
|
||||
|
||||
```typescript
|
||||
DELETE /api/mcp/generate-key
|
||||
- Revokes user's MCP API key
|
||||
- Removes from Firestore
|
||||
- Forces ChatGPT to disconnect
|
||||
```
|
||||
|
||||
### **2. Updated MCP API to Accept API Keys**
|
||||
**File:** `app/api/mcp/route.ts`
|
||||
|
||||
The MCP endpoint now accepts **two types** of authentication:
|
||||
|
||||
**Option A: MCP API Key** (for ChatGPT)
|
||||
```bash
|
||||
Authorization: Bearer vibn_mcp_abc123...
|
||||
```
|
||||
|
||||
**Option B: Firebase ID Token** (for direct user access)
|
||||
```bash
|
||||
Authorization: Bearer eyJhbGciOiJSUzI1Ni...
|
||||
```
|
||||
|
||||
### **3. UI Component for Key Management**
|
||||
**File:** `components/mcp-connection-card.tsx`
|
||||
|
||||
Features:
|
||||
- ✅ Generate API key button
|
||||
- ✅ Show/hide key toggle
|
||||
- ✅ Copy individual settings
|
||||
- ✅ **Copy all settings** button (one-click setup!)
|
||||
- ✅ Setup instructions
|
||||
- ✅ Revoke key with confirmation dialog
|
||||
|
||||
### **4. Integrated into Connections Page**
|
||||
**File:** `app/[workspace]/connections/page.tsx`
|
||||
|
||||
The MCP connection card is now live on the Connections page, replacing the old placeholder.
|
||||
|
||||
### **5. Firestore Security Rules**
|
||||
**File:** `firestore.rules`
|
||||
|
||||
```javascript
|
||||
match /mcpKeys/{keyId} {
|
||||
// Only server can manage keys via Admin SDK
|
||||
// Users can't directly access or modify
|
||||
allow read, write: if false;
|
||||
}
|
||||
```
|
||||
|
||||
**Deployed:** ✅ Rules are live in production
|
||||
|
||||
---
|
||||
|
||||
## 📋 User Flow (Step-by-Step)
|
||||
|
||||
### **From Vibn:**
|
||||
|
||||
1. User goes to: `/your-workspace/connections`
|
||||
2. Scrolls to "ChatGPT Integration (MCP)" card
|
||||
3. Clicks: **"Generate MCP API Key"**
|
||||
4. Waits 1-2 seconds
|
||||
5. Sees:
|
||||
- MCP Server URL: `https://vibnai.com/api/mcp`
|
||||
- API Key: `vibn_mcp_...` (hidden by default)
|
||||
6. Clicks: **"Copy All Settings"**
|
||||
7. Toast: "All settings copied! Paste into ChatGPT"
|
||||
|
||||
### **To ChatGPT:**
|
||||
|
||||
1. User opens ChatGPT
|
||||
2. Goes to: **Settings → Personalization → Custom Tools**
|
||||
3. Clicks: **"Add New Connector"**
|
||||
4. Pastes settings from clipboard:
|
||||
```
|
||||
Name: Vibn
|
||||
Description: Access your Vibn coding projects...
|
||||
MCP Server URL: https://vibnai.com/api/mcp
|
||||
Authentication: Bearer
|
||||
API Key: vibn_mcp_abc123...
|
||||
```
|
||||
5. Checks: **"I understand and want to continue"**
|
||||
6. Clicks: **"Create"**
|
||||
7. Done! ✅
|
||||
|
||||
### **Test It:**
|
||||
|
||||
User asks ChatGPT:
|
||||
- "Show me my Vibn projects"
|
||||
- "What are my recent coding sessions?"
|
||||
- "How much have I spent on AI?"
|
||||
|
||||
ChatGPT uses the MCP API key to fetch data and respond!
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Features
|
||||
|
||||
### **API Key Format:**
|
||||
```
|
||||
vibn_mcp_{64-character-hex-string}
|
||||
```
|
||||
|
||||
**Example:** `vibn_mcp_a1b2c3d4e5f6...` (72 chars total)
|
||||
|
||||
### **Storage:**
|
||||
```javascript
|
||||
// Firestore: mcpKeys collection
|
||||
{
|
||||
userId: "firebase-user-id",
|
||||
key: "vibn_mcp_abc123...",
|
||||
type: "mcp",
|
||||
createdAt: "2024-11-14T...",
|
||||
lastUsed: "2024-11-14T..." // Updated on each use
|
||||
}
|
||||
```
|
||||
|
||||
### **Authentication Flow:**
|
||||
|
||||
```
|
||||
ChatGPT Request
|
||||
↓
|
||||
POST /api/mcp
|
||||
Authorization: Bearer vibn_mcp_abc123...
|
||||
↓
|
||||
Check if token starts with "vibn_mcp_"
|
||||
↓
|
||||
Query Firestore: mcpKeys.where('key', '==', token)
|
||||
↓
|
||||
Extract userId from key doc
|
||||
↓
|
||||
Update lastUsed timestamp
|
||||
↓
|
||||
Process MCP request with userId context
|
||||
↓
|
||||
Return data to ChatGPT
|
||||
```
|
||||
|
||||
### **Security Rules:**
|
||||
- ✅ Users can't directly read their key from Firestore
|
||||
- ✅ Keys are only accessible via Admin SDK (server-side)
|
||||
- ✅ Keys are scoped to a single user
|
||||
- ✅ All MCP queries filter by userId
|
||||
- ✅ Keys can be revoked instantly
|
||||
|
||||
---
|
||||
|
||||
## 🆚 Comparison: Old vs New
|
||||
|
||||
### **Old Way (Manual):**
|
||||
❌ User needs to run console commands
|
||||
❌ Firebase ID token expires every 1 hour
|
||||
❌ User must regenerate token constantly
|
||||
❌ Poor user experience
|
||||
|
||||
### **New Way (API Keys):**
|
||||
✅ User clicks a button
|
||||
✅ Key never expires
|
||||
✅ One-time setup
|
||||
✅ Can be revoked anytime
|
||||
✅ Great user experience
|
||||
|
||||
---
|
||||
|
||||
## 📊 Database Schema
|
||||
|
||||
### **mcpKeys Collection:**
|
||||
```typescript
|
||||
{
|
||||
userId: string; // Firebase user ID
|
||||
key: string; // vibn_mcp_{hex}
|
||||
type: string; // "mcp"
|
||||
createdAt: string; // ISO timestamp
|
||||
lastUsed: string | null; // ISO timestamp or null
|
||||
}
|
||||
```
|
||||
|
||||
### **Indexes:**
|
||||
```javascript
|
||||
// Compound index on 'key' (for fast lookup during auth)
|
||||
mcpKeys: {
|
||||
key: "ascending"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing
|
||||
|
||||
### **1. Generate Key:**
|
||||
```bash
|
||||
# From browser console (when logged in):
|
||||
const token = await firebase.auth().currentUser.getIdToken();
|
||||
const response = await fetch('/api/mcp/generate-key', {
|
||||
method: 'POST',
|
||||
headers: { 'Authorization': `Bearer ${token}` }
|
||||
});
|
||||
const data = await response.json();
|
||||
console.log(data.apiKey);
|
||||
```
|
||||
|
||||
### **2. Test API with Key:**
|
||||
```bash
|
||||
curl -X POST https://vibnai.com/api/mcp \
|
||||
-H "Authorization: Bearer vibn_mcp_YOUR_KEY" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"action": "list_resources"}'
|
||||
```
|
||||
|
||||
### **3. Revoke Key:**
|
||||
```bash
|
||||
const token = await firebase.auth().currentUser.getIdToken();
|
||||
await fetch('/api/mcp/generate-key', {
|
||||
method: 'DELETE',
|
||||
headers: { 'Authorization': `Bearer ${token}` }
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Benefits
|
||||
|
||||
### **For Users:**
|
||||
- ✅ No technical knowledge required
|
||||
- ✅ One-click copy/paste setup
|
||||
- ✅ Keys never expire (set and forget)
|
||||
- ✅ Clear revocation if needed
|
||||
- ✅ Visual feedback (show/hide key)
|
||||
|
||||
### **For ChatGPT:**
|
||||
- ✅ Stable, long-lived authentication
|
||||
- ✅ Fast key validation (Firestore lookup)
|
||||
- ✅ Automatic last-used tracking
|
||||
- ✅ User-scoped data access
|
||||
|
||||
### **For Vibn:**
|
||||
- ✅ No Firebase ID token management
|
||||
- ✅ Simple key rotation if needed
|
||||
- ✅ Usage analytics (lastUsed field)
|
||||
- ✅ Better security posture
|
||||
|
||||
---
|
||||
|
||||
## 📝 Files Modified/Created
|
||||
|
||||
### **New Files:**
|
||||
```
|
||||
app/api/mcp/generate-key/route.ts ← Key generation/revocation API
|
||||
components/mcp-connection-card.tsx ← UI component for key management
|
||||
MCP_API_KEYS_GUIDE.md ← This file
|
||||
```
|
||||
|
||||
### **Modified Files:**
|
||||
```
|
||||
app/api/mcp/route.ts ← Now accepts MCP API keys
|
||||
app/[workspace]/connections/page.tsx ← Integrated MCP card
|
||||
firestore.rules ← Added mcpKeys rules
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 What's Live
|
||||
|
||||
✅ **API Key Generation:** `/api/mcp/generate-key`
|
||||
✅ **API Key Authentication:** `/api/mcp`
|
||||
✅ **UI for Key Management:** `/your-workspace/connections`
|
||||
✅ **Firestore Rules:** Deployed to production
|
||||
✅ **Security:** Keys are server-side only
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Result
|
||||
|
||||
**Users can now:**
|
||||
1. Generate a non-expiring API key in 1 click
|
||||
2. Copy all settings in 1 click
|
||||
3. Paste into ChatGPT's connector form
|
||||
4. Connect ChatGPT to their Vibn data
|
||||
5. Never worry about token expiration
|
||||
|
||||
**No console commands. No manual token refresh. Just works!** ✨
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Future Enhancements
|
||||
|
||||
Potential additions:
|
||||
- [ ] Multiple MCP keys per user (for different AI assistants)
|
||||
- [ ] Key usage analytics dashboard
|
||||
- [ ] Automatic key rotation (optional)
|
||||
- [ ] Scoped keys (read-only vs full access)
|
||||
- [ ] Key expiration dates (optional)
|
||||
|
||||
---
|
||||
|
||||
**Built and ready to use!** 🚀
|
||||
|
||||
Visit: `https://vibnai.com/your-workspace/connections` to try it now!
|
||||
|
||||
Reference in New Issue
Block a user