qeek-mcp-beta 1.0.0

package/README.md

@@ -0,0 +1,128 @@
+# Qeek MCP
+
+📋 **Access your Qeek briefs directly in Cursor and Windsurf**
+
+Say "work on brief id: xxx" and instantly load all your product specs, technical specs, UI mockups, and diagrams into your AI assistant.
+
+## 🚀 Quick Start
+
+### 1. Install & Setup
+
+```bash
+npx qeek-mcp setup
+```
+
+This will:
+- Prompt you for your Qeek API token
+- Save configuration to `~/.qeek/config.json`
+- Auto-configure Cursor (`~/.cursor/mcp.json`)
+- Auto-configure Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+### 2. Get Your Token
+
+1. Go to https://app.qeek.ai/settings/api-tokens
+2. Generate a new token (starts with `qek_live_`)
+3. Paste it during setup
+
+### 3. Use It
+
+In Cursor or Windsurf, simply type:
+
+```
+work on brief id: architect-1234567890-abcdef
+```
+
+The MCP tool will automatically load all specs from that brief as context.
+
+## 🎯 How It Works
+
+```
+┌─────────────────┐      ┌──────────────┐      ┌─────────────────┐
+│   Cursor IDE    │◄────►│  qeek-mcp    │◄────►│  api.qeek.ai    │
+│   or Windsurf   │stdio │  (npx)       │HTTPS │  /internal/briefs │
+└─────────────────┘      └──────────────┘      └─────────────────┘
+```
+
+## 📋 Features
+
+- **One-command context loading** — All specs from your brief
+- **Multi-type support** — Product, technical, UI mockups, diagrams
+- **Smart formatting** — Organized markdown with clear sections
+- **IDE integration** — Works with Cursor and Windsurf
+- **Token-based auth** — Simple, secure, no OAuth redirects
+
+## 🔧 Manual Configuration
+
+If automatic setup doesn't work, manually add to your MCP config:
+
+### Cursor (`~/.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "qeek": {
+      "command": "npx",
+      "args": ["-y", "qeek-mcp"]
+    }
+  }
+}
+```
+
+### Windsurf (`~/.codeium/windsurf/mcp_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "qeek": {
+      "command": "npx",
+      "args": ["-y", "qeek-mcp"]
+    }
+  }
+}
+```
+
+## 📝 Usage Examples
+
+**Load a brief:**
+```
+work on brief id: architect-1234567890-abcdef
+```
+
+**With additional context:**
+```
+work on brief id: architect-1234567890-abcdef, I need to implement the authentication flow
+```
+
+## 🐛 Troubleshooting
+
+### "Qeek MCP not configured"
+
+Run setup again:
+```bash
+npx qeek-mcp setup
+```
+
+### "Invalid API token"
+
+1. Go to https://app.qeek.ai/settings/api-tokens
+2. Generate a new token
+3. Re-run setup
+
+### "Brief not found"
+
+- Verify the brief ID is correct
+- Ensure you have access to that brief in the Qeek UI
+
+## 🔒 Security
+
+- Token stored only in `~/.qeek/config.json` on your machine
+- Never transmitted except to official Qeek API
+- Token can be revoked at any time in Qeek UI
+
+## 📄 License
+
+MIT License - see LICENSE for details.
+
+---
+
+**Built with ❤️ by the Qeek team**

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "qeek-mcp-beta",
+  "version": "1.0.0",
+  "description": "Qeek MCP server for Cursor and Windsurf - Access your briefs directly in your IDE",
+  "main": "src/server.js",
+  "bin": {
+    "qeek-mcp": "./src/server.js",
+    "qeek-mcp-setup": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "setup": "node src/cli.js"
+  },
+  "keywords": ["mcp", "cursor", "windsurf", "qeek", "briefs", "specs"],
+  "author": "Qeek",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { saveConfig } = require('./config');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+async function setup() {
+  console.log('\n🔑 Qeek MCP Setup');
+  console.log('==================\n');
+  console.log('1. Go to: https://app.qeek.ai/settings/api-tokens');
+  console.log('2. Generate a new token');
+  console.log('3. Paste it below:\n');
+
+  const token = await new Promise(resolve => {
+    rl.question('Token: ', resolve);
+  });
+
+  if (!token.startsWith('qek_live_')) {
+    console.log('\n⚠️  Warning: Token should start with "qek_live_"');
+  }
+
+  // Save config
+  saveConfig({
+    version: 1,
+    token: token.trim(),
+    apiUrl: 'https://api.qeek.ai',
+    createdAt: new Date().toISOString()
+  });
+
+  // Configure Cursor
+  await configureCursor();
+  
+  // Configure Windsurf
+  await configureWindsurf();
+
+  console.log('\n✅ Setup complete!');
+  console.log('Use: "work on brief id: <brief-id>" in Cursor/Windsurf\n');
+  
+  rl.close();
+}
+
+async function configureCursor() {
+  const cursorDir = path.join(os.homedir(), '.cursor');
+  const mcpConfigPath = path.join(cursorDir, 'mcp.json');
+  
+  let config = {};
+  if (fs.existsSync(mcpConfigPath)) {
+    config = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'));
+  }
+
+  config.mcpServers = config.mcpServers || {};
+  config.mcpServers.qeek = {
+    command: 'npx',
+    args: ['-y', 'qeek-mcp']
+  };
+
+  if (!fs.existsSync(cursorDir)) {
+    fs.mkdirSync(cursorDir, { recursive: true });
+  }
+
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(config, null, 2));
+  console.log('✓ Cursor MCP config updated');
+}
+
+async function configureWindsurf() {
+  const windsurfDir = path.join(os.homedir(), '.codeium', 'windsurf');
+  const mcpConfigPath = path.join(windsurfDir, 'mcp_config.json');
+  
+  let config = {};
+  if (fs.existsSync(mcpConfigPath)) {
+    config = JSON.parse(fs.readFileSync(mcpConfigPath, 'utf8'));
+  }
+
+  config.mcpServers = config.mcpServers || {};
+  config.mcpServers.qeek = {
+    command: 'npx',
+    args: ['-y', 'qeek-mcp']
+  };
+
+  if (!fs.existsSync(windsurfDir)) {
+    fs.mkdirSync(windsurfDir, { recursive: true });
+  }
+
+  fs.writeFileSync(mcpConfigPath, JSON.stringify(config, null, 2));
+  console.log('✓ Windsurf MCP config updated');
+}
+
+if (require.main === module) {
+  setup().catch(console.error);
+}
+
+module.exports = { setup };

package/src/config.js

@@ -0,0 +1,40 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const CONFIG_DIR = path.join(os.homedir(), '.qeek');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    throw new Error(
+      'Qeek MCP not configured. Run: npx qeek-mcp setup\n' +
+      'Get your token at: https://app.qeek.ai/settings/api-tokens'
+    );
+  }
+
+  const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  
+  return {
+    token: config.token,
+    apiUrl: config.apiUrl || 'https://api.qeek.ai'
+  };
+}
+
+function saveConfig(config) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+  
+  // Ensure permissions even if umask interfered
+  try {
+    fs.chmodSync(CONFIG_FILE, 0o600);
+    fs.chmodSync(CONFIG_DIR, 0o700);
+  } catch (e) {
+    // Ignore permission errors on Windows or restricted environments
+  }
+}
+
+module.exports = { loadConfig, saveConfig, CONFIG_DIR };

package/src/server.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * Qeek MCP Server - Brief Context Tool
+ * 
+ * This script creates an MCP-compatible server that provides the getBriefContext tool
+ * for loading Qeek brief specs into Cursor/Windsurf.
+ */
+
+// Handle setup command
+if (process.argv[2] === 'setup') {
+  const { setup } = require('./cli.js');
+  setup().then(() => process.exit(0)).catch(err => {
+    console.error('Setup failed:', err);
+    process.exit(1);
+  });
+  return; // Prevent falling through to server startup
+}
+
+const { loadConfig } = require('./config');
+const { getBriefContext } = require('./tools/getBriefContext');
+
+const config = loadConfig();
+
+const tools = [
+  {
+    name: 'getBriefContext',
+    description: '📋 Load all specs (product, tech, UI mockups, diagrams) from a Qeek brief. Use when user says "work on brief id: xxx" or "load brief xxx".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        briefId: {
+          type: 'string',
+          description: 'The brief/chat session ID (e.g., "architect-1234567890-abcdef")'
+        }
+      },
+      required: ['briefId']
+    }
+  }
+];
+
+function sendResponse(response) {
+  console.log(JSON.stringify(response));
+}
+
+async function handleRequest(request) {
+  try {
+    const parsed = typeof request === 'string' ? JSON.parse(request) : request;
+    
+    // Handle notifications (no id field) - don't send response
+    if (parsed.id === undefined) {
+      // Log notifications for debugging but don't respond
+      if (parsed.method?.startsWith('notifications/')) {
+        console.error(`📨 Notification: ${parsed.method}`);
+      }
+      return;
+    }
+    
+    switch (parsed.method) {
+      case 'initialize':
+        sendResponse({
+          jsonrpc: '2.0',
+          id: parsed.id,
+          result: {
+            protocolVersion: '2024-11-05',
+            capabilities: {
+              tools: {}
+            },
+            serverInfo: {
+              name: 'qeek-mcp',
+              version: '1.0.0',
+              description: '📋 Load Qeek brief specs into your IDE'
+            }
+          }
+        });
+        break;
+        
+      case 'tools/list':
+        sendResponse({
+          jsonrpc: '2.0',
+          id: parsed.id,
+          result: { tools }
+        });
+        break;
+        
+      case 'tools/call':
+        const { name, arguments: args } = parsed.params;
+        
+        if (name === 'getBriefContext') {
+          const result = await getBriefContext(args.briefId, config);
+          sendResponse({
+            jsonrpc: '2.0',
+            id: parsed.id,
+            result
+          });
+        } else {
+          sendResponse({
+            jsonrpc: '2.0',
+            id: parsed.id,
+            error: {
+              code: -32601,
+              message: `Unknown tool: ${name}`
+            }
+          });
+        }
+        break;
+        
+      default:
+        sendResponse({
+          jsonrpc: '2.0',
+          id: parsed.id,
+          error: {
+            code: -32601,
+            message: `Unknown method: ${parsed.method}`
+          }
+        });
+    }
+  } catch (error) {
+    sendResponse({
+      jsonrpc: '2.0',
+      error: {
+        code: -32700,
+        message: 'Parse error',
+        data: error.message
+      }
+    });
+  }
+}
+
+function start() {
+  console.error('🚀 Qeek MCP Server starting...');
+  console.error('📋 Tool: getBriefContext');
+  console.error('📡 MCP Server ready - listening for requests...');
+
+  process.stdin.setEncoding('utf8');
+  
+  // Buffer for handling partial messages
+  let buffer = '';
+  
+  process.stdin.on('data', (data) => {
+    buffer += data;
+    
+    // Process complete lines from buffer
+    let newlineIndex;
+    while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.substring(0, newlineIndex).trim();
+      buffer = buffer.substring(newlineIndex + 1);
+      
+      if (line) {
+        handleRequest(line);
+      }
+    }
+  });
+
+  process.stdin.on('end', () => {
+    // Process any remaining data in buffer
+    const remaining = buffer.trim();
+    if (remaining) {
+      handleRequest(remaining);
+    }
+    process.exit(0);
+  });
+
+  process.on('SIGINT', () => process.exit(0));
+  process.on('SIGTERM', () => process.exit(0));
+}
+
+start();
+

package/src/tools/getBriefContext.js

@@ -0,0 +1,126 @@
+async function getBriefContext(briefId, config) {
+  console.error(`📋 Loading brief: ${briefId}`);
+
+  try {
+    const response = await fetch(`${config.apiUrl}/internal/briefs/${briefId}`, {
+      headers: {
+        'Authorization': `Bearer ${config.token}`,
+        'Content-Type': 'application/json'
+      }
+    });
+
+    if (response.status === 401) {
+      return {
+        content: [{
+          type: 'text',
+          text: '❌ Invalid API token.\n\nPlease run: `npx qeek-mcp setup`\nGet a new token at: https://app.qeek.ai/settings/api-tokens'
+        }],
+        isError: true
+      };
+    }
+
+    if (response.status === 404) {
+      return {
+        content: [{
+          type: 'text',
+          text: `❌ Brief not found: ${briefId}\n\nPlease verify the brief ID is correct.`
+        }],
+        isError: true
+      };
+    }
+
+    if (!response.ok) {
+      throw new Error(`API error: ${response.status}`);
+    }
+
+    const brief = await response.json();
+    const markdown = formatBriefAsMarkdown(brief);
+
+    console.error(`✅ Loaded brief with ${brief.specs?.length || 0} specs`);
+
+    return {
+      content: [{ type: 'text', text: markdown }],
+      structuredContent: {
+        briefId: brief.id,
+        title: brief.title,
+        projectId: brief.projectId,
+        repositoryNames: brief.repositoryNames,
+        specCounts: countSpecsByType(brief.specs)
+      }
+    };
+
+  } catch (error) {
+    console.error('❌ Error:', error.message);
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ Error loading brief: ${error.message}`
+      }],
+      isError: true
+    };
+  }
+}
+
+function formatBriefAsMarkdown(brief) {
+  let md = `# 📋 Brief: ${brief.title}\n\n`;
+  md += `**ID:** \`${brief.id}\`\n`;
+  md += `**Project:** ${brief.projectId}\n`;
+  md += `**Repos:** ${brief.repositoryNames?.join(', ') || 'None'}\n\n`;
+  md += `---\n\n`;
+
+  // Group and format specs
+  const specs = brief.specs || [];
+  
+  const productSpecs = specs.filter(s => s.specType === 'product');
+  const techSpecs = specs.filter(s => s.specType === 'tech');
+  const uiSpecs = specs.filter(s => s.specType === 'ui');
+  const diagramSpecs = specs.filter(s => s.specType === 'diagram');
+  const customSpecs = specs.filter(s => s.specType === 'custom');
+
+  if (productSpecs.length) {
+    md += `## 📖 Product Specs\n\n`;
+    productSpecs.forEach(s => {
+      md += `### ${s.title}\n\n${s.content}\n\n---\n\n`;
+    });
+  }
+
+  if (techSpecs.length) {
+    md += `## ⚙️ Technical Specs\n\n`;
+    techSpecs.forEach(s => {
+      md += `### ${s.title}\n\n${s.content}\n\n---\n\n`;
+    });
+  }
+
+  if (uiSpecs.length) {
+    md += `## 🎨 UI Mockups\n\n`;
+    uiSpecs.forEach(s => {
+      md += `### ${s.title}\n\n${s.content}\n\n---\n\n`;
+    });
+  }
+
+  if (diagramSpecs.length) {
+    md += `## 📊 Diagrams\n\n`;
+    diagramSpecs.forEach(s => {
+      md += `### ${s.title}\n\n${s.content}\n\n---\n\n`;
+    });
+  }
+
+  if (customSpecs.length) {
+    md += `## 📝 Custom Specs\n\n`;
+    customSpecs.forEach(s => {
+      md += `### ${s.title}\n\n${s.content}\n\n---\n\n`;
+    });
+  }
+
+  return md;
+}
+
+function countSpecsByType(specs) {
+  const counts = { product: 0, tech: 0, ui: 0, diagram: 0, custom: 0 };
+  (specs || []).forEach(s => {
+    counts[s.specType] = (counts[s.specType] || 0) + 1;
+  });
+  return counts;
+}
+
+module.exports = { getBriefContext };