🦉 Smart Context MCP Server

Smart Context MCP is a local Model Context Protocol (MCP) server acting as a Universal Context Engine for AI Coding Agents (Cline, Roo Code, Claude Code, Cursor, Continue.dev, Codex, etc.).

It reduces token consumption for powerful LLMs (Strong LLMs) by 50%–70% by intelligently filtering code context, tracking Git Delta changes, and building high-performance local indexes using SQLite and Tree-sitter AST parsing.

Built following the ai-read-first specification & architecture principles for AI-assisted software development.

🌟 Key Features

Smart Token Optimization: Filters out irrelevant code files and sends only the precise context required for each prompt.
Git Delta Detection: Inspects git status and git diff to prioritize active workspace files.
SQLite Local Storage: Fast symbol and Repo Map querying (< 2ms) without high RAM overhead.
Multi-Project Management: Dynamically filters and tracks AST symbols per project.
Flexible Low AI Integration: Supports intent analysis using cheap or local AI providers (Ollama Nemotron, Groq Cloud, Anthropic Claude, OpenAI, Google Gemini Flash).
Web Dashboard UI: Built-in web administration dashboard at http://localhost:3333 for settings, tooltips, and SQLite cache exploration.

💾 Local Storage & Database Locations

Smart Context MCP persists user settings and indexed workspace data locally in your home directory across operating systems:

Data Type	macOS / Linux Path	Windows Path
⚙️ User Configuration	`~/.smart-context/config.json`	`%USERPROFILE%\.smart-context\config.json`
📦 SQLite Cache Database	`~/.smart-context/cache.db`	`%USERPROFILE%\.smart-context\cache.db`

(You can customize the cache database path anytime via the Web Dashboard settings modal).

⚡ Quick Start (Pre-built Release — No Build Required)

End-users do not need to install Node.js build tools or run npm:

Download the pre-built release package: smart-context-mcp-v1.0.0.zip (from the release/ folder or GitHub Releases).
Unzip smart-context-mcp-v1.0.0.zip into your desired folder.
Configure your AI Client to point to the executable launcher smart-context-mcp:

{
  "mcpServers": {
    "smart-context": {
      "command": "/path/to/unzipped/smart-context-mcp-release/smart-context-mcp",
      "args": []
    }
  }
}

📂 Popular AI Client & VS Code Extension Config Locations

Here is where to find the MCP configuration file across Windows, macOS, and Linux for popular AI Coding Clients & VS Code extensions:

AI Client / Extension	Operating System	Standard Configuration File Path
Claude Desktop App	macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
	Windows	`%APPDATA%\Claude\claude_desktop_config.json`
	Linux	`~/.config/Claude/claude_desktop_config.json`
Cursor IDE	macOS / Linux	`~/.cursor/mcp.json` (or Cursor Settings ➔ Features ➔ MCP)
	Windows	`%USERPROFILE%\.cursor\mcp.json`
Continue.dev (VS Code & JetBrains)	macOS / Linux	`~/.continue/config.json` (under `experimental.mcpServers`)
	Windows	`%USERPROFILE%\.continue\config.json`
Cline Extension (VS Code)	macOS	`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
	Windows	`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
	Linux	`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
Roo Code Extension (VS Code)	macOS	`~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`
	Windows	`%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json`
	Linux	`~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json`
Claude Code CLI	macOS / Linux / Windows	`~/.claude.json` (under `mcpServers`)
Codex / VS Code MCP	macOS / Linux / Windows	`.vscode/mcp.json` (Workspace settings)
Antigravity IDE	macOS / Linux	`~/.gemini/antigravity-ide/mcp_config.json`
	Windows	`%USERPROFILE%\.gemini\antigravity-ide\mcp_config.json`

🖥️ Web Dashboard UI

When the MCP Server starts, the administration Web Dashboard is available at:

👉 http://localhost:3333

Features available on the Web Dashboard:

Project Filter: Select and view cached data for specific projects or across all repositories.
SQLite Cache Explorer: View cached files and parsed AST symbols with detailed hover tooltips (?).
Header Actions (⚙️ Settings & ❓ Guide Modals): Dynamically update Low AI Providers and view user guides in modal popups.

📖 Architecture & Standards

This project adheres to the ai-read-first standard for AI agent workflows.

🛠️ Developer Setup (For Modifying Source Code)

If you want to contribute or customize the source code:

# 1. Clone repository
git clone https://github.com/nghiale-soft/smart-context-mcp.git
cd smart-context-mcp

# 2. Install dependencies & build
npm install
npm run build

# 3. Create pre-built standalone ZIP release
npm run release

📜 Helper Scripts (`scripts/`)

./scripts/release.sh: Builds TypeScript source and packages clean ZIP release (release/smart-context-mcp-v1.0.0.zip).