Smart Coding MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Smart Coding MCP find where we handle user authentication in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Smart Coding MCP
An extensible Model Context Protocol (MCP) server that provides intelligent semantic code search for AI assistants. Built with local AI models using Matryoshka Representation Learning (MRL) for flexible embedding dimensions (64-768d).
What This Does
AI coding assistants work better when they can find relevant code quickly. Traditional keyword search falls short - if you ask "where do we handle authentication?" but your code uses "login" and "session", keyword search misses it.
This MCP server solves that by indexing your codebase with AI embeddings. Your AI assistant can search by meaning instead of exact keywords, finding relevant code even when the terminology differs.

Related MCP server: Claude Context Local
Available Tools
đ a_semantic_search - Find Code by Meaning
The primary tool for codebase exploration. Uses AI embeddings to understand what you're looking for, not just match keywords.
How it works: Converts your natural language query into a vector, then finds code chunks with similar meaning using cosine similarity + exact match boosting.
Best for:
Exploring unfamiliar codebases:
"How does authentication work?"Finding related code:
"Where do we validate user input?"Conceptual searches:
"error handling patterns"Works even with typos:
"embeding modle initializashun"still finds embedding 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
Fetches the latest version of any package from its official registry. Supports 20+ ecosystems.
How it works: Queries official package registries (npm, PyPI, Crates.io, etc.) in real-time. No guessing, no stale training data.
Supported ecosystems: npm, PyPI, Crates.io, Maven, Go, RubyGems, NuGet, Packagist, Hex, pub.dev, Homebrew, Conda, and more.
Best for:
Before adding dependencies:
"express"â4.18.2Checking for updates:
"pip:requests"â2.31.0Multi-ecosystem projects:
"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
Triggers a full reindex of your codebase. Normally not needed since indexing is automatic and incremental.
How it works: Scans all files, generates new embeddings, and updates the SQLite cache. Uses progressive indexing so you can search while it runs.
When to use:
After major refactoring or branch switches
After pulling large changes from remote
If search results seem stale or incomplete
After changing embedding configuration (dimension, model)
đī¸ c_clear_cache - Reset Everything
Deletes the embeddings cache entirely, forcing a complete reindex on next search.
How it works: Removes the .smart-coding-cache/ directory. Next search or index operation starts fresh.
When to use:
Cache corruption (rare, but possible)
Switching embedding models or dimensions
Starting fresh after major codebase restructure
Troubleshooting search issues
đ e_set_workspace - Switch Projects
Changes the workspace path at runtime without restarting the server.
How it works: Updates the internal workspace reference, creates cache folder for new path, and optionally triggers reindexing.
When to use:
Working on multiple projects in one session
Monorepo navigation between packages
Switching between related repositories
âšī¸ f_get_status - Server Health Check
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)
Files indexed and chunk count
Model configuration (name, dimension, device)
Cache size and type
When to use:
Start of session to verify everything is working
Debugging connection or indexing issues
Checking indexing progress on large codebases
Installation
npm install -g smart-coding-mcpTo update:
npm update -g smart-coding-mcpIDE Integration
Detailed setup instructions for your preferred environment:
IDE / App | Setup Guide |
|
VS Code | â Yes | |
Cursor | â Yes | |
Windsurf | â Absolute paths only | |
Claude Desktop | â Absolute paths only | |
OpenCode | â Absolute paths only | |
Raycast | â Absolute paths only | |
Antigravity | â Absolute paths only |
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
IDE | OS | Path |
Claude Desktop | macOS |
|
Claude Desktop | Windows |
|
OpenCode | Global |
|
OpenCode | Project |
|
Windsurf | macOS |
|
Windsurf | Windows |
|
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:
Variable | Default | Description |
|
| Enable detailed logging |
|
| Max search results returned |
|
| Files to process in parallel |
|
| Max file size in bytes (1MB) |
|
| Lines of code per chunk |
|
| MRL dimension (64, 128, 256, 512, 768) |
|
| AI embedding model |
|
| Inference device ( |
|
| Weight for semantic vs exact matching |
|
| Boost multiplier for exact text matches |
|
| Max CPU usage during indexing (10-100%) |
|
| Code chunking ( |
|
| Auto-reindex on file changes |
|
| Delay before background indexing (ms), |
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 - Search works immediately while indexing continues in the background. No waiting for large codebases.
Resource Throttling - CPU limited to 50% by default. Your machine stays responsive during indexing.
SQLite Cache - 5-10x faster than JSON. Automatic migration from older JSON caches.
Incremental Updates - Only changed files are re-indexed. Saves every 5 batches, so no data loss if interrupted.
Optimized Defaults - 128d embeddings (2x faster than 256d with minimal quality loss), smart batch sizing, 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 --> AgentTech Stack
Component | Technology |
Protocol | Model Context Protocol (JSON-RPC) |
AI Model | nomic-embed-text-v1.5 (MRL) |
Inference | transformers.js + ONNX Runtime |
Chunking | Smart regex / Tree-sitter AST |
Search | Cosine similarity + exact match boost |
Cache | SQLite with WAL mode |
Privacy
Everything runs 100% locally:
AI model runs on your machine (no API calls)
Code never leaves your system
No telemetry or analytics
Cache stored in
.smart-coding-cache/
Research Background
This project builds on research from Cursor showing that semantic search improves AI coding agent performance by 12.5% on average. The key insight: AI assistants benefit more from relevant context than from large amounts of context.
License
MIT License - Copyright (c) 2025 Omar Haris
See LICENSE for full text.
Available Tools
6 toolsa_semantic_searchARead-onlyIdempotent
Performs intelligent hybrid code search combining semantic understanding with exact text matching. Ideal for finding code by meaning (e.g., 'authentication logic', 'database queries') even with typos or variations. Returns the most relevant code snippets with file locations and line numbers.
Inputs: query (required), maxResults.
b_index_codebaseAIdempotent
Manually trigger a full reindex of the codebase. This will scan all files and update the embeddings cache. Useful after large code changes or if the index seems out of date.
Inputs: force.
c_clear_cacheADestructiveIdempotent
Clears the embeddings cache, forcing a complete reindex on next search or manual index operation. Useful when encountering cache corruption or after major codebase changes.
Inputs: no named parameters.
d_check_last_versionARead-onlyIdempotent
Get the latest version of a library/package from its official registry. Supported ecosystems: npm (JS/TS), PyPI (Python), Packagist (PHP), Crates.io (Rust), Maven (Java/Kotlin), Go, RubyGems, NuGet (.NET), Hex (Elixir), CRAN (R), CPAN (Perl), pub.dev (Dart), Homebrew (macOS), Conda (Python/R), Clojars (Clojure), Hackage (Haskell), Julia, Swift PM, Chocolatey (Windows). Returns the version string to help you avoid using outdated dependencies.
Inputs: package (required), ecosystem.
e_set_workspaceA
Change the project workspace path at runtime. Use this when you detect the current workspace is incorrect or you need to switch to a different project directory. Creates cache folder automatically and optionally re-indexes the new workspace.
Inputs: path (required), clearCache, reindex.
f_get_statusA
Get comprehensive status information about the Smart Coding MCP server. Returns version, workspace path, model configuration, indexing status, and cache information. Useful for understanding the current state of the semantic search system.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogâĻ
TDQS
Scored across 6 tools
Most tools have distinct purposes, such as semantic search, indexing, cache management, dependency checking, workspace switching, and status retrieval. However, 'b_index_codebase' and 'c_clear_cache' could be confused since both relate to cache/index management, with overlapping use cases like handling major code changes.
The naming is inconsistent and chaotic, with no discernible pattern. Tools use prefixes like 'a_', 'b_', etc., which are arbitrary and not descriptive, mixed with descriptive names like 'set_workspace' and 'get_status'. This lack of a consistent verb_noun or other convention makes the set hard to navigate.
With 6 tools, the count is well-scoped and appropriate for a semantic coding assistant server. Each tool appears to earn its place by covering distinct aspects like search, indexing, cache, dependencies, workspace, and status, without being overly sparse or bloated.
The tool set covers core workflows for semantic code search and management, including search, indexing, cache handling, dependency updates, workspace switching, and status checks. A minor gap exists in lacking direct code manipulation tools (e.g., edit or refactor), but agents can likely work around this given the server's focus on search and analysis.
Maintenance
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Ask how your codebase works. Hosted codebase intelligence for repos indexed on repowise.dev.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables semantic code search across projects using AI embeddings to find code by meaning rather than just text matching. Provides fast intelligent search, symbol analysis, and code similarity detection with multi-language support.MIT
- FlicenseNot gradedqualityDmaintenanceProvides semantic code search capabilities that run 100% locally using EmbeddingGemma embeddings. Enables finding code by meaning across 15 file extensions and 9+ programming languages without API costs or sending code to the cloud.238-
- AlicenseAqualityDmaintenanceProvides semantic code search over codebases using local embeddings with natural language queries. Supports hybrid search, file watching, and respects .gitignore.117MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to perform intelligent semantic code search across codebases using local AI embeddings for meaning-based retrieval.6MIT