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。