Smart Coding MCP

🚀 Smart Coding MCP

Smart Coding MCP is an extensible Model Context Protocol (MCP) server. It leverages local AI models and Matryoshka Representation Learning (MRL) to provide intelligent semantic code search for AI assistants, with flexible embedding dimensions ranging from 64 to 768d.

🚀 Quick Start

AI coding assistants rely on rapid access to relevant code for optimal performance. Traditional keyword - based searches often fall short. For example, if you search for "where do we handle authentication?" but the code uses terms like "login" and "session", the search may yield no results. The Smart Coding MCP server addresses this issue by indexing your codebase with AI embeddings. This enables your AI assistant to search by meaning rather than exact keywords, effectively finding relevant code even when terminologies differ.

✨ Features

🔍 a_semantic_search - Find Code by Meaning

This is the primary tool for exploring the codebase. It uses AI embeddings to understand the intent of your query rather than simply matching keywords.

How it works: It converts your natural - language query into a vector and then uses cosine similarity combined with an exact - match boost to find code chunks with similar meanings.

Best for:

• Exploring unfamiliar codebases, e.g., "How does authentication work?"
• Finding related code, e.g., "Where do we validate user input?"
• Conceptual searches, e.g., "error handling patterns"
• It can tolerate typos, like "embeding modle initializashun" can still find embedding - related code.

Example queries:

"Where do we handle cache persistence?"
"How is the database connection managed?"
"Find all API endpoint definitions"

📦 d_check_last_version - Package Version Lookup

This tool fetches the latest version of any package from its official registry and supports over 20 ecosystems.

How it works: It queries official package registries such as npm, PyPI, Crates.io, etc., in real - time, eliminating the need for guesswork and relying on stale training data.

Supported ecosystems: npm, PyPI, Crates.io, Maven, Go, RubyGems, NuGet, Packagist, Hex, pub.dev, Homebrew, Conda, and more.

Best for:

• Checking package versions before adding dependencies, e.g., "express" → 4.18.2
• Verifying updates, e.g., "pip:requests" → 2.31.0
• In multi - ecosystem projects, e.g., "npm:react", "go:github.com/gin - gonic/gin"

Example usage:

"What's the latest version of lodash?"
"Check if there's a newer version of axios"

🔄 b_index_codebase - Manual Reindexing

This tool triggers a full reindex of your codebase. Normally, indexing is automatic and incremental, so this is not always necessary.

How it works: It scans all files, generates new embeddings, and updates the SQLite cache. It uses progressive indexing, allowing you to search while the process is ongoing.

When to use:

• After major refactoring or switching branches
• After pulling large changes from a remote repository
• If search results seem stale or incomplete
• After changing the embedding configuration (dimension, model)

🗑️ c_clear_cache - Reset Everything

This tool deletes the embeddings cache entirely, forcing a complete reindex on the next search.

How it works: It removes the .smart - coding - cache/ directory. The next search or indexing operation will start from scratch.

When to use:

• In case of cache corruption (rare but possible)
• When switching embedding models or dimensions
• After a major codebase restructure
• When troubleshooting search issues

📂 e_set_workspace - Switch Projects

This tool changes the workspace path at runtime without restarting the server.

How it works: It updates the internal workspace reference, creates a cache folder for the new path, and can optionally trigger reindexing.

When to use:

• When working on multiple projects in one session
• Navigating between packages in a monorepo
• Switching between related repositories

ℹ️ f_get_status - Server Health Check

This tool returns comprehensive status information about the MCP server.

What it shows:

• Server version and uptime
• Workspace path and cache location
• Indexing status (ready, indexing, percentage complete)
• Number of files indexed and code chunks
• Model configuration (name, dimension, device)
• Cache size and type

When to use:

• At the start of a session to verify everything is working
• When debugging connection or indexing issues
• To check the progress of indexing large codebases

📦 Installation

npm install -g smart-coding-mcp

To update:

npm update -g smart-coding-mcp

📚 Documentation

IDE Integration

Detailed setup instructions for your preferred environment:

Quick Setup

Add to your MCP config file:

{
  "mcpServers": {
    "smart-coding-mcp": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/absolute/path/to/your/project"]
    }
  }
}

Config File Locations

Multi - Project Setup

{
  "mcpServers": {
    "smart-coding-frontend": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/path/to/frontend"]
    },
    "smart-coding-backend": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/path/to/backend"]
    }
  }
}

Environment Variables

Customize behavior via environment variables:

Example with env vars:

{
  "mcpServers": {
    "smart-coding-mcp": {
      "command": "smart-coding-mcp",
      "args": ["--workspace", "/path/to/project"],
      "env": {
        "SMART_CODING_VERBOSE": "true",
        "SMART_CODING_MAX_RESULTS": "10",
        "SMART_CODING_EMBEDDING_DIMENSION": "256"
      }
    }
  }
}

Performance

• Progressive Indexing: You can start searching immediately while indexing continues in the background, eliminating the need to wait for large codebases.
• Resource Throttling: The CPU usage is limited to 50% by default, ensuring your machine remains responsive during indexing.
• SQLite Cache: It is 5 - 10 times faster than JSON and supports automatic migration from older JSON caches.
• Incremental Updates: Only changed files are re - indexed, and data is saved every 5 batches to prevent data loss in case of interruption.
• Optimized Defaults: It uses 128d embeddings (2x faster than 256d with minimal quality loss), smart batch sizing, and parallel processing.

How It Works

flowchart TB
    subgraph IDE["IDE / AI Assistant"]
        Agent["AI Agent<br/>(Claude, GPT, Gemini)"]
    end

    subgraph MCP["Smart Coding MCP Server"]
        direction TB
        Protocol["Model Context Protocol<br/>JSON - RPC over stdio"]
        Tools["MCP Tools<br/>semantic_search | index_codebase | set_workspace | get_status"]

        subgraph Indexing["Indexing Pipeline"]
            Discovery["File Discovery<br/>glob patterns + smart ignore"]
            Chunking["Code Chunking<br/>Smart (regex) / AST (Tree - sitter)"]
            Embedding["AI Embedding<br/>transformers.js + ONNX Runtime"]
        end

        subgraph AI["AI Model"]
            Model["nomic - embed - text - v1.5<br/>Matryoshka Representation Learning"]
            Dimensions["Flexible Dimensions<br/>64 | 128 | 256 | 512 | 768"]
            Normalize["Layer Norm → Slice → L2 Normalize"]
        end

        subgraph Search["Search"]
            QueryEmbed["Query → Vector"]
            Cosine["Cosine Similarity"]
            Hybrid["Hybrid Search<br/>Semantic + Exact Match Boost"]
        end
    end

    subgraph Storage["Cache"]
        Vectors["SQLite Database<br/>embeddings.db (WAL mode)"]
        Hashes["File Hashes<br/>Incremental updates"]
        Progressive["Progressive Indexing<br/>Search works during indexing"]
    end

    Agent <-->|"MCP Protocol"| Protocol
    Protocol --> Tools

    Tools --> Discovery
    Discovery --> Chunking
    Chunking --> Embedding
    Embedding --> Model
    Model --> Dimensions
    Dimensions --> Normalize
    Normalize --> Vectors

    Tools --> QueryEmbed
    QueryEmbed --> Model
    Cosine --> Hybrid
    Vectors --> Cosine
    Hybrid --> Agent

Tech Stack

Privacy

Everything runs 100% locally:

• The AI model operates on your machine without making any API calls.
• Your code never leaves your system.
• There is no telemetry or analytics.
• The cache is stored in .smart - coding - cache/.

Research Background

This project is based on research from Cursor, which shows that semantic search can improve the performance of AI coding agents by an average of 12.5%. The key takeaway is that AI assistants benefit more from relevant context than from large amounts of context.

📄 License

This project is under the MIT License - Copyright (c) 2025 Omar Haris. See LICENSE for the full text.