Smart Coding MCP

🚀 智能編碼MCP

智能編碼MCP是一個可擴展的模型上下文協議（MCP）服務器，它為AI助手提供智能語義代碼搜索功能。該服務器基於本地AI模型構建，採用套娃表示學習（MRL）技術，支持靈活的嵌入維度（64 - 768d）。

🚀 快速開始

安裝

npm install -g smart-coding-mcp

若要更新：

npm update -g smart-coding-mcp

IDE集成

以下是不同IDE或應用的詳細設置指南：

快速設置

將以下內容添加到MCP配置文件中：

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

配置文件位置

多項目設置

{
  "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"]
    }
  }
}

環境變量

可通過環境變量自定義服務器行為：

使用環境變量的示例：

{
  "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"
      }
    }
  }
}

✨ 主要特性

智能語義搜索

AI編碼助手在能夠快速找到相關代碼時，工作效率會更高。傳統的關鍵字搜索存在侷限性，例如當你詢問“我們在哪裡處理身份驗證？”，但代碼中使用的是“登錄”和“會話”時，關鍵字搜索就會失效。而智能編碼MCP服務器通過使用AI嵌入對代碼庫進行索引，解決了這個問題。你的AI助手可以根據語義進行搜索，而不僅僅是匹配精確的關鍵字，即使術語不同，也能找到相關代碼。

豐富的工具集

• 🔍 a_semantic_search - 按語義查找代碼：這是探索代碼庫的主要工具，使用AI嵌入來理解你要查找的內容，而不僅僅是匹配關鍵字。
  • 工作原理：將你的自然語言查詢轉換為向量，然後使用餘弦相似度 + 精確匹配增強來查找具有相似含義的代碼塊。
  • 適用場景：探索不熟悉的代碼庫、查找相關代碼、進行概念性搜索，甚至在有拼寫錯誤的情況下也能正常工作。
  • 示例查詢：

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

• 📦 d_check_last_version - 包版本查詢：從官方註冊表中獲取任何包的最新版本，支持20多個生態系統。
  • 工作原理：實時查詢官方包註冊表（npm、PyPI、Crates.io等）。
  • 支持的生態系統：npm、PyPI、Crates.io、Maven、Go、RubyGems、NuGet、Packagist、Hex、pub.dev、Homebrew、Conda等。
  • 適用場景：添加依賴項之前、檢查更新、多生態系統項目。
  • 示例用法：

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

• 🔄 b_index_codebase - 手動重新索引：觸發代碼庫的完整重新索引。通常情況下，由於索引是自動且增量的，因此不需要手動操作。
  • 工作原理：掃描所有文件，生成新的嵌入，並更新SQLite緩存。採用漸進式索引，因此在索引過程中你仍然可以進行搜索。
  • 使用場景：進行重大重構或切換分支後、從遠程拉取大量更改後、搜索結果過時或不完整時、更改嵌入配置（維度、模型）後。
• 🗑️ c_clear_cache - 重置所有內容：完全刪除嵌入緩存，強制在下一次搜索時進行完整的重新索引。
  • 工作原理：刪除 .smart-coding-cache/ 目錄。下一次搜索或索引操作將重新開始。
  • 使用場景：緩存損壞（罕見但可能發生）、切換嵌入模型或維度、進行重大代碼庫重構後重新開始、排查搜索問題。
• 📂 e_set_workspace - 切換項目：在運行時更改工作區路徑，而無需重啟服務器。
  • 工作原理：更新內部工作區引用，為新路徑創建緩存文件夾，並可選擇觸發重新索引。
  • 使用場景：在一個會話中處理多個項目、在單倉庫的不同包之間導航、切換相關倉庫。
• ℹ️ f_get_status - 服務器健康檢查：返回關於MCP服務器的全面狀態信息。
  • 顯示內容：服務器版本和正常運行時間、工作區路徑和緩存位置、索引狀態（就緒、正在索引、完成百分比）、已索引的文件和代碼塊數量、模型配置（名稱、維度、設備）、緩存大小和類型。
  • 使用場景：會話開始時驗證一切是否正常工作、調試連接或索引問題、檢查大型代碼庫的索引進度。

高性能設計

• 漸進式索引：在後臺進行索引的同時，搜索功能可以立即使用，無需等待大型代碼庫的索引完成。
• 資源節流：默認情況下，CPU使用率限制在50%，確保在索引過程中你的機器仍然保持響應。
• SQLite緩存：比JSON快5 - 10倍，並且可以自動從舊的JSON緩存遷移。
• 增量更新：僅對更改的文件進行重新索引，每5批保存一次，因此即使中斷也不會丟失數據。
• 優化的默認設置：採用128d嵌入（比256d快2倍，質量損失極小）、智能批量大小和並行處理。

隱私保護

一切都在本地運行：

• AI模型在你的機器上運行（無需進行API調用）。
• 代碼永遠不會離開你的系統。
• 沒有遙測或分析。
• 緩存存儲在 .smart-coding-cache/ 中。

📚 詳細文檔

工作原理

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

    subgraph MCP["智能編碼MCP服務器"]
        direction TB
        Protocol["模型上下文協議<br/>JSON-RPC over stdio"]
        Tools["MCP工具<br/>semantic_search | index_codebase | set_workspace | get_status"]

        subgraph Indexing["索引管道"]
            Discovery["文件發現<br/>通配符模式 + 智能忽略"]
            Chunking["代碼分塊<br/>智能（正則表達式）/ AST（Tree-sitter）"]
            Embedding["AI嵌入<br/>transformers.js + ONNX Runtime"]
        end

        subgraph AI["AI模型"]
            Model["nomic-embed-text-v1.5<br/>套娃表示學習"]
            Dimensions["靈活的維度<br/>64 | 128 | 256 | 512 | 768"]
            Normalize["層歸一化 → 切片 → L2歸一化"]
        end

        subgraph Search["搜索"]
            QueryEmbed["查詢 → 向量"]
            Cosine["餘弦相似度"]
            Hybrid["混合搜索<br/>語義 + 精確匹配增強"]
        end
    end

    subgraph Storage["緩存"]
        Vectors["SQLite數據庫<br/>embeddings.db（WAL模式）"]
        Hashes["文件哈希<br/>增量更新"]
        Progressive["漸進式索引<br/>索引期間可進行搜索"]
    end

    Agent <-->|"MCP協議"| 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

技術棧

🔧 技術細節

本項目基於 Cursor的研究 構建，該研究表明，語義搜索平均可將AI編碼代理的性能提高12.5%。關鍵見解在於：AI助手從相關上下文獲得的收益比從大量上下文獲得的收益更多。

📄 許可證

本項目採用MIT許可證 - 版權所有 (c) 2025 Omar Haris。完整的許可證文本請參閱 LICENSE。