CodeWeave Mcp

@codeweave/mcp

为你的 AI Agent 提供结构化代码理解能力，而不只是文件转储。

---

CodeWeave 是一个 MCP 服务，为 AI Agent 提供高效、精准的代码智能。你的 Agent 无需将整个文件转储到上下文中，而是查询本地索引——AST、调用图、类型图、混合语义搜索——仅获取所需内容。

更少的 Token。更相关的上下文。更好的决策。

语义搜索流水线是系统的核心：一个由 6 个阶段组成的混合引擎，结合了向量嵌入、全文搜索和结构密度评分。我们在大型生产代码库中进行了广泛测试，包括 Java 单体项目、TypeScript 单体仓库、Python 机器学习流水线和 Go 微服务，检索准确率始终出色。

积极开发中。 新工具和改进会定期推出。欢迎贡献和反馈。

快速开始

cd your-project
npx @codeweave/mcp

就是这样。设置向导会处理所有事项：

1. 全局安装 @codeweave/mcp
2. 如有需要，安装 Ollama
3. 下载嵌入模型
4. 配置你的 MCP 客户端（Claude Code、VS Code）
5. 为你的项目建立索引

注意： 首次运行需要一次性下载 Ollama 和嵌入模型。这需要几分钟，但只需进行一次。

在 Claude Code 或 VS Code 中打开你的项目，然后开始提问。

工具

围绕代码理解工作流组织的 3 个工具：

工具	用途
semantic_search	按含义搜索——即使不知道确切名称，也能找到函数。结合向量与关键词的混合搜索，并通过密度重新排序。
reindex	手动触发索引更新。通常不需要——文件监视器会在文件更改时自动重新建立索引。
get_index_status	索引健康状况面板：文件／函数数量、嵌入状态、调用图统计信息、语言分布。

工作原理

Source Code
    │
    ▼
tree-sitter AST  ───>  Function Index (in-memory)
                              │
                   ┌──────────┼──────────┐
                   ▼          ▼          ▼
              Call Graph  Type Graph  Embeddings
              (JSON)      (JSON)     (LanceDB)
                   │          │          │
                   └──────────┼──────────┘
                              ▼
                       3 MCP Tools  ───>  AI Agent

1. 解析 — tree-sitter 提取 7 种语言中的每个函数、类、方法和接口
2. 嵌入 — Qwen3-Embedding-0.6B 为语义搜索生成向量嵌入
3. 索引 — LanceDB 存储向量，并同时建立 BM25 全文索引
4. 图谱 — 调用图通过类型感知解析追踪调用关系；类型图追踪继承和实现关系（为排序和索引状态报告提供支持）
5. 监视 — 文件监视器检测更改，并对受影响的文件进行增量重新索引
6. 服务 — 通过 MCP 协议（stdio）提供 3 个工具，可在索引完成前使用

语义搜索

搜索流水线是 CodeWeave 真正大放异彩的地方。它不只是向量相似度搜索，而是一个多阶段系统，旨在找出最 相关、最 重要 的代码：

6 阶段流水线：

1. 精确名称匹配 — 为已知函数名称提供快速通道（得分 0.95+）
2. 向量搜索 — 对查询进行嵌入，查找语义相似的函数（超量获取 3 倍结果，为重排留出空间）
3. 全文搜索 — BM25 关键词匹配可捕捉嵌入未能找到的内容
4. RRF 合并 — 倒数排名融合会合并两个结果列表，无需校准得分
5. 精确匹配加权 — 名称与查询匹配的函数会获得优先级
6. 密度重排 — 通过结构信号确定信息密度，将琐碎代码排在后面

密度评分使用 7 种语言无关的结构信号：

信号	衡量内容
函数体大小	函数越大，承载的行为越多（按对数缩放）
文档字符串是否存在	有文档说明的代码更有可能重要
文档字符串丰富度	标签、依赖项、副作用表明代码维护良好
参数数量	参数越多 = 行为越复杂
调用图中心性	被许多其他函数调用的函数是架构锚点
可见性	公有 > 受保护 > 私有
类型	类 > 方法/函数 > 接口

惩罚机制可防止噪声主导结果：

• 访问器（getter/setter）— 纯数据访问，不包含行为
• 构造函数 — 参数很多会抬高得分，但它们只是赋值操作
• 测试文件 — 函数体大并不意味着行为重要（除非你正在搜索测试）

优雅降级： 如果 Ollama 不可用，搜索会退回到仅使用全文搜索。

为什么选择这些技术

每项技术选择都服务于核心目标：本地、快速、零配置地理解代码。

技术	原因
tree-sitter	一套解析框架支持全部 7 种语言。成熟、快速、久经考验。无需从头编写 7 种不同解析器，就能让我们完整访问 AST。
LanceDB	嵌入式向量数据库——无需外部服务、Docker 或配置，只需磁盘上的一个目录。通过单一引擎同时支持向量搜索和 BM25 全文搜索。
Qwen3-Embedding-0.6B	秘密武器。参数量仅为 0.6B，但在代码理解方面，其嵌入质量可媲美参数量是其 10 倍的模型。已在大型生产代码库中进行测试，包括 Java 企业级单体应用、TypeScript 单体仓库和 Python 数据流水线，检索准确率始终出色。通过 Ollama 在本地运行，速度足以支持实时重新索引，体量也足够轻巧，适用于任何开发者的机器。
RRF（倒数排名融合）	信息检索研究中经验证的技术。可合并来自不同评分系统（向量相似度和 BM25 相关性）的排序列表，无需校准得分。简单、稳健、有效。
MCP 协议	用于 AI 工具集成的标准接口。一个服务即可与 Claude Code、VS Code、Cursor 以及任何兼容 MCP 的客户端配合使用。

支持的语言

语言	函数	调用	导入	类型	测试检测
Python	函数、方法、类	调用点	import/from-import	类继承、类型提示	pytest、unittest
TypeScript	函数、箭头函数、方法、类、接口	调用点	命名/默认/命名空间导入	implements、extends、成员类型	jest、vitest、playwright
JavaScript	（与 TypeScript 相同）	（与 TypeScript 相同）	（与 TypeScript 相同）	（与 TypeScript 相同）	jest、vitest、mocha
Go	函数、方法（接收者）、结构体	调用点	import 语句	隐式接口、结构体	testing、testify
Rust	函数、方法（impl）、结构体、枚举	调用点	use 声明	针对类型的 impl Trait	#[test]、#[cfg(test)]
Java	方法、构造函数、类、接口	方法调用	import 声明	extends、implements	JUnit、Mockito、AssertJ
C#	方法、构造函数、类、结构体、接口、记录	调用	using 指令	基类型、接口实现	NUnit、xUnit、Moq

每种语言的解析器还会提供：

• 噪声过滤 — 内置标准库调用列表（例如，console.log、fmt.Println、System.out.println），这些调用会从依赖分析中滤除
• 结构提示 — 由 AST 确认的分类（构造函数、抽象、getter/setter、测试），用于密度评分

配置

CodeWeave 开箱即用，无需配置。如需自定义，请创建 .code-context/config.yaml：

workspaces:
  - .                                  # Root workspace
  - clients/web                        # Web client
  - clients/mobile                     # Mobile client

embedding:
  model: "qwen3-embedding:0.6b"     # Embedding model name
  ollamaUrl: "http://localhost:11434" # Ollama API endpoint
  dimensions: 1024                    # Vector dimensions
  batchSize: 50                       # Embedding batch size

parser:
  sourceRoot: "src"                   # Strip this prefix from module paths
  ignore:
    - "**/*.generated.*"              # Additional ignore patterns
    - "**/vendor/**"

search:
  rrfK: 60                           # RRF smoothing constant
  expandCamelCase: true               # Expand camelCase in search chunks
  density:
    enabled: true                     # Density-based reranking
    accessorPenalty: 0.6              # Penalty for getters/setters
    constructorPenalty: 0.7           # Penalty for constructors
    testFilePenalty: 0.5              # Penalty for test files

watcher:
  debounceMs: 500                     # File change debounce
  minIntervalMs: 2000                 # Minimum reindex interval

indexing:
  maxFileSizeKb: 500                  # Skip files larger than this

CLI 工具

# Full project initialization (AST + embeddings + graphs)
codeweave-init [path] [--force] [--no-embed]

# Incremental reindex (only changed files)
codeweave-reindex [--all] [--files=path1,path2] [--stdin]

手动设置

如果你更喜欢逐步设置，而不是使用 npx @codeweave/mcp：

# 1. Install globally
npm install -g @codeweave/mcp

# 2. Install Ollama and pull the embedding model
# macOS
brew install ollama
# Linux
curl -fsSL https://ollama.com/install.sh | sh

ollama pull qwen3-embedding:0.6b

# 3. Index your project
cd your-project
codeweave-init

4. 配置 MCP 客户端

Claude Code — 在项目根目录中添加 .mcp.json：

{
  "mcpServers": {
    "codeweave": {
      "command": "codeweave-server"
    }
  }
}

VS Code — 添加 .vscode/mcp.json：

{
  "servers": {
    "codeweave": {
      "command": "codeweave-server"
    }
  }
}

Monorepo 支持

CodeWeave 会通过扫描清单文件（package.json、build.gradle、pom.xml、go.mod、Cargo.toml、pyproject.toml 等）自动检测 Monorepo 中的工作区：

my-project/
├── backend/build.gradle    → workspace "backend"
├── mobile/package.json     → workspace "mobile"
└── shared/package.json     → workspace "shared"

每个工作区都有独立的索引、调用图、类型图和向量存储。工具接受可选的 workspace 参数；省略该参数即可搜索所有工作区。

Git Worktree 支持

CodeWeave 会自动检测 git worktree（包括 Claude Code 的 /worktree）。首次在 worktree 中启动时，它会复制主仓库的缓存，以便快速预热（约 2 秒，而不是 30 秒以上）。之后，每个 worktree 都会维护自己的完全隔离索引。

• 自动 — 无需配置
• 隔离 — worktree 的更改不会影响主仓库的缓存
• 增量 — 仅重新解析和生成与主分支不同的文件的嵌入

要求

• Node.js 20+
• Ollama — 用于语义搜索嵌入。可通过设置向导安装，也可从 ollama.com 手动安装。没有 Ollama 时，语义搜索将退化为仅全文搜索。

状态

CodeWeave 正在积极开发中。核心索引管道和全部 3 个工具均已稳定，并已在涵盖全部 7 种受支持语言的生产代码库中通过测试。

欢迎提供反馈、报告错误和贡献代码 — 请在 github.com/semihkayan/codeweave-mcp 提交问题。

许可证

Apache 2.0