<div align="center">

🧠 CodeContext

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

Features • Quick Start • Architecture • API Reference • Contributing

</div>

---

🎯 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.

✨ 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

Category	Pattern Types	Detection Method
Code Style	Error Handling, Imports, Naming, Structure	Rules-based (instant)
Frameworks	API Format, Validation, Database, Auth	Hybrid (rules + LLM fallback)

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

Layer	Technology
Frontend	Next.js 14 (App Router), TypeScript, Tailwind CSS
Backend	Next.js API Routes, NextAuth.js
Database	PostgreSQL (Supabase)
Queue	Redis (Upstash)
AST Parsing	@babel/parser, @babel/traverse
LLM	Groq (llama-3.3-70b-versatile)
MCP	@modelcontextprotocol/sdk

---

🚀 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:

Variable	Description	Where to Get
DATABASE_URL	PostgreSQL connection string	Supabase → Settings → Database
UPSTASH_REDIS_REST_URL	Redis REST URL	Upstash → Redis → REST API
UPSTASH_REDIS_REST_TOKEN	Redis REST token	Same as above
NEXTAUTH_SECRET	Random 32-byte secret	Run: openssl rand -base64 32
GITHUB_CLIENT_ID	OAuth App client ID	GitHub → OAuth Apps
GITHUB_CLIENT_SECRET	OAuth App secret	Same as above
GROQ_API_KEY	Groq API key	Groq Console

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)

Pattern	What It Detects
Error Handling	try-catch blocks, wrapper functions (handleError, etc.)
Import Style	Relative (./path), Absolute (@/, ~/), Barrel exports
Naming Convention	camelCase, snake_case, PascalCase
File Structure	App Router, Pages Router, Components directory

Hybrid (Rules + LLM Fallback)

Pattern	What It Detects
API Format	Next.js API Routes, response structure patterns
Validation	Zod, Yup, Joi, Valibot, custom validation
Database	Prisma, Drizzle, TypeORM, Mongoose, Supabase, Kysely
Authentication	NextAuth, Clerk, Auth0, Supabase Auth, Firebase

---

🔧 Troubleshooting

<details> <summary><strong>Database connection failed</strong></summary>

• 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

</details>

<details> <summary><strong>GitHub OAuth redirect error</strong></summary>

• Verify callback URL is set to http://localhost:3000/api/auth/callback/github
• Ensure NEXTAUTH_URL matches your app URL

</details>

<details> <summary><strong>Pattern detection returns empty</strong></summary>

• Check if repository indexing is complete (status: "completed")
• Verify there are TypeScript/JavaScript files in the repo
• Check Redis queue for pending jobs

</details>

<details> <summary><strong>MCP not connecting to Cursor</strong></summary>

• Restart Cursor after updating mcp.json
• Check API key is valid and not expired
• Verify the repo_id matches a indexed repository

</details>

---

🗺️ 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.

---

<div align="center">

Built with ❤️ for the AI-assisted coding community

⭐ Star this repo if you find it useful!

</div>