shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

smart-coding-mcp

智能代码语义搜索MCP服务器，通过本地AI模型为编码助手提供基于语义的代码搜索功能，支持多项目管理和渐进式索引。

article

README

🚀 智能编码MCP

智能编码MCP是一个可扩展的模型上下文协议（MCP）服务器，它为AI助手提供智能语义代码搜索功能。该服务器基于本地AI模型构建，采用套娃表示学习（MRL）技术，支持灵活的嵌入维度（64 - 768d）。

🚀 快速开始

安装

npm install -g smart-coding-mcp

若要更新：

npm update -g smart-coding-mcp

IDE集成

以下是不同IDE或应用的详细设置指南： | IDE / 应用 | 设置指南 | ${workspaceFolder} 支持情况 | | ------------------ | -------------------------------------------------- | ---------------------------- | | VS Code | 查看指南 | ✅ 支持 | | Cursor | 查看指南 | ✅ 支持 | | Windsurf | 查看指南 | ❌ 仅支持绝对路径 | | Claude Desktop | 查看指南 | ❌ 仅支持绝对路径 | | OpenCode | 查看指南 | ❌ 仅支持绝对路径 | | Raycast | 查看指南 | ❌ 仅支持绝对路径 | | Antigravity | 查看指南 | ❌ 仅支持绝对路径 |

快速设置

将以下内容添加到MCP配置文件中：

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

配置文件位置

| IDE | 操作系统 | 路径 | | ------------------ | ------- | ----------------------------------------------------------------- | | Claude Desktop | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop | Windows | %APPDATA%\Claude\claude_desktop_config.json | | OpenCode | 全局 | ~/.config/opencode/opencode.json | | OpenCode | 项目 | 项目根目录下的 opencode.json | | Windsurf | macOS | ~/.codeium/windsurf/mcp_config.json | | Windsurf | Windows | %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维度（64、128、256、512、768） | | 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 | 后台索引前的延迟时间（毫秒），false 表示禁用 |

使用环境变量的示例：

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

技术栈

| 组件 | 技术 | | ------------- | ------------------------------------- | | 协议 | 模型上下文协议（JSON-RPC） | | AI模型 | nomic-embed-text-v1.5（MRL） | | 推理 | transformers.js + ONNX Runtime | | 分块 | 智能正则表达式 / Tree-sitter AST | | 搜索 | 余弦相似度 + 精确匹配增强 | | 缓存 | 采用WAL模式的SQLite |

🔧 技术细节

本项目基于 Cursor的研究 构建，该研究表明，语义搜索平均可将AI编码代理的性能提高12.5%。关键见解在于：AI助手从相关上下文获得的收益比从大量上下文获得的收益更多。

📄 许可证

本项目采用MIT许可证 - 版权所有 (c) 2025 Omar Haris。完整的许可证文本请参阅 LICENSE。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端