QEEK MCP Assistant

🤖 AI-powered code assistant for QEEK codebases via Model Context Protocol (MCP)

Connect your Cursor, Windsurf, or other MCP-compatible editor to your QEEK Mastra service for intelligent codebase questions and analysis.

🚀 Quick Start

1. Install the Package

npm install -g qeek-mcp-assistant

2. Setup Authentication

npx qeek-mcp-assistant setup

This will:

• Prompt you for your QEEK authentication token
• Save the configuration for future use
• Automatically configure your editor (Cursor/Windsurf)
• Test the connection to verify everything works

3. Start Using It!

Once configured, restart your editor and try prompts like:

• qeek tell me about the tickets functionality
• qeek how does authentication work?
• qeek explain the database schema
• qeek what UI components are available?

🎯 How It Works

The QEEK MCP Assistant:

1. Listens for prompts starting with "qeek"
2. Connects to your production Mastra service
3. Uses semantic search and AI analysis tools
4. Returns comprehensive insights about your codebase

📋 Commands

| Command | Description | |---------|-------------| | npx qeek-mcp-assistant | Start MCP server (default) | | npx qeek-mcp-assistant setup | Configure authentication | | npx qeek-mcp-assistant test | Test API connection | | npx qeek-mcp-assistant mcp | Start MCP server (explicit) |

⚙️ Configuration

Environment Variables

• QEEK_TOKEN - Your QEEK authentication token
• QEEK_API_URL - API endpoint (defaults to production)

Token Setup

You can set your token in several ways:

1. Interactive setup (recommended):

   npx qeek-mcp-assistant setup

2. Environment variable:

   export QEEK_TOKEN="your-token-here"

3. Direct in MCP config:

   {
     "mcpServers": {
       "qeek-assistant": {
         "command": "npx",
         "args": ["qeek-mcp-assistant"],
         "env": {
           "QEEK_TOKEN": "your-token-here"
         },
         "disabled": false
       }
     }
   }

🔧 Troubleshooting

Connection Issues

# Test your connection
npx qeek-mcp-assistant test

Token Problems

# Reconfigure authentication
npx qeek-mcp-assistant setup

MCP Not Working

1. Restart your editor after configuration changes
2. Check the MCP settings in your editor
3. Verify the token with the test command
4. Check the logs in your editor's MCP section

🌐 Mastra Service Integration

This MCP server connects to your QEEK Mastra service which provides:

• Semantic Context Tool - Embeddings-based code search via BigQuery
• Gemini Context Tool - AI-powered repository analysis
• Rich Metadata - Project structure, dependencies, and relationships

📖 Examples

Basic Usage

AI: ## Ticket Functionality Overview

The ticket functionality in QEEK is a comprehensive system for managing tasks, bugs, and feature requests. Here's what I found:

Key Components

• TicketBoard.tsx: Kanban-style board with drag-and-drop
• TicketList.tsx: List view with filtering and search
• TicketModal.tsx: Create/edit tickets with AI assistance
• TicketView.tsx: Detailed view with chat interface

Features

• Real-time updates via Firestore
• AI-generated specifications
• Ticket linking and relationships
• Status tracking (backlog → development → deployment)
• Estimation and planning tools

[Full detailed response would continue...]

### Advanced Usage

You: qeek how does the authentication system work in this codebase?

AI: ## Authentication System Analysis

Based on my analysis of your codebase, here's how authentication works:

Core Components

• AuthContext: React context for user state management
• Firebase Auth: Primary authentication provider
• Account System: Multi-account support with switching

Flow

1. User signs in via Firebase Auth
2. User data stored in Firestore
3. Account context provides current account info
4. Protected routes check authentication status

[Detailed implementation details would follow...]

## ✨ Features

- 🔍 **Semantic Code Search** - Find relevant code using natural language
- 🤖 **AI Analysis** - Get intelligent explanations of your codebase
- 🎯 **Smart Triggering** - Just start your prompt with "qeek"
- 🔐 **Secure Authentication** - Token-based access to your QEEK account
- 📊 **Rich Context** - Understands project structure and relationships
- ⚡ **Real-time** - Direct connection to your Mastra service

## 🔧 Advanced Configuration

### Manual Editor Setup

If automatic configuration doesn't work, you can manually configure your editor:

#### For Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "qeek-assistant": {
      "command": "npx",
      "args": ["qeek-mcp-assistant"],
      "disabled": false
    }
  }
}

For Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "qeek-assistant": {
      "command": "npx",
      "args": ["qeek-mcp-assistant"],
      "disabled": false
    }
  }
}

Custom API Endpoint

{
  "mcpServers": {
    "qeek-assistant": {
      "command": "npx",
      "args": ["qeek-mcp-assistant"],
      "env": {
        "QEEK_API_URL": "https://your-custom-endpoint.com"
      },
      "disabled": false
    }
  }
}

Debug Mode

DEBUG=qeek* npx qeek-mcp-assistant

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT License - see LICENSE for details.

Start exploring your codebase with AI! 🚀

• 🌐 QEEK Website
• 📖 QEEK Documentation
• 🔧 Model Context Protocol
• 💬 Support & Community

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the QEEK team