使用说明

语义代码mcp

使用AST感知分块和向量嵌入进行语义代码搜索的MCP服务器。适用于任何支持MCP的AI编码工具。

问题

传统的搜索工具，如grep、ripgrep和ag，可以精确地匹配文本模式。当开发人员提出诸如“如何处理身份验证？”或“我们在哪里处理付款？”之类的概念性问题时，这些工具需要知道确切的函数名称或代码模式。这导致：

压倒性的结果：数千行包含搜索词，其中大多数不相关
命名惯例的盲目性：“authenticateUser”、“login”、“validateSession”和“handleAuth”是同一个概念——grep不知道
上下文丢失：结果显示没有周围代码结构的孤立行

AI编码工具继承了这些局限性。Claude Code依赖于grep/ripgrep进行代码搜索——没有语义理解，只有字符串匹配。Aider使用带有图排名的仓库映射来选择相关代码，但仍然依赖于结构分析而不是意义。这些方法适用于较小的代码库，但在规模上很难实现，在不相关的结果上燃烧令牌或缺少概念上相关的代码。

解决方案

语义搜索通过意义来理解代码，而不仅仅是文本。它可以通过理解概念关系来回答“用户身份验证是如何实现的？”，而不管函数名或文件位置如何。

使用局部嵌入和向量搜索，它弥合了文本搜索限制和LLM上下文约束之间的差距，为导航大型代码库提供了更准确的结果。

特性

语义搜索 -按含义查找代码，而不仅仅是关键字
上下文图 -了解代码如何通过图增强搜索进行连接（调用、导入、继承）
会话记忆 -跨多回合对话跟踪代理探索状态
AST感知分块 -Tree sitter WASM用于跨平台解析，无需本机编译
本地嵌入 -带nomic嵌入代码的ONNX运行时（768 dims，8K上下文）
混合搜索 -向量相似度+BM25关键字匹配
交叉编码器重新排序 -变压器重新分级，精度更高
增量索引 -MD5哈希用于更改检测，仅重新索引修改过的文件
文件监视 -编码时实时更新
懒惰索引 -索引建立在首次搜索的基础上，而不是启动时
GPU支持 -CUDA自动检测，索引速度提高10-50倍

安装

开源代码

添加 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "semantic-code": {
      "type": "local",
      "command": ["npx", "@smallthinkingmachines/semantic-code-mcp"],
      "enabled": true
    }
  }
}

克劳德代码

添加 ~/.claude.json 或项目 .mcp.json:

{
  "mcpServers": {
    "semantic-code": {
      "command": "npx",
      "args": ["@smallthinkingmachines/semantic-code-mcp"]
    }
  }
}

VS Code

添加 .vscode/mcp.json （工作区）或运行 MCP: Add Server 命令：

{
  "servers": {
    "semantic-code": {
      "command": "npx",
      "args": ["-y", "@smallthinkingmachines/semantic-code-mcp"]
    }
  }
}

指定目录

默认情况下，服务器会为您当前的工作目录建立索引。要为特定目录建立索引，请将其添加为参数：

# OpenCode: ["npx", "@smallthinkingmachines/semantic-code-mcp", "/path/to/project"]
# VS Code:  "args": ["-y", "@smallthinkingmachines/semantic-code-mcp", "/path/to/project"]
# Claude:   "args": ["@smallthinkingmachines/semantic-code-mcp", "/path/to/project"]

首次运行

首次搜索时，服务器将：

下载型号 （~400MB）-嵌入和重新排序模型缓存在 ~/.cache/semantic-code-mcp/
索引你的代码库 -解析并嵌入所有支持的文件（进度显示在日志中）

后续搜索使用缓存的模型和索引。文件更改时，索引会自动更新。

工具：语义搜索

使用自然语言查询在语义上搜索代码。

参数

参数	类型	必填	说明
`query`	string	Yes	描述您要查找的内容的自然语言查询
`path`	string	否	搜索范围的目录路径
`limit`	number	否	最大结果数（默认值：10，最大值：50）
`file_pattern`	string	否	用于过滤文件的Glob模式（例如，“.ts“，”/南美国家巴拉圭的缩写（Paraguay）

示例

semantic_search({
  query: "authentication middleware that validates JWT tokens",
  path: "src/",
  limit: 5
})

建筑

MCP Server
├── Chunker (web-tree-sitter) → AST-aware code splitting (WASM, cross-platform)
├── Embedder (ONNX local)     → nomic-embed-code, 768 dims
├── Vector DB (LanceDB)       → Serverless, hybrid search
├── Context Graph (SQLite)    → Structural relationships + session memory
├── File Watcher (chokidar)   → Incremental updates
└── Hybrid Search             → BM25 + vector + reranking

上下文图（选择加入）

上下文图在语义搜索的基础上增加了结构感知。通过以下方式启用它：

SEMANTIC_CODE_GRAPH_ENABLED=true

启用后，服务器在索引期间从AST提取结构关系（调用、导入、扩展、实现），并将其存储在SQLite图中。这为另外三个工具提供了动力。

工具：context_query

语义搜索+图邻域扩展。返回富含结构上下文的搜索结果。

参数	类型	必填	说明
`query`	string	是	自然语言查询
`path`	string	否	要确定搜索范围的目录
`limit`	number	No	最大结果数（默认值：10）
`file_pattern`	string	否	用于过滤文件的Glob模式
`depth`	number	No	图遍历深度（1-3，默认值：1）
`edge_kinds`	string[]	否	要遵循的边缘类型：调用、导入、扩展、实现、导出、agent_linked
`session_id`	string	否	用于探索跟踪的会话ID

context_query({
  query: "payment processing",
  depth: 2,
  session_id: "debug-checkout"
})

返回每个搜索结果及其图邻居（调用者、被调用者、导入和继承），而无需读取其他文件。

工具：graph_annotate

在代码节点上留下注释，并在相关块之间创建链接。

参数	类型	必填	说明
`session_id`	string	是	会话ID
`node_id`	string	是	要注释的块ID
`note`	string	否	要附加的注释
`link_to`	string[]	否	创建代理链接边的块ID
`reasoning`	string	否	推理日志条目

工具：会话_摘要

查看探索状态：访问的节点、边界、注释、推理日志和图形统计信息。

参数	类型	必填	说明
`session_id`	string	是	要汇总的会话ID

图形配置

变量	描述	默认值
`SEMANTIC_CODE_GRAPH_ENABLED`	启用上下文图	`false`
`SEMANTIC_CODE_GRAPH_DEPTH`	默认BFS遍历深度（1-5）	`2`
`SEMANTIC_CODE_SESSION_TTL`	会话TTL（秒）	`3600`
`SEMANTIC_CODE_EDGE_KINDS`	要遵循的逗号分隔边类型	所有类型

图会优雅地降级——如果SQLite初始化失败，语义搜索在没有图特征的情况下继续工作。

支持的语言

Types/JavaScript（包括TSX/JSX）
python
走
锈
Java
C/C++
C

其他语言又回到了基于行的分块。

配置

环境变量

变量	描述	默认值
`SEMANTIC_CODE_ROOT`	要索引的根目录	当前工作目录
`SEMANTIC_CODE_INDEX`	自定义索引存储位置	`.semantic-code/index/`
`SEMANTIC_CODE_GRAPH_ENABLED`	启用上下文图	`false`
`SEMANTIC_CODE_GRAPH_DEPTH`	默认图形遍历深度（1-5）	`2`
`SEMANTIC_CODE_SESSION_TTL`	会话TTL（秒）	`3600`
`SEMANTIC_CODE_EDGE_KINDS`	要遵循的边类型（逗号分隔）	所有类型

默认忽略模式

默认情况下忽略以下模式：

**/node_modules/**
**/.git/**
**/dist/**
**/build/**
**/.next/**
**/coverage/**
**/__pycache__/**
**/venv/**
**/.venv/**
**/target/**          (Rust)
**/vendor/**          (Go)
**/*.min.js
**/*.bundle.js
**/*.map
**/package-lock.json
**/yarn.lock
**/pnpm-lock.yaml
**/.semantic-code/**

安全

该服务器包括对常见攻击媒介的保护：

SQL注入：所有过滤器输入都根据严格的白名单进行验证
路径遍历：验证搜索路径是否保留在根目录中
输入验证：在数据库操作之前验证ID和模式

无效输入抛出类型错误(InvalidFilterError, PathTraversalError, InvalidIdError)这可以被适当地捕捉和处理。

存储

索引位置： .semantic-code/index/ （添加到 .gitignore)
图形数据库： .semantic-code/index/graph.db （SQLite，在启用图形时创建）
模型缓存： ~/.cache/semantic-code-mcp/
估计大小：3GB代码库→ ~1.5GB指数（含float16）

文档

部署指导 -生产部署、Docker、性能调优
故障排除指南 -常见问题和解决方案
架构概述 -内部设计和数据流

发展

# Install dependencies
yarn install

# Build
yarn build

# Run in development
yarn dev

# Run tests
yarn test

# Run specific test suites
yarn test -- tests/integration/    # Integration tests
yarn test -- tests/edge-cases/     # Edge case tests
yarn test -- tests/performance/    # Performance benchmarks

项目结构

semantic-code-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── chunker/
│   │   ├── index.ts          # AST-aware chunker + edge extraction
│   │   ├── languages.ts      # Language configs with WASM paths
│   │   └── wasm-loader.ts    # WASM grammar loader with caching
│   ├── embedder/
│   │   ├── index.ts          # ONNX embedding generation
│   │   └── model.ts          # Model download & loading
│   ├── graph/
│   │   ├── index.ts          # SQLite graph store (nodes, edges, BFS)
│   │   ├── config.ts         # Graph configuration from env vars
│   │   ├── extractor.ts      # Edge resolution (raw edges → graph edges)
│   │   ├── schema.ts         # SQLite DDL for graph tables
│   │   ├── session.ts        # In-memory session manager
│   │   └── types.ts          # GraphNode, GraphEdge, RawEdge types
│   ├── store/
│   │   └── index.ts          # LanceDB integration
│   ├── search/
│   │   ├── index.ts          # Hybrid search orchestration
│   │   └── reranker.ts       # Cross-encoder reranking
│   ├── watcher/
│   │   └── index.ts          # File watcher + incremental indexing
│   ├── tools/
│   │   ├── semantic-search.ts # semantic_search tool
│   │   ├── context-query.ts   # context_query tool (search + graph)
│   │   ├── graph-annotate.ts  # graph_annotate tool
│   │   └── session-summary.ts # session_summary tool
│   └── utils/
│       ├── logger.ts          # Structured logging
│       ├── validation.ts      # Shared ID validation
│       └── ...
├── grammars/                  # Pre-built WASM parsers
├── scripts/
│   └── copy-grammars.js      # Build script for WASM files
├── package.json
├── tsconfig.json
└── README.md

附录

Nix用户

由于Nix的路径隔离， npx 可能找不到二进制文件。改为安装到固定位置：

npm install --prefix ~/.local/share/semantic-code-mcp @smallthinkingmachines/semantic-code-mcp

然后在MCP配置中使用（替换 YOUR_USERNAME):

{
  "mcpServers": {
    "semantic-code": {
      "command": "node",
      "args": ["/home/YOUR_USERNAME/.local/share/semantic-code-mcp/node_modules/@smallthinkingmachines/semantic-code-mcp/dist/index.js"]
    }
  }
}