AI导哈

智能语义代码搜索工具

一个基于本地AI模型的智能语义代码搜索工具，提供代码库的语义搜索、包版本查找和代码索引功能，适用于AI编程助手和开发者快速查找相关代码。

  • by omar-haris
  • JavaScript
  • 本地部署
  • 200 星标
  • 更新于
在 GitHub 查看 omar-haris/smart-coding-mcp

使用说明

智能编码MCP

一个可扩展的模型上下文协议（MCP）服务器，为AI助手提供智能语义代码搜索。使用Matryoshka表示学习（MRL）构建本地AI模型，以实现灵活的嵌入维度（64-768d）。

这有什么作用

当AI编码助手能够快速找到相关代码时，他们的工作效果会更好。传统的关键字搜索是不够的——如果你问“我们在哪里处理身份验证？”但你的代码使用了“登录”和“会话”，关键字搜索就会错过它。

这个MCP服务器通过用AI嵌入对代码库进行索引来解决这个问题。你的人工智能助手可以按含义而不是确切的关键字进行搜索，即使术语不同，也能找到相关的代码。

可用工具

🔍 a_semantic_search -按含义查找代码

代码库探索的主要工具。使用AI嵌入来了解你在寻找什么，而不仅仅是匹配关键字。

它是如何工作的： 将自然语言查询转换为向量，然后使用余弦相似度+精确匹配增强来查找具有相似含义的代码块。

最适合：

  • 探索不熟悉的代码库： "How does authentication work?"
  • 查找相关代码： "Where do we validate user input?"
  • 概念搜索： "error handling patterns"
  • 即使拼写错误也能正常工作： "embeding modle initializashun" 仍然找到嵌入代码

示例查询：

"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等。

最适合：

  • 在添加依赖关系之前： "express" → 4.18.2
  • 检查更新： "pip:requests" → 2.31.0
  • 多生态系统项目： "npm:react", "go:github.com/gin-gonic/gin"

示例用法：

"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 -切换项目

在运行时更改工作区路径，而无需重新启动服务器。

它是如何工作的： 更新内部工作区引用，为新路径创建缓存文件夹，并可选择触发重新索引。

何时使用：

  • 在一次会议上处理多个项目
  • 包之间的Monrepo导航
  • 在相关存储库之间切换

ℹ️ f_get_status -服务器健康检查

返回有关MCP服务器的全面状态信息。

它显示了什么：

  • 服务器版本和正常运行时间
  • 工作区路径和缓存位置
  • 索引状态（就绪、索引、完成百分比）
  • 文件索引和块计数
  • 型号配置（名称、尺寸、设备）
  • 缓存大小和类型

何时使用：

  • 开始会话以验证一切正常
  • 调试连接或索引问题
  • 检查大型代码库的索引进度

安装

npm install -g smart-coding-mcp

要更新，请执行以下操作：

npm update -g smart-coding-mcp

IDE集成

您首选环境的详细设置说明：

IDE/App 安装指南 ${workspaceFolder} 支持
VS Code 查看指南 ✅ 是的
光标 查看指南 ✅ 是的
帆板运动 查看指南 ❌ 仅绝对路径
克劳德桌面 查看指南 ❌ 仅绝对路径
开源代码 查看指南 ❌ 仅绝对路径
光线投射 查看指南 ❌ 仅绝对路径
反重力 查看指南 ❌ 仅绝对路径

快速设置

添加到MCP配置文件中：

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

配置文件位置

IDE 操作系统 路径
克劳德桌面 macOS ~/Library/Application Support/Claude/claude_desktop_config.json
克劳德桌面 窗户 %APPDATA%\Claude\claude_desktop_config.json
开源代码 全球 ~/.config/opencode/opencode.json
开源代码 项目 opencode.json 在项目根中
帆板运动 macOS ~/.codeium/windsurf/mcp_config.json
帆板运动 窗户 %USERPROFILE%\.codeium\windsurf\mcp_config.json

多项目设置

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

环境变量

通过环境变量自定义行为：

变量 默认值 描述
SMART_CODING_VERBOSE false 启用详细日志记录
SMART_CODING_MAX_RESULTS 5 返回的最大搜索结果数
SMART_CODING_BATCH_SIZE 100 要并行处理的文件
SMART_CODING_MAX_FILE_SIZE 1048576 最大文件大小（以字节为单位）（1MB）
SMART_CODING_CHUNK_SIZE 25 每个块的代码行数
SMART_CODING_EMBEDDING_DIMENSION 128 MRL维度（64128256512768）
SMART_CODING_EMBEDDING_MODEL nomic-ai/nomic-embed-text-v1.5 AI嵌入模型
SMART_CODING_DEVICE cpu 推理装置(cpu, webgpu, auto)
SMART_CODING_SEMANTIC_WEIGHT 0.7 语义匹配与精确匹配的权重
SMART_CODING_EXACT_MATCH_BOOST 1.5 用于精确文本匹配的增强倍数
SMART_CODING_MAX_CPU_PERCENT 50 索引期间的最大CPU使用率（10-100%）
SMART_CODING_CHUNKING_MODE smart 代码分块(smart, ast, line)
SMART_CODING_WATCH_FILES false 文件更改时自动重新索引
SMART_CODING_AUTO_INDEX_DELAY 5000 背景索引前的延迟（ms）， false 禁用

带有env变量的示例：

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

演出

渐进式索引 -搜索立即工作，而索引在后台继续。无需等待大型代码库。

资源节流 -CPU默认限制为50%。您的机器在索引过程中保持响应。

SQLite缓存 -比JSON快5-10倍。从旧JSON缓存自动迁移。

增量更新 -只有更改的文件才会重新索引。每5批保存一次，因此中断时不会丢失数据。

优化默认值 -128d嵌入（比256d快2倍，质量损失最小），智能批量大小，并行处理。

运作原理

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

技术栈

组件 技术
协议 模型上下文协议（JSON-RPC）
AI模型 nomic-embed-ext-v1.5（MRL）
推断 transformers.js+ONNX运行时
组块 智能正则表达式/树保姆AST
搜索 余弦相似度+精确匹配提升
缓存 带WAL模式的SQLite

隐私

一切都在运转 100%本地:

  • AI模型在您的机器上运行（没有API调用）
  • 代码永远不会离开你的系统
  • 无遥测或分析
  • 缓存存储在 .smart-coding-cache/

研究背景

该项目建立在 Cursor的研究 表明语义搜索使AI编码代理的性能平均提高了12.5%。关键见解：人工智能助手从中受益更多 相关的 上下文比from 大量 上下文。

许可证

麻省理工学院许可证-版权所有（c）2025 Omar Haris

看 许可证 全文。

相关 MCP