AI导哈

代码智能分析服务器

Nucleus MCP Server是一个通过模型上下文协议提供代码库深度语义理解的AI代理服务器，支持多语言代码的语义搜索、关键词匹配和结构分析。

  • by apoc
  • PowerShell
  • 混合部署
  • 3 星标
  • 更新于
在 GitHub 查看 apoc/nucleus-mcp

使用说明

Nucleus MCP服务器

基于模型上下文协议的代理代码智能

Nucleus是一个MCP（模型上下文协议）服务器，为AI代理提供对代码库的深入语义理解。它结合了语义搜索、关键字匹配和代码结构分析，以回答概念查询（“身份验证逻辑在哪里？”）和精确导航（“谁调用？” verify_token?").

特性

  • 混合搜索：语义概念匹配、精确关键字搜索和结构分析（谁叫谁）
  • 增量索引：只有更改的文件才会重新索引
  • 多语言支持：Rust、Python、TypeScript、C、C++、C#、Dart、Go、Java、Lua和YARA
  • 本地优先：所有数据存储在 .nucleus/ 在您的项目中--不需要外部服务
  • 认知记忆：代理在会话中持续学习
  • GPU加速：支持CUDA、DirectML、OpenVINO和Metal（macOS）

快速开始

1.下载并安装

  1. 从以下网址下载适用于您平台的最新版本ZIP 发布 页面。
  2. 将ZIP解压缩到所需的安装位置，例如：
# Windows example
Expand-Archive -Path nucleus-server_win64.zip -DestinationPath "C:\Tools\nucleus"

macOS和Linux： 马上就来。

2.GPU设置（Windows）

运行安装脚本，将推理运行库安装到与二进制文件相同的目录中：

DirectML（Windows-适用于任何GPU）

powershell -ExecutionPolicy Bypass -File scripts/setup-gpu.ps1 directml -OutputDir "C:\Tools\nucleus"

康迪亚

# Requires CUDA Toolkit 11.8+ and cuDNN 8.x
powershell -ExecutionPolicy Bypass -File scripts/setup-gpu.ps1 cuda -OutputDir "C:\Tools\nucleus"

英特尔OpenVINO

# For Intel CPUs, integrated/discrete GPUs (Arc), and NPUs
powershell -ExecutionPolicy Bypass -File scripts/setup-gpu.ps1 openvino -OutputDir "C:\Tools\nucleus"

支持的Intel硬件：

  • 中央处理器 --任何Intel CPU（核心、至强）
  • 集成显卡 --集成图形（第11代+）
  • 独立显卡 --离散GPU（英特尔Arc A系列）
  • 神经网络处理器 --神经处理单元（Intel Core Ultra/Meteor Lake及更新版本）

仅CPU

powershell -ExecutionPolicy Bypass -File scripts/setup-gpu.ps1 cpu -OutputDir "C:\Tools\nucleus"

替换 C:\Tools\nucleus 使用您解压缩二进制文件的路径。

您还可以覆盖临时下载目录：

powershell -ExecutionPolicy Bypass -File scripts/setup-gpu.ps1 directml `
    -OutputDir "C:\Tools\nucleus" `
    -TempDir "D:\scratch"

macOS（苹果硅）： 无需设置——通过Metal的GPU加速是自动的。

3.首次运行（模型下载）

在控制台中运行服务器一次，下载AI模型并验证设置：

C:\Tools\nucleus\nucleus-server --root /path/to/your/project

在第一次运行时，嵌入和重新排序模型会自动下载（根据配置，约2.3-3.3 GB——嵌入模型加上约1.1 GB的重新排序器）。控制台输出显示模型加载、GPU设备选择和索引进度。

模型缓存在：

  • 窗户： %LOCALAPPDATA%\fastembed\
  • macOS/Linux： ~/.cache/fastembed/

覆盖： FASTEMBED_CACHE_PATH=/custom/path

4.添加到您的MCP客户端

克劳德桌面(~/.claude/claude_desktop_config.json)

{
  "mcpServers": {
    "nucleus": {
      "command": "C:\\Tools\\nucleus\\nucleus-server",
      "args": []
    }
  }
}

VS代码(.vscode/mcp.json 或用户设置）

{
  "servers": {
    "nucleus": {
      "command": "C:\\Tools\\nucleus\\nucleus-server",
      "args": [],
      "type": "stdio"
    }
  }
}

光标(~/.cursor/mcp.json)

{
  "mcpServers": {
    "nucleus": {
      "command": "C:\\Tools\\nucleus\\nucleus-server",
      "args": []
    }
  }
}

克劳德代码（CLI）

claude mcp add nucleus C:\Tools\nucleus\nucleus-server

替换 C:\Tools\nucleus\nucleus-server 上面所有示例中的二进制文件的实际路径。

5.HTTP模式（多客户端）

默认情况下，Nucleus通过stdio进行通信——每个MCP客户端都会生成自己的服务器进程，将模型单独加载到内存中。在HTTP模式下，单个Nucleus实例为所有客户端提供服务。无论连接了多少编辑器或代理，模型都会加载一次。

nucleus-server --http

这将在上启动HTTP服务器 http://127.0.0.1:4040/mcp 使用MCP流式HTTP传输。所有客户端都连接到此实例。您可以同时处理多个项目，甚至可以同时从多个窗口或编辑器打开同一个项目——每个项目都有自己的共享会话（索引、文件查看器、向量存储），因此不会出现任何重复或损坏。

将MCP客户端指向正在运行的服务器，而不是启动二进制文件：

{
  "mcpServers": {
    "nucleus": {
      "url": "http://127.0.0.1:4040/mcp"
    }
  }
}

CLI标志：

  • --http --启用HTTP/SSE传输（默认：stdio）
  • --bind <addr> --绑定地址（默认值： 127.0.0.1)
  • --port <port> --侦听端口（默认： 4040)

可用工具

代码搜索和导航

工具 说明
search_code 跨代码库的语义搜索。返回具有匹配符号的文件级结果。
search_symbols 按名称搜索符号。返回带有行号的精确位置。
get_symbol 通过ID获取完整的符号定义——签名、文档字符串、代码和关系。
get_symbols 批量获取多个符号定义。
get_usages 获取包含位置和代码片段的符号的所有引用。
resolve_symbol_at 将给定文件和行处的引用解析为其定义。退货 symbol_id 以及位置。
find_similar_code 查找与代码段类似的代码。在编写新代码之前使用，以检查现有模式。
find_duplicate_code 检测代码库中近乎重复的代码簇。得分≥0.95为克隆，0.90-0.95相似。
file_overview 获取文件中所有符号的结构概述。
class_overview 获取类/结构的API表面：方法、基、特征-不带体。
get_implementors 获取实现trait或接口的所有类型。
get_dependency_graph 文件级依赖关系图：谁导入此文件（入站）以及它导入什么（出站）。

项目与指标管理

工具 说明
list_dir 列出索引项目中目录的内容。
project_info 获取项目统计信息：文件计数、符号计数、语言、索引运行状况。
status 获取索引状态和系统运行状况。
reindex 触发完整或增量重新索引。使用 {"force": true} 从头开始重建。

认知记忆

工具 说明
cognitive_trigger 管理内存会话生命周期： start, end, problem_appeared, problem_solved.
read_memory 使用语义搜索检索相关记忆。
write_memory 保持新的记忆（代码模式、决策、学习）。
update_memory 修改现有内存。

配置

创建 .nucleus/config.json 在项目根目录中自定义行为：

{
  "embedding": {
    "model": "Qwen3",
    "max_length": 512,
    "batch_size": 32
  },
  "indexer": {
    "include": ["**/*.rs", "**/*.py", "**/*.ts", "**/*.js"],
    "exclude": ["target", "node_modules", ".git", "dist"],
    "max_file_size_bytes": 10485760
  }
}

嵌入模型

型号 尺寸 描述
Qwen3 （默认） ~1.2 GB 最适合代码搜索。仅限于密集矢量。
BGEM3 ~2.2 GB 使用密集和稀疏向量的混合搜索。

要切换型号，请更新 config.json 然后跑 reindex 随着 force: true.

环境变量

核心

变量 描述 默认值
NUCLEUS_EP 执行提供程序（Windows/Linux）： cuda, openvino, directml, cpu 自动检测
FASTEMBED_CACHE_PATH 模型缓存目录 操作系统默认值（见上文）
RUST_LOG 日志记录级别： error, warn, info, debug, trace info

CUDA调整（NVIDIA GPU）

变量 默认值 描述
NUCLEUS_CUDA_MEM_LIMIT 无限制 GPU内存限制（字节）
NUCLEUS_CUDA_CUDNN_CONV_ALGO EXHAUSTIVE 算法搜索： DEFAULT, HEURISTIC, EXHAUSTIVE
NUCLEUS_CUDA_ARENA_STRATEGY SameAsRequested 内存策略： NextPowerOfTwo, SameAsRequested

OpenVINO调优（英特尔）

变量 默认值 描述
NUCLEUS_OPENVINO_DEVICE GPU 设备： GPU, GPU.0, NPU, CPU
NUCLEUS_OPENVINO_PRECISION FP16 精度： FP16, FP32
NUCLEUS_OPENVINO_STREAMS 8 并行执行流（1–255）
NUCLEUS_OPENVINO_CACHE_DIR auto 模型缓存目录

升级

升级Nucleus后，您可能需要重新索引：

# Delete existing index and restart the server
rm -rf .nucleus/

# Or trigger via MCP tool:
# reindex with force: true

何时重新索引：

  • 升级到新的Nucleus版本后
  • 更改嵌入模型后
  • 如果搜索结果显得陈旧或不完整

相关 MCP