Semantic Code MCP

语义代码mcp

为Claude code提供语义代码搜索的MCP服务器。它不是迭代grep/glob，而是用嵌入对代码库进行索引，并按含义返回排名结果。

支持 python, 锈，以及 标记语言 --计划使用更多语言。

运作原理

Claude Code ──(MCP/STDIO)──▶ semantic-code-mcp server
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
              AST Chunker      Embedder        LanceDB
             (tree-sitter)  (sentence-trans)  (vectors)

1. 组块 --树状图将源文件解析为函数、类、方法、结构、特征、markdown部分等。
2. 嵌入 --句子变换器对每个块进行编码（全MiniLM-L6-v2，384d）
3. 存储 --存储在LanceDB中的向量（嵌入式，如SQLite）
4. 搜索 --基于近因提升的混合语义+关键字搜索

索引是增量的（基于mtime），并使用 git ls-files 用于快速文件发现。嵌入模型在第一个查询时延迟加载。

安装

macOS/Windows

PyPI在这些平台上只提供CPU火炬，因此不需要额外的标志（安装约1.7GB）。

uvx semantic-code-mcp

Claude代码集成：

claude mcp add --scope user semantic-code -- uvx semantic-code-mcp

Linux

\[！重要\] 没有 --index 标志，PyPI安装CUDA捆绑火炬（~3.5GB）。除非你需要GPU加速（你不需要——嵌入式在CPU上运行），否则使用下面的命令获取仅CPU的构建（~1.7GB）。

uvx --index pytorch-cpu=https://download.pytorch.org/whl/cpu semantic-code-mcp

Claude代码集成：

claude mcp add --scope user semantic-code -- \
  uvx --index pytorch-cpu=https://download.pytorch.org/whl/cpu semantic-code-mcp

Claude Desktop / other MCP clients (JSON config)

{
  "mcpServers": {
    "semantic-code": {
      "command": "uvx",
      "args": ["--index", "pytorch-cpu=https://download.pytorch.org/whl/cpu", "semantic-code-mcp"]
    }
  }
}

在macOS/Windows上，您可以省略 --index 和 pytorch-cpu args。

更新中

uvx 缓存已安装的版本。要获取最新版本，请执行以下操作：

uvx --upgrade semantic-code-mcp

或者在MCP配置中插入特定版本：

claude mcp add --scope user semantic-code -- uvx semantic-code-mcp@0.2.0

MCP工具

search_code

按含义搜索代码，而不仅仅是文本匹配。首次搜索时自动索引。

返回排名结果 file_path, line_start, line_end, name, chunk_type, content，以及 score.

index_codebase

为语义搜索的代码库建立索引。仅处理新文件和更改的文件，除非 force=True.

index_status

检查项目的索引状态。

退货 is_indexed, files_count，以及 chunks_count.

配置

所有设置都是环境变量 SEMANTIC_CODE_MCP_ 前缀（通过pydantic设置）：

通过传递环境变量 env MCP配置中的字段：

{
  "mcpServers": {
    "semantic-code": {
      "command": "uvx",
      "args": ["semantic-code-mcp"],
      "env": {
        "SEMANTIC_CODE_MCP_DEBUG": "true",
        "SEMANTIC_CODE_MCP_LOCAL_INDEX": "true"
      }
    }
  }
}

或者使用Claude Code CLI：

claude mcp add --scope user semantic-code \
  -e SEMANTIC_CODE_MCP_DEBUG=true \
  -e SEMANTIC_CODE_MCP_LOCAL_INDEX=true \
  -- uvx semantic-code-mcp

技术栈

发展

uv sync                            # Install dependencies
uv run python -m semantic_code_mcp # Run server
uv run pytest                      # Run tests
uv run ruff check src/             # Lint
uv run ruff format src/            # Format

预提交钩子强制执行linting、格式化和类型检查(ty)，安全扫描(bandit)，以及 约定式提交.

释放

版本是从git标签自动派生出来的(hatch-vcs)--中没有硬编码版本 pyproject.toml.

git tag v0.2.0
git push origin v0.2.0

CI构建包，发布到PyPI，并创建带有自动生成注释的GitHub Release。

添加新语言

分块器系统旨在使添加语言变得简单。每种语言都需要：

1. 树保姆语法包 （例如。 tree-sitter-javascript)
2. 分块子类 它遍历AST并提取有意义的块

步骤：

uv add tree-sitter-mylang

创建 src/semantic_code_mcp/chunkers/mylang.py:

from enum import StrEnum, auto

import tree_sitter_mylang as tsmylang
from tree_sitter import Language, Node

from semantic_code_mcp.chunkers.base import BaseTreeSitterChunker
from semantic_code_mcp.models import Chunk, ChunkType

class NodeType(StrEnum):
    function_definition = auto()
    # ... other node types

class MyLangChunker(BaseTreeSitterChunker):
    language = Language(tsmylang.language())
    extensions = (".ml",)

    def _extract_chunks(self, root: Node, file_path: str, lines: list[str]) -> list[Chunk]:
        chunks = []
        for node in root.children:
            match node.type:
                case NodeType.function_definition:
                    name = node.child_by_field_name("name").text.decode()
                    chunks.append(self._make_chunk(node, file_path, lines, ChunkType.function, name))
                # ... other node types
        return chunks

在中注册 src/semantic_code_mcp/container.py:

from semantic_code_mcp.chunkers.mylang import MyLangChunker

def get_chunkers(self) -> list[BaseTreeSitterChunker]:
    return [PythonChunker(), RustChunker(), MarkdownChunker(), MyLangChunker()]

这 CompositeChunker 自动按文件扩展名处理调度。使用 BaseTreeSitterChunker._make_chunk() 以实现一致的块结构。看 chunkers/python.py 和 chunkers/rust.py 查看完整示例。

项目结构

• src/semantic_code_mcp/chunkers/ --语言分块器(base.py, composite.py, python.py, rust.py, markdown.py)
• src/semantic_code_mcp/services/ --IndexService（扫描/块/索引），SearchService（搜索+自动索引）
• src/semantic_code_mcp/indexer.py --嵌入+存储管道
• docs/decisions/ --架构决策记录
• TODO.md --史诗与规划
• CHANGELOG.md --已完成的工作（保持变更日志格式）
• .claude/rules/ --AI代理的上下文特定编码规则

许可证

麻省理工学院