qeek-mcp-assistant/README.md

QEEK MCP Server - AI assistant for QEEK codebase questions. Connect to your Mastra service via Model Context Protocol.

# 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

```bash
npm install -g qeek-mcp-assistant
```

### 2. Setup Authentication

```bash
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):
   ```bash
   npx qeek-mcp-assistant setup
   ```

2. **Environment variable**:
   ```bash
   export QEEK_TOKEN="your-token-here"
   ```

3. **Direct in MCP config**:
   ```json
   {
     "mcpServers": {
       "qeek-assistant": {
         "command": "npx",
         "args": ["qeek-mcp-assistant"],
         "env": {
           "QEEK_TOKEN": "your-token-here"
         },
         "disabled": false
       }
     }
   }
   ```

## 🔧 Troubleshooting

### Connection Issues

```bash
# Test your connection
npx qeek-mcp-assistant test
```

### Token Problems

```bash
# 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`:

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

### Custom API Endpoint

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

### Debug Mode

```bash
DEBUG=qeek* npx qeek-mcp-assistant
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

---

**Start exploring your codebase with AI! 🚀**

- 🌐 [QEEK Website](https://qeek.ai)
- 📖 [QEEK Documentation](https://docs.qeek.ai)
- 🔧 [Model Context Protocol](https://modelcontextprotocol.io)
- 💬 [Support & Community](https://app.qeek.ai/support)

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

Made with ❤️ by the QEEK team