项目介绍
Context Lens
赋予你的AI理解意义的能力，而不仅仅是匹配关键词。
什么是 Context Lens？
Context Lens 将任何内容转换为您的AI助手可搜索的知识库。这个自包含的模型上下文协议（MCP）服务器内置了无服务器向量存储（LanceDB），为对话带来了语义搜索能力。指向任何内容——代码库、文档、合同或文本文件——您的AI可以立即理解和回答关于这些内容的问题。
传统的关键词搜索会找到包含特定单词的文件。如果错过确切的词，则会错过内容。
Context Lens理解意义。询问“认证”时，可以找到关于登录、凭证、令牌、OAuth和访问控制的代码——即使这些文件从未使用过“认证”这个词。
实际操作
想了解 Context-Lens 是如何工作的吗？这里有趣的部分是：您可以使用 Context-Lens 来学习 Context-Lens。
演示：使用 Claude Desktop 和 Context-Lens 对此仓库进行索引和查询。无需克隆 Git，无需滚动浏览代码——只需提问和回答。
为什么选择 LanceDB？
Context Lens 使用 LanceDB——一个现代的无服务器向量数据库：
- 🆓 完全免费且本地化——无需云服务、API密钥或订阅
- ⚡ 零基础设施——嵌入式数据库，仅需磁盘上的一个文件
- 🚀 快速高效——基于 Apache Arrow，优化了向量搜索
- 💾 简单存储——单个文件数据库，易于备份或移动
将其视为“AI嵌入的 SQLite”——拥有向量搜索的所有功能，而没有复杂性。
功能
- 🔍 语义搜索——理解意义，而不仅仅是关键词
- 🚀 零设置——无需安装、配置或API密钥
- 💾 无服务器存储——内置 LanceDB，无需外部数据库
- 🔒 100% 本地且私有——所有数据都保留在您的机器上
- 📁 本地及 GitHub——索引本地文件或公共 GitHub 仓库
- 🎯 智能解析——语言感知的分块以获得更好的结果
架构
工作原理
当您将内容添加到 Context Lens 时，它不会只是将文本倒入数据库。实际上发生了以下情况：
智能读取： Context Lens 检测文件类型并使用专用解析器。Python 文件通过 AST 解析，JSON 结构化解析，Markdown 根据标题分割。这保留了内容的自然结构。
有意义的分块： 不是任意字符限制，而是智能分块——完整的函数、逻辑段落、整个部分。您的代码永远不会在函数中间被分割。
语义向量： 每个分块使用本地嵌入模型转换为 384 维向量。这些向量捕捉意义，而不是单词。“认证”和“登录系统”成为相似的向量，尽管它们没有共享任何单词。
本地存储： 所有内容都存储在 LanceDB 中——这是一个无服务器的向量数据库，只是一个磁盘上的文件。无需云服务，无需 API 调用，完全私有。
概念搜索： 当您提出问题时，它也会变成一个向量。Context Lens 查找具有相似向量（相似意义）的分块，并按相关性排序。您得到的答案基于概念，而不是关键词匹配。
技术规格
| 组件 | 详情 |
|---|---|
| 嵌入模型 | sentence-transformers/all-MiniLM-L6-v2 |
| 向量维度 | 384 维度 |
| 模型大小 | 约 90MB（首次使用时下载） |
| 分块大小 | 1000 字符（默认，可配置） |
| 分块重叠 | 200 字符（默认，可配置） |
| 向量数据库 | LanceDB（无服务器，基于文件） |
| 存储格式 | Apache Arrow 列格式 |
| 搜索方法 | 余弦相似度 |
| 处理 | 100% 本地，无外部 API 调用 |
📖 想要定制？ 请参阅 SETUP.md 了解配置选项和 TECHNICAL.md 了解性能基准。
快速设置
Kiro IDE
添加到 .kiro/settings/mcp.json：
{
"mcpServers": {
"context-lens": {
"command": "uvx",
"args": ["context-lens"],
"autoApprove": ["list_documents", "search_documents"]
}
}
}
重新加载：命令面板 → "MCP: 重新加载服务器"
Cursor
添加到 .cursor/mcp.json：
{
"mcpServers": {
"context-lens": {
"command": "uvx",
"args": ["context-lens"]
}
}
}
其他 MCP 客户端
对于 Claude Desktop、Continue.dev 或任何兼容 MCP 的客户端：
{
"mcpServers": {
"context-lens": {
"command": "uvx",
"args": ["context-lens"]
}
}
}
📖 需要详细的设置说明？ 请参阅 SETUP.md 了解所有客户端、编程使用和配置选项。
MCP 注册表
Context Lens 发布到了官方 模型上下文协议注册表，标识为 io.github.cornelcroi/context-lens。
<!-- mcp-name: io.github.cornelcroi/context-lens -->📖 注册表详情和验证： 请参阅 REGISTRY.md 了解安装验证和注册表信息。
编程使用
在您的 Python 应用程序中直接使用 Context Lens：
#!/usr/bin/env python3
import os
from dotenv import load_dotenv
from mcp import StdioServerParameters, stdio_client
from strands import Agent
from strands.models.openai import OpenAIModel
from strands.tools.mcp import MCPClient
def main():
# 从 .env 文件加载环境变量
load_dotenv()
# 创建 context-lens 服务器的 MCP 客户端
mcp_client = MCPClient(
lambda: stdio_client(
StdioServerParameters(command="uvx", args=["context-lens"])
)
)
# 创建带有 OpenAI 模型和 MCP 工具的代理
model = OpenAIModel(model_id="gpt-4o-mini")
agent = Agent(model=model, tools=[mcp_client])
print("聊天机器人已启动！输入 'quit' 退出。")
while True:
user_input = input("\n您：").strip()
if user_input.lower() in ['quit', 'exit', 'bye']:
print("再见！")
break
if not user_input:
continue
try:
response = agent(user_input)
print(f"机器人：{response}")
except Exception as e:
print(f"错误：{e}")
if __name__ == "__main__":
main()
示例对话：
您：将 https://github.com/fastapi/fastapi 添加到知识库
机器人：✓ 添加了 247 个文件，共 1,543 个分块
您：FastAPI 如何处理依赖注入？
机器人：FastAPI 使用复杂的依赖注入系统...
📖 完整示例： 请参阅 SETUP.md 了解完整代码和更多框架。
快速开始
添加您的项目
您：将 ./src 目录中的所有 Python 文件添加到知识库
LLM：✓ 添加了 23 个 Python 文件，共 156 个分块
您：认证系统是如何工作的？
LLM：认证系统使用 JWT 令牌。登录流程始于 auth/login.py，其中验证凭据，然后生成包含用户ID和过期时间的令牌...
您：显示所有数据库模型
LLM：根据代码库，以下是主要的数据库模型：
1. 用户模型（models/user.py）——处理用户账户和认证
2. 帖子模型（models/post.py）——管理博客帖子及其关系...
从开源学习
您：将 https://github.com/fastapi/fastapi 添加到知识库
LLM：✓ 添加了 247 个文件，共 1,543 个分块
您：FastAPI 如何处理依赖注入？
LLM：FastAPI 使用复杂的依赖注入系统。fastapi/dependencies.py 中的 Depends() 函数分析函数签名并自动解决依赖项。这里是它的运作方式...
您：比较 FastAPI 的路由与 Flask
LLM：FastAPI 使用类似于 Flask 的装饰器路由，但有关键差异：1) 类型提示用于自动验证，2) 内置异步支持，3) 自动生成 OpenAPI 文档...
分析文档
您：将 ./legal/contracts 目录中的所有合同添加到知识库
LLM：✓ 添加了 12 份合同文档，共 487 个分块
您：查找所有终止条款
LLM：我在 8 份合同中找到了终止条款。这里是一个总结：
- 服务协议：任一方需提前 30 天通知
- 供应商合同：因违反保密义务可立即终止...
您：所有合同的付款条款是什么？
LLM：付款条款因合同类型而异：
- 服务合同：发票日期后 30 天内支付
- 供应商协议：50% 预付，50% 在交付时支付...
从 URL 获取文件
您：将 https://raw.githubusercontent.com/fastapi/fastapi/master/README.md 添加到知识库
LLM：✓ 文档 'README.md' 成功添加，共 42 个分块
您：什么是 FastAPI，其主要特性是什么？
LLM：FastAPI 是一个现代、快速的 Web 框架，用于使用 Python 3.7+ 构建 API。主要特性包括：
- 快速性能（与 NodeJS 和 Go 相当）
- 自动 API 文档
- 类型提示用于验证
- 内置异步支持...
📖 更多示例和查询模式： USAGE_GUIDE.md
智能解析与分块
Context Lens 并不是盲目地拆分文本——它理解代码结构并创建尊重语言边界的智能分块。
区别： 通用分块按字符计数随意拆分代码，经常在函数中间中断。智能解析理解您的代码结构并创建完整、有意义的分块。
支持的文件类型
- 🐍 Python（
.py,.pyw）——函数、类、导入 - ⚡ JavaScript/TypeScript（
.js,.jsx,.ts,.tsx,.mjs,.cjs）——函数、类、导入 - 📦 JSON（
.json,.jsonc）——顶级键、嵌套对象 - 📋 YAML（
.yaml,.yml）——顶级键、列表、映射 - 📝 Markdown（
.md,.markdown,.mdx）——标题层次结构、代码块 - 🦀 Rust（
.rs）——结构体、特征、实现块、函数 - 📄 其他文件（
.txt,.log,.cpp,.java等）——智能段落/句子拆分
优点
✅ 完整的代码单元——从不中断函数或类 ✅ 保留上下文——文档字符串、注释和结构保持完整 ✅ 更好的搜索——找到完整、易懂的代码片段 ✅ 自动——无需配置，基于文件扩展名工作
📖 想看看它是如何工作的？ 请参阅 PARSING_EXAMPLES.md 了解详细示例。
可添加的内容
Context Lens 可以处理来自多个来源的文本文件：
- 📁 本地文件和文件夹——您的项目、文档、任何文本文件
- 🌐 GitHub 仓库——公共仓库、特定分支、目录或文件
- 🔗 直接文件 URL——任何可通过 HTTP/HTTPS 访问的文件
- 📄 文档——合同、政策、研究论文、技术文档
支持的文件类型： .py, .js, .ts, .java, .cpp, .go, .rs, .rb, .php, .json, .yaml, .md, .txt, .sh 等（超过 25 种扩展名）
最大文件大小： 10 MB（可通过 MAX_FILE_SIZE_MB 环境变量配置）
示例：
./src/—— 本地目录/path/to/file.py—— 单个本地文件https://github.com/fastapi/fastapi—— 整个仓库https://github.com/django/django/tree/main/django/contrib/auth—— 特定目录https://example.com/config.yaml—— 直接文件 URL/path/to/contracts/—— 法律文档
📖 查看更多示例： USAGE_GUIDE.md
可用工具
- 📥 add_document —— 添加文件、文件夹或 GitHub URL
- 🔍 search_documents —— 在所有内容中进行语义搜索
- 📋 list_documents —— 浏览已索引的文档
- ℹ️ get_document_info —— 获取文档元数据
- 🗑️ remove_document —— 删除特定文档
- 🧹 clear_knowledge_base —— 删除所有文档
📖 查看详细示例： USAGE_GUIDE.md
常见问题
这与 GitHub 的 MCP 服务器有何不同？
它们有不同的用途并且互为补充：
Context Lens 更适合：
- 🧠 语义理解——“查找认证代码”返回登录、凭证、令牌、OAuth——即使没有精确的关键词
- 📚 学习代码库——询问“X 如何工作？”并获得整个项目中概念相关的结果
- 🔍 模式发现——查找相似的代码模式、错误处理方法或架构决策
- 💾 离线开发——一旦索引完成，无需互联网连接即可工作
- 🔒 隐私——所有处理都在本地进行，没有任何数据发送到外部服务
GitHub 的 MCP 服务器更适合：
- 🔧 仓库管理——创建问题、管理 PR、处理 CI/CD 操作
- 📊 实时状态——始终从 GitHub 获取最新版本
- 🌐 GitHub 特定功能——集成 GitHub 生态系统（Actions、Projects 等）
关键区别： Context Lens 一次克隆并索引一切以实现快速语义搜索（离线）。GitHub MCP 每次查询时都会调用 API 以实现实时访问（在线）。使用 Context Lens 来理解代码，使用 GitHub MCP 来管理仓库。
为什么第一次运行很慢？
嵌入模型（约 100MB）在首次使用时下载。这只会发生一次。
我需要 API 密钥吗？
不需要！Context Lens 完全本地运行。无需 API 密钥，无需云服务。
我的数据存储在哪里？
Context-Lens 将数据存储在平台特定的目录中：
- macOS：
~/Library/Application Support/context-lens/ - Linux：
~/.local/share/context-lens/ - Windows：%LOCALAPPDATA%\context-lens\
您可以通过设置 CONTEXT_LENS_HOME 环境变量来更改基础目录：
{
"mcpServers": {
"context-lens": {
"command": "uvx",
"args": ["context-lens"],
"env": {
"CONTEXT_LENS_HOME": "/path/to/your/data"
}
}
}
}
或者通过 LANCE_DB_PATH（数据库）和 EMBEDDING_CACHE_DIR（模型）覆盖单独的路径。
我可以使用这个来处理私有代码吗？
可以！所有处理都在本地进行。没有任何数据发送到外部服务。
它占用多少磁盘空间？
模型约 100MB + 每个文本分块约 1KB。一个 10MB 的代码库大约使用 5-10MB 的数据库空间。
📖 更多问题： TROUBLESHOOTING.md