Skip to content
Back to search

smart-coding-mcp

An extensible Model Context Protocol (MCP-Local-MRL-RAG-AST) server that provides intelligent semantic code search for AI assistants. Built with local AI models, inspired by Cursor's semantic search.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/omar-haris--smart-coding-mcp/badge.svg)](/listings/omar-haris--smart-coding-mcp)

HTML

<a href="/listings/omar-haris--smart-coding-mcp"><img src="/api/listings/omar-haris--smart-coding-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g smart-coding-mcp

To update:

npm update -g smart-coding-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 326 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Smart Coding MCP
  2. [![npm version](https://img.shields.io/npm/v/smart-coding-mcp.svg)](https://www.npmjs.com/package/smart-coding-mcp)
  3. [![npm downloads](https://img.shields.io/npm/dm/smart-coding-mcp.svg)](https://www.npmjs.com/package/smart-coding-mcp)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  5. [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
  6. 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).
  7. ## What This Does
  8. 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.
  9. 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.
  10. ![Example](example.png)
  11. ## Available Tools
  12. ### 🔍 `a_semantic_search` - Find Code by Meaning
  13. The primary tool for codebase exploration. Uses AI embeddings to understand what you're looking for, not just match keywords.
  14. **How it works:** Converts your natural language query into a vector, then finds code chunks with similar meaning using cosine similarity + exact match boosting.
  15. **Best for:**
  16. - Exploring unfamiliar codebases: `"How does authentication work?"`
  17. - Finding related code: `"Where do we validate user input?"`
  18. - Conceptual searches: `"error handling patterns"`
  19. - Works even with typos: `"embeding modle initializashun"` still finds embedding code
  20. **Example queries:**
  21. ```
  22. "Where do we handle cache persistence?"
  23. "How is the database connection managed?"
  24. "Find all API endpoint definitions"
  25. ```
  26. ---
  27. ### 📦 `d_check_last_version` - Package Version Lookup
  28. Fetches the latest version of any package from its official registry. Supports 20+ ecosystems.
  29. **How it works:** Queries official package registries (npm, PyPI, Crates.io, etc.) in real-time. No guessing, no stale training data.
  30. **Supported ecosystems:** npm, PyPI, Crates.io, Maven, Go, RubyGems, NuGet, Packagist, Hex, pub.dev, Homebrew, Conda, and more.
  31. **Best for:**
  32. - Before adding dependencies: `"express"` → `4.18.2`
  33. - Checking for updates: `"pip:requests"` → `2.31.0`
  34. - Multi-ecosystem projects: `"npm:react"`, `"go:github.com/gin-gonic/gin"`
  35. **Example usage:**
  36. ```
  37. "What's the latest version of lodash?"
  38. "Check if there's a newer version of axios"
  39. ```
  40. ---
  41. ### 🔄 `b_index_codebase` - Manual Reindexing
  42. Triggers a full reindex of your codebase. Normally not needed since indexing is automatic and incremental.
  43. **How it works:** Scans all files, generates new embeddings, and updates the SQLite cache. Uses progressive indexing so you can search while it runs.
  44. **When to use:**
  45. - After major refactoring or branch switches
  46. - After pulling large changes from remote
  47. - If search results seem stale or incomplete
  48. - After changing embedding configuration (dimension, model)
  49. ---
  50. ### 🗑️ `c_clear_cache` - Reset Everything
  51. Deletes the embeddings cache entirely, forcing a complete reindex on next search.
  52. **How it works:** Removes the `.smart-coding-cache/` directory. Next search or index operation starts fresh.
  53. **When to use:**
  54. - Cache corruption (rare, but possible)
  55. - Switching embedding models or dimensions
  56. - Starting fresh after major codebase restructure
  57. - Troubleshooting search issues
  58. ---
  59. ### 📂 `e_set_workspace` - Switch Projects
  60. Changes the workspace path at runtime without restarting the server.
  61. **How it works:** Updates the internal workspace reference, creates cache folder for new path, and optionally triggers reindexing.
  62. **When to use:**
  63. - Working on multiple projects in one session
  64. - Monorepo navigation between packages
  65. - Switching between related repositories
  66. ---
  67. ### ℹ️ `f_get_status` - Server Health Check
  68. Returns comprehensive status information about the MCP server.
  69. **What it shows:**
  70. - Server version and uptime
  71. - Workspace path and cache location
  72. - Indexing status (ready, indexing, percentage complete)
  73. - Files indexed and chunk count
  74. - Model configuration (name, dimension, device)
  75. - Cache size and type
  76. **When to use:**
  77. - Start of session to verify everything is working
  78. - Debugging connection or indexing issues
  79. - Checking indexing progress on large codebases
  80. ---
  81. ## Installation
  82. ```bash
  83. npm install -g smart-coding-mcp
  84. ```
  85. To update:
  86. ```bash
  87. npm update -g smart-coding-mcp
  88. ```
  89. ## IDE Integration
  90. Detailed setup instructions for your preferred environment:
  91. | IDE / App | Setup Guide | `${workspaceFolder}` Support |
  92. | ------------------ | -------------------------------------------------- | ---------------------------- |
  93. | **VS Code** | [**View Guide**](docs/ide-setup/vscode.md) | ✅ Yes |
  94. | **Cursor** | [**View Guide**](docs/ide-setup/cursor.md) | ✅ Yes |
  95. | **Windsurf** | [**View Guide**](docs/ide-setup/windsurf.md) | ❌ Absolute paths only |
  96. | **Claude Desktop** | [**View Guide**](docs/ide-setup/claude-desktop.md) | ❌ Absolute paths only |
  97. | **OpenCode** | [**View Guide**](docs/ide-setup/opencode.md) | ❌ Absolute paths only |
  98. | **Raycast** | [**View Guide**](docs/ide-setup/raycast.md) | ❌ Absolute paths only |
  99. | **Antigravity** | [**View Guide**](docs/ide-setup/antigravity.md) | ❌ Absolute paths only |
  100. ### Quick Setup
  101. Add to your MCP config file:
  102. ```json
  103. {
  104. "mcpServers": {
  105. "smart-coding-mcp": {
  106. "command": "smart-coding-mcp",
  107. "args": ["--workspace", "/absolute/path/to/your/project"]
  108. }
  109. }
  110. }
  111. ```
  112. ### Config File Locations
  113. | IDE | OS | Path |
  114. | ------------------ | ------- | ----------------------------------------------------------------- |
  115. | **Claude Desktop** | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
  116. | **Claude Desktop** | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
  117. | **OpenCode** | Global | `~/.config/opencode/opencode.json` |
  118. | **OpenCode** | Project | `opencode.json` in project root |
  119. | **Windsurf** | macOS | `~/.codeium/windsurf/mcp_config.json` |
  120. | **Windsurf** | Windows | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
  121. ### Multi-Project Setup
  122. ```json
  123. {
  124. "mcpServers": {
  125. "smart-coding-frontend": {
  126. "command": "smart-coding-mcp",
  127. "args": ["--workspace", "/path/to/frontend"]
  128. },
  129. "smart-coding-backend": {
  130. "command": "smart-coding-mcp",
  131. "args": ["--workspace", "/path/to/backend"]
  132. }
  133. }
  134. }
  135. ```
  136. ## Environment Variables
  137. Customize behavior via environment variables:
  138. | Variable | Default | Description |
  139. | ---------------------------------- | -------------------------------- | ------------------------------------------ |
  140. | `SMART_CODING_VERBOSE` | `false` | Enable detailed logging |
  141. | `SMART_CODING_MAX_RESULTS` | `5` | Max search results returned |
  142. | `SMART_CODING_BATCH_SIZE` | `100` | Files to process in parallel |
  143. | `SMART_CODING_MAX_FILE_SIZE` | `1048576` | Max file size in bytes (1MB) |
  144. | `SMART_CODING_CHUNK_SIZE` | `25` | Lines of code per chunk |
  145. | `SMART_CODING_EMBEDDING_DIMENSION` | `128` | MRL dimension (64, 128, 256, 512, 768) |
  146. | `SMART_CODING_EMBEDDING_MODEL` | `nomic-ai/nomic-embed-text-v1.5` | AI embedding model |
  147. | `SMART_CODING_DEVICE` | `cpu` | Inference device (`cpu`, `webgpu`, `auto`) |
  148. | `SMART_CODING_SEMANTIC_WEIGHT` | `0.7` | Weight for semantic vs exact matching |
  149. | `SMART_CODING_EXACT_MATCH_BOOST` | `1.5` | Boost multiplier for exact text matches |
  150. | `SMART_CODING_MAX_CPU_PERCENT` | `50` | Max CPU usage during indexing (10-100%) |
  151. | `SMART_CODING_CHUNKING_MODE` | `smart` | Code chunking (`smart`, `ast`, `line`) |
  152. | `SMART_CODING_WATCH_FILES` | `false` | Auto-reindex on file changes |
  153. | `SMART_CODING_AUTO_INDEX_DELAY` | `5000` | Delay before background indexing (ms), `false` to disable |
  154. **Example with env vars:**
  155. ```json
  156. {
  157. "mcpServers": {
  158. "smart-coding-mcp": {
  159. "command": "smart-coding-mcp",
  160. "args": ["--workspace", "/path/to/project"],
  161. "env": {
  162. "SMART_CODING_VERBOSE": "true",
  163. "SMART_CODING_MAX_RESULTS": "10",
  164. "SMART_CODING_EMBEDDING_DIMENSION": "256"
  165. }
  166. }
  167. }
  168. }
  169. ```
  170. ## Performance
  171. **Progressive Indexing** - Search works immediately while indexing continues in the background. No waiting for large codebases.
  172. **Resource Throttling** - CPU limited to 50% by default. Your machine stays responsive during indexing.
  173. **SQLite Cache** - 5-10x faster than JSON. Automatic migration from older JSON caches.
  174. **Incremental Updates** - Only changed files are re-indexed. Saves every 5 batches, so no data loss if interrupted.
  175. **Optimized Defaults** - 128d embeddings (2x faster than 256d with minimal quality loss), smart batch sizing, parallel processing.
  176. ## How It Works
  177. ```mermaid
  178. flowchart TB
  179. subgraph IDE["IDE / AI Assistant"]
  180. Agent["AI Agent<br/>(Claude, GPT, Gemini)"]
  181. end
  182. subgraph MCP["Smart Coding MCP Server"]
  183. direction TB
  184. Protocol["Model Context Protocol<br/>JSON-RPC over stdio"]
  185. Tools["MCP Tools<br/>semantic_search | index_codebase | set_workspace | get_status"]
  186. subgraph Indexing["Indexing Pipeline"]
  187. Discovery["File Discovery<br/>glob patterns + smart ignore"]
  188. Chunking["Code Chunking<br/>Smart (regex) / AST (Tree-sitter)"]
  189. Embedding["AI Embedding<br/>transformers.js + ONNX Runtime"]
  190. end
  191. subgraph AI["AI Model"]
  192. Model["nomic-embed-text-v1.5<br/>Matryoshka Representation Learning"]
  193. Dimensions["Flexible Dimensions<br/>64 | 128 | 256 | 512 | 768"]
  194. Normalize["Layer Norm → Slice → L2 Normalize"]
  195. end
  196. subgraph Search["Search"]
  197. QueryEmbed["Query → Vector"]
  198. Cosine["Cosine Similarity"]
  199. Hybrid["Hybrid Search<br/>Semantic + Exact Match Boost"]
  200. end
  201. end
  202. subgraph Storage["Cache"]
  203. Vectors["SQLite Database<br/>embeddings.db (WAL mode)"]
  204. Hashes["File Hashes<br/>Incremental updates"]
  205. Progressive["Progressive Indexing<br/>Search works during indexing"]
  206. end
  207. Agent <-->|"MCP Protocol"| Protocol
  208. Protocol --> Tools
  209. Tools --> Discovery
  210. Discovery --> Chunking
  211. Chunking --> Embedding
  212. Embedding --> Model
  213. Model --> Dimensions
  214. Dimensions --> Normalize
  215. Normalize --> Vectors
  216. Tools --> QueryEmbed
  217. QueryEmbed --> Model
  218. Cosine --> Hybrid
  219. Vectors --> Cosine
  220. Hybrid --> Agent
  221. ```
  222. ### Tech Stack
  223. | Component | Technology |
  224. | ------------- | ------------------------------------- |
  225. | **Protocol** | Model Context Protocol (JSON-RPC) |
  226. | **AI Model** | nomic-embed-text-v1.5 (MRL) |
  227. | **Inference** | transformers.js + ONNX Runtime |
  228. | **Chunking** | Smart regex / Tree-sitter AST |
  229. | **Search** | Cosine similarity + exact match boost |
  230. | **Cache** | SQLite with WAL mode |
  231. ## Privacy
  232. Everything runs **100% locally**:
  233. - AI model runs on your machine (no API calls)
  234. - Code never leaves your system
  235. - No telemetry or analytics
  236. - Cache stored in `.smart-coding-cache/`
  237. ## Research Background
  238. This project builds on [research from Cursor](https://cursor.com/blog/semsearch) 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.
  239. ## License
  240. MIT License - Copyright (c) 2025 Omar Haris
  241. See [LICENSE](LICENSE) for full text.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.