← 返回目录

ContextWeaver

社区

为 AI Agent 精心编织的代码库上下文引擎

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 开发工具第 219 / 438
Stars: ★ 296 热门
传输方式: stdio（本地进程）
运行环境: Node.js 20+
凭据: 需要 API Key / 凭据
许可证: MIT
最近提交: 44 天前
工具数: 1

53FMRS · D

整体评价良好。混合搜索和上下文扩展策略能有效提升代码检索质量，但依赖于外部 API，对隐私敏感环境可能有顾虑。配置简单，适合 AI 辅助开发场景。

最强项 · 文档质量 13/20 最弱项 · 安全与权限 8/20

可靠性

10/20

安全与权限

8/20

维护活跃度

12/20

文档质量

13/20

安装易用性

10/20

查看各项评分依据

可靠性 10/20: 源码显示了清晰的模块结构和完整的功能实现，包括搜索服务、索引管道和MCP服务器。然而，静态审查无法验证实际运行，且没有发现自动化测试或CI配置，因此无法确认关键路径的可复现性。MCP服务器初始化流程和工具定义存在，但缺乏错误处理的深度验证。
安全与权限 8/20: 需要API密钥作为环境变量，没有硬编码密钥。但缺少对API密钥权限范围的说明，且依赖外部网络服务（SiliconFlow），存在潜在的数据外发风险。没有发现恶意行为或数据窃取迹象。
维护活跃度 12/20: 仓库活跃度较高，有294颗星和4次提交，但未提供明确的发布管理信息。持有MIT许可证，但没有发现安全响应渠道或依赖更新策略。维护治理存在差距。
文档质量 13/20: README提供了详细的安装、配置和MCP集成说明，包括工具参数和环境变量。但缺少故障排除指南和API成本说明。文档与源码结构一致，但仍有隐式假设。
安装易用性 10/20: 提供了全局安装和一键启动MCP服务器的步骤，以及Claude Desktop配置示例。但缺少明确的平台兼容性声明和逐步故障排除指南。

静态评测 · 未实际运行收录于 2026-08-07

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件访问网络连接数据库

适合谁

需要语义代码检索的 AI 辅助编程工具。
希望减少手动搜索代码的开发者。
需要跨文件理解代码依赖的 Agent 应用。

不适合谁

需要实时代码编辑或修改的 IDE 插件。
不支持外部 Embedding API 的离线环境。
需要管理超大型代码库（超过百万级文件）的搜索场景。

所需权限

需要访问代码库文件系统（读取）。
需要调用外部 Embedding 和 Reranker API（网络请求）。
需要写入配置目录 ~/.contextweaver 用于存储索引和日志。

风险与副作用

API Key 泄露风险：配置文件中存储的密钥需妥善保管。
索引构建可能消耗较多内存和 CPU，尤其在大型代码库上。
检索结果可能包含敏感代码，需要注意输出内容的权限控制。

安装接入

准备工作

运行环境：Node.js 20+

EMBEDDINGS_API_KEY 必填密钥 Embedding API 密钥，必需；可从 SiliconFlow 等服务商获取。

EMBEDDINGS_BASE_URL 必填 Embedding API 地址，必需；例如 https://api.siliconflow.cn/v1/embeddings。

EMBEDDINGS_MODEL 必填 Embedding 模型名称，必需；例如 BAAI/bge-m3。

RERANK_API_KEY 必填密钥 Reranker API 密钥，必需；可从 SiliconFlow 等服务商获取。

RERANK_BASE_URL 必填 Reranker API 地址，必需；例如 https://api.siliconflow.cn/v1/rerank。

RERANK_MODEL 必填 Reranker 模型名称，必需；例如 BAAI/bge-reranker-v2-m3。

其他可选配置项（4 个）

EMBEDDINGS_MAX_CONCURRENCY 可选 Embedding 并发数，可选，默认 10。

EMBEDDINGS_DIMENSIONS 可选向量维度，可选，默认 1024。

RERANK_TOP_N 可选 Rerank 返回数量，可选，默认 20。

IGNORE_PATTERNS 可选额外忽略的目录模式，可选，逗号分隔，如 .venv,node_modules。

全局安装：npm install -g @hsingjui/contextweaver 或 pnpm add -g @hsingjui/contextweaver。
初始化配置：运行 contextweaver init 创建 ~/.contextweaver/.env，并配置 Embedding 和 Reranker 的 API Key 及模型。
索引代码库：在项目根目录运行 contextweaver index。
启动 MCP 服务器：运行 contextweaver mcp。

claude_desktop_config.json

{
  "mcpServers": {
    "contextweaver": {
      "command": "contextweaver",
      "args": [
        "mcp"
      ]
    }
  }
}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "contextweaver": {
      "command": "contextweaver",
      "args": [
        "mcp"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add contextweaver -- contextweaver mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

运行 `contextweaver index` 对代码库建立索引后启动 `contextweaver mcp`，在 Claude Desktop 工具列表中应出现 `codebase-retrieval` 工具；调用一次检索即可确认连接正常。

常见排障

检查 ~/.contextweaver/.env 是否正确配置了 API Key 和模型名称。
确保代码库路径正确，且具有读取权限。
查看日志文件 ~/.contextweaver/logs/app.YYYY-MM-DD.log，通过 LOG_LEVEL=debug 查看详细错误。
如果索引未更新，尝试运行 contextweaver index --force 强制重建索引。

试试这样问

连接成功后，可以直接对 AI 助手这样说：

检索这个代码库中用户认证流程是如何实现的
用 codebase-retrieval 查找数据库连接逻辑，技术术语填 DatabasePool,Connection
帮我定位项目里处理路由注册的代码位置
搜索一下错误处理中间件的实现，并解释其结构

工具能力 1

codebase-retrieval 只读

根据语义意图和技术术语，检索代码库中最相关的代码片段，并附带上下文信息。

使用场景

AI 代码助手需要快速理解大型代码库的结构和特定功能实现。

开发者希望通过自然语言查询代码库，如“用户认证流程是如何实现的？”。

在 IDE 或聊天工具中集成 MCP，为 Agent 提供代码库检索能力。

支持客户端

Claude Desktop

依据项目文档列出，未经本站实测。

详细介绍

ContextWeaver 是一个基于 MCP 协议的语义代码检索引擎，采用混合搜索（向量+词法）、AST 语义分片、三阶段上下文扩展和 Token 感知打包，为 LLM 提供精准、相关的代码上下文。支持 TypeScript、JavaScript、Python、Go、Java、Rust 等语言。