cursor-buddy-mcp

🎯 Why Cursor Buddy MCP?

🧠 Context-Aware AI

Your AI assistant instantly knows your coding standards, architectural patterns, and project conventions

📚 Centralized Knowledge

All project documentation and guidelines in one searchable location

✅ Progress Tracking

Automatic todo management and implementation history tracking

🔄 Real-time Updates

File monitoring ensures your AI always has the latest information

🚀 Zero Setup Friction

Drop-in Docker container with immediate MCP integration

🔍 Intelligent Search

Fast, relevant results across all your project context

📋 Table of Contents

• 🎯 Why Cursor Buddy MCP?
• 🏗️ Architecture
• 🚀 Quick Start
• 🔧 Available Tools
• 💡 Usage Examples
• 📚 Documentation
  • 📋 Rules Files
  • 📖 Knowledge Files
  • ✅ Todo Files
  • 🗄️ Database Files
• 💎 Best Practices
• 🔧 Advanced Features
• 🤝 Contributing

🏗️ Architecture

Built on the Model Context Protocol (MCP) using the Go SDK from mark3labs/mcp-go. Communicates over stdin/stdout using JSON-RPC 2.0, making it compatible with MCP clients like Claude Desktop.

🎨 Features

🚀 Quick Start

1️⃣ Pull from GitHub Registry

docker pull ghcr.io/omar-haris/cursor-buddy-mcp:latest

2️⃣ Configure Cursor

Add to `.cursor/mcp.json`:

> ⚠️ Important: Replace `/path/to/your/project/` with your actual project directory path!

{
  "mcpServers": {
    "cursor-buddy-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/project/.buddy:/home/buddy/.buddy",
        "-e", "BUDDY_PATH=/home/buddy/.buddy",
        "ghcr.io/omar-haris/cursor-buddy-mcp:latest"
      ]
    }
  }
}

Examples:

• Linux/macOS: `"/home/user/myproject/.buddy:/home/buddy/.buddy"`
• Windows: `"C:/Users/User/myproject/.buddy:/home/buddy/.buddy"`
• Current directory: `"${PWD}/.buddy:/home/buddy/.buddy"`

💡 How to find your project path:

# Navigate to your project directory and run:
pwd
# Copy the output and replace /path/to/your/project/ with: {output}/.buddy

3️⃣ Create .buddy Structure

Navigate to your project directory and run:

mkdir -p .buddy/{rules,knowledge,todos,database,history,backups}

📁 This will create:

your-project/
├── .buddy/
│   ├── rules/
│   ├── knowledge/
│   ├── todos/
│   ├── database/
│   ├── history/
│   └── backups/

4️⃣ Add Your Content

Create files in `.buddy/` folders following the documentation below.

🔧 Available Tools

📋 buddy_get_rules

Get coding standards and guidelines

• Filter by category or priority
• Support for multiple rule types

🔍 buddy_search_knowledge

Search project documentation

• Full-text search across all knowledge
• Category and tag filtering

✅ buddy_manage_todos

List/update tasks and track progress

• Feature-based organization
• Progress tracking and completion

🗄️ buddy_get_database_info

Get schema info and validate queries

• Table schema information
• Query validation and examples

📚 buddy_history

Track implementation changes and search history

• Implementation timeline
• Feature development tracking

💾 buddy_backup

Create and manage file backups

• Automatic backup creation
• Safe file modifications

💡 Usage Examples

Ask your AI assistant questions like:

📚 Documentation

📋 Rules Files

> Location: `.buddy/rules/`

> Purpose: Define coding standards, architectural patterns, and guidelines

📝 Format Requirements

• ✅ Use markdown format (`.md`)
• ✅ Include metadata: `category` and `priority`
• ✅ Organize with clear sections and subsections

🔧 Example: Coding Standards

Click to expand coding standards example

# Coding Standards
- category: coding
- priority: critical

## Overview
Core coding standards and best practices for the project.

## Go-Specific Standards
- Follow Go naming conventions (camelCase, PascalCase)
- Use `gofmt` for code formatting
- Handle errors explicitly, don't ignore them
- Use interfaces for abstraction

## Error Handling
- Always check and handle errors
- Use structured error types
- Wrap errors with context using `fmt.Errorf`
- Return meaningful error messages

## Testing
- Write unit tests for all public functions
- Use table-driven tests for multiple test cases
- Achieve minimum 80% code coverage

🏗️ Example: Architecture Patterns

Click to expand architecture patterns example

# Architecture Patterns
- category: architecture
- priority: critical

## Design Principles
- **Single Responsibility**: Each component has one reason to change
- **Dependency Inversion**: Depend on abstractions, not concretions

## Recommended Patterns

### Repository Pattern
- Encapsulate data access logic
- Provide consistent interface for data operations
- Enable easy testing with mock implementations

### Layered Architecture
┌─────────────────────┐
│   Presentation      │  ← HTTP handlers, CLI
├─────────────────────┤
│   Business Logic    │  ← Domain models, use cases
├─────────────────────┤
│   Data Access       │  ← Repositories, databases
└─────────────────────┘

📖 Knowledge Files

> Location: `.buddy/knowledge/`

> Purpose: Store project documentation, API specs, and technical information

📝 Format Requirements

• ✅ Use markdown format (`.md`)
• ✅ Include metadata: `category` and optional `tags`
• ✅ Structure with clear headings and examples

🌐 Example: API Documentation

Click to expand API documentation example

# API Documentation
- category: architecture
- tags: api, rest, authentication

## Authentication Endpoints

### POST /auth/login
**Request:**

{

"email": "user@example.com",

"password": "secure_password"

}

**Response:**

{

"token": "jwt_token_here",

"user": {

"id": 123,

"email": "user@example.com",

"role": "user"

}

}

### GET /auth/me
**Headers:** `Authorization: Bearer `

**Response:**

{

"user": {

"id": 123,

"email": "user@example.com",

"role": "user"

}

}

## Error Handling
All endpoints return errors in this format:

{

"error": "error_code",

"message": "Human readable message"

}

// Code block

✅ Todo Files

> Location: `.buddy/todos/`

> Purpose: Track tasks, features, and project progress

📝 Format Requirements

• ✅ Use markdown format (`.md`)
• ✅ Use checkbox syntax: `- [ ]` (incomplete) or `- [x]` (complete)
• ✅ Group related tasks under clear headings
• ✅ Include context and details for each task

🔐 Example: Feature Development

Click to expand feature development example

# Authentication Feature

## Backend Implementation
- [x] Set up JWT library
- [x] Create user model and database migration
- [x] Implement password hashing with bcrypt
- [ ] Create login endpoint
- [ ] Create registration endpoint
- [ ] Add middleware for protected routes
- [ ] Write unit tests for auth service
- [ ] Add integration tests for auth endpoints

## Frontend Implementation
- [ ] Create login form component
- [ ] Create registration form component
- [ ] Implement JWT token storage
- [ ] Add authentication context
- [ ] Create protected route wrapper
- [ ] Handle token refresh logic

## Security & Testing
- [ ] Add rate limiting to auth endpoints
- [ ] Implement account lockout after failed attempts
- [ ] Add password strength validation
- [ ] Security audit of auth implementation
- [ ] Load testing for auth endpoints

🗄️ Database Files

> Location: `.buddy/database/`

> Purpose: Store SQL schema definitions, migrations, and query examples

📝 Example: Schema Definition

Click to expand database schema example

-- Users table
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    role VARCHAR(50) DEFAULT 'user',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Sessions table for JWT blacklisting
CREATE TABLE sessions (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
    token_hash VARCHAR(255) UNIQUE NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Indexes for performance
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_sessions_token_hash ON sessions(token_hash);
CREATE INDEX idx_sessions_expires_at ON sessions(expires_at);

💎 Best Practices

🔧 Advanced Features

🔍 File Monitoring

The server automatically monitors your `.buddy` directory for changes and reloads content in real-time.

🔎 Search Integration

Uses Bleve full-text search for fast, relevant results across all your project context.

💾 Backup Management

Automatically creates backups of important files before modifications.

🏗️ Extensible Architecture

Built with Go for high performance and easy extension with new tools and features.

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🐛 Report Issues: Found a bug? Open an issue

2. 💡 Suggest Features: Have an idea? Start a discussion

3. 🔧 Submit PRs: Ready to code? Fork, develop, and submit a pull request

4. 📚 Improve Docs: Help us make the documentation better