🧠 CodeContext

AI Coding Context Layer — Make AI assistants understand your team's codebase patterns

Features • Quick Start • Architecture • API Reference • Contributing

🎯 The Problem

AI coding assistants like Cursor and Copilot are powerful, but they don't understand your team's unique patterns:

• Your error handling conventions

• Your import style preferences

• Your validation approach

• Your authentication patterns

Every suggestion requires mental translation to match your codebase.

Related MCP server: code-intel MCP Server

✨ The Solution

CodeContext automatically detects your codebase patterns and injects them as context into AI assistants via the Model Context Protocol (MCP). Now every AI suggestion follows your team's conventions out of the box.

🚀 Features

8 Pattern Types Detected

Key Capabilities

• 🔍 AST-Powered Analysis — Deep code parsing with Babel for accurate pattern detection

• 🤖 Hybrid Detection — Rules-based first, LLM (Groq) fallback for complex patterns

• ⚡ Real-time Indexing — Background processing with Redis queue

• 🔗 MCP Protocol — Native integration with Cursor, Copilot, and more

• 🔐 GitHub OAuth — Seamless onboarding and repository access

• 📊 Dashboard — View detected patterns, confidence scores, and usage analytics

🏗️ Architecture

flowchart TB
    subgraph Input["📥 Input"]
        GH[GitHub Repository]
    end
    
    subgraph Core["🧠 CodeContext Engine"]
        IDX[Indexing Queue<br/>Redis/Upstash]
        AST[AST Parser<br/>Babel]
        DET[Pattern Detectors<br/>8 Types]
        LLM[LLM Fallback<br/>Groq]
        CTX[Context Generator]
    end
    
    subgraph Storage["💾 Storage"]
        DB[(PostgreSQL<br/>Supabase)]
    end
    
    subgraph Output["📤 Output"]
        MCP[MCP Server]
        DASH[Dashboard]
    end
    
    subgraph Clients["🤖 AI Clients"]
        CUR[Cursor]
        COP[Copilot]
        OTHER[Other MCP Clients]
    end
    
    GH --> IDX
    IDX --> AST
    AST --> DET
    DET --> LLM
    DET --> DB
    LLM --> DB
    DB --> CTX
    CTX --> MCP
    DB --> DASH
    MCP --> CUR
    MCP --> COP
    MCP --> OTHER

📦 Tech Stack

🚀 Quick Start

Prerequisites

• Node.js 18+

• PostgreSQL database (we recommend Supabase)

• Redis instance (we recommend Upstash)

• GitHub OAuth App

• Groq API key (free tier: 14,400 req/day)

1. Clone & Install

git clone https://github.com/bhasinagam/ContextBridge.git
cd ContextBridge
npm install

2. Configure Environment

cp .env.example .env.local

Edit .env.local with your credentials:

3. Set Up Database

Run the schema in your Supabase SQL editor:

-- Contents of src/lib/db/schema.sql

Or use the Supabase dashboard to import src/lib/db/schema.sql.

4. Run Development Server

npm run dev

Open http://localhost:3000 to access the dashboard.

🔌 MCP Integration

Using with Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "codecontext": {
      "url": "http://localhost:3000/api/mcp/context",
      "headers": {
        "X-API-Key": "your-api-key"
      },
      "defaultParams": {
        "repo_id": "your-repo-id"
      }
    }
  }
}

API Usage

curl -X POST http://localhost:3000/api/mcp/context \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "query": "add an API endpoint",
    "repo_id": "your-repo-id"
  }'

📁 Project Structure

src/
├── app/                      # Next.js App Router
│   ├── api/                  # API Routes
│   │   ├── auth/             # NextAuth endpoints
│   │   ├── github/           # GitHub API proxy
│   │   ├── mcp/              # MCP context & health
│   │   ├── patterns/         # Pattern queries
│   │   ├── repos/            # Repository CRUD
│   │   └── webhooks/         # GitHub webhooks
│   ├── dashboard/            # Dashboard pages
│   └── onboarding/           # Onboarding flow
├── components/               # React components
│   ├── ui/                   # shadcn/ui components
│   └── dashboard/            # Dashboard-specific
└── lib/                      # Core libraries
    ├── db/                   # Database client & schema
    ├── github/               # GitHub API client
    ├── indexing/             # AST parser & queue
    ├── mcp/                  # MCP server & context generator
    ├── patterns/             # 8 pattern detectors
    └── utils/                # Types, helpers, Groq client

🔍 Pattern Types

Rules-Based (No API Calls)

Hybrid (Rules + LLM Fallback)

🔧 Troubleshooting

• Ensure your Supabase project is active

• Check if the password contains special characters (URL-encode them)

• Use port 5432 for direct connection, 6543 for pooled

• Verify callback URL is set to http://localhost:3000/api/auth/callback/github

• Ensure NEXTAUTH_URL matches your app URL

• Check if repository indexing is complete (status: "completed")

• Verify there are TypeScript/JavaScript files in the repo

• Check Redis queue for pending jobs

• Restart Cursor after updating mcp.json

• Check API key is valid and not expired

• Verify the repo_id matches a indexed repository

🗺️ Roadmap

• Multi-language support — Python, Go, Rust

• Custom pattern definitions — User-defined pattern rules

• Team collaboration — Shared pattern configs

• VS Code extension — Native VS Code integration

• Pattern analytics — Usage trends and insights

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Built with ❤️ for the AI-assisted coding community

⭐ Star this repo if you find it useful!