Context Lens

Context Lens

让你的 AI 具备理解含义的能力，而不只是匹配关键词。

什么是 Context Lens？

Context Lens 可将任意内容转化为你的 AI 助手可用的可搜索知识库。这个自包含的 Model Context Protocol（MCP）服务内置无服务器向量存储（LanceDB），为你的对话带来语义搜索。将它指向任意内容——代码库、文档、合同或文本文件——你的 AI 就能即时理解并回答关于这些内容的问题。

传统关键词搜索会查找包含特定词语的文件。没写确切的词？就找不到内容。

Context Lens 理解含义。询问“authentication”，就能找到关于登录、凭证、token、OAuth 和访问控制的代码——即使那些文件从未使用过“authentication”这个词。

实际效果

想了解 Context-Lens 是如何工作的？有趣的地方在于：你可以用 Context-Lens 来了解 Context-Lens。

演示：使用 Claude Desktop 搭配 Context-Lens 对该仓库本身进行索引和查询。无需 git clone，无需翻阅代码——只有问答。

为什么选择 LanceDB？

Context Lens 使用 LanceDB——一个现代化的无服务器向量数据库：

• 🆓 完全免费且本地运行 - 无需云服务、API key 或订阅
• ⚡ 零基础设施 - 嵌入式数据库，只是磁盘上的一个文件
• 🚀 快速高效 - 基于 Apache Arrow 构建，专为向量搜索优化
• 💾 存储简单 - 单文件数据库，易于备份或迁移

可以把它看作“AI embedding 领域的 SQLite”——具备向量搜索的全部能力，却没有复杂性。

功能特性

• 🔍 语义搜索 - 理解含义，而不只是关键词
• 🚀 零配置 - 无需安装、无需配置、无需 API key
• 💾 无服务器存储 - 内置 LanceDB，无需外部数据库
• 🔒 100% 本地且私密 - 所有数据都保留在你的机器上
• 📁 本地与 GitHub - 可索引本地文件或公共 GitHub 仓库
• 🎯 智能解析 - 语言感知分块，带来更好的结果

架构

工作原理

当你向 Context Lens 添加内容时，它并不只是把文本倾倒进数据库。实际发生的过程如下：

智能读取： Context Lens 会检测你的文件类型并使用专门的解析器。Python 文件通过 AST 解析进行分析，JSON 按结构解析，Markdown 按标题拆分。这保留了内容的自然结构。

有意义的分块： 内容不是按任意字符数限制来切分，而是智能分块——完整的函数、逻辑段落、完整章节。你的代码绝不会在函数中间被拆开。

语义向量： 每个分块都会使用本地 embedding 模型转换为 384 维向量。这些向量捕捉的是含义，而不只是词语。“authentication”和“login system”会变成相似的向量，即使它们没有共同的词。

本地存储： 一切都进入 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: Reload Servers"

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 Registry

Context Lens 已作为 io.github.cornelcroi/context-lens 发布到官方 Model Context Protocol Registry。

📖 Registry 详情与验证： 请参阅 REGISTRY.md 了解安装验证和 Registry 信息。

编程方式用法

在 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():
    # Load environment variables from .env file
    load_dotenv()
    
    # Create MCP client for context-lens server
    mcp_client = MCPClient(
        lambda: stdio_client(
            StdioServerParameters(command="uvx", args=["context-lens"])
        )
    )
    
    # Create an agent with OpenAI model and MCP tools
    model = OpenAIModel(model_id="gpt-4o-mini")
    agent = Agent(model=model, tools=[mcp_client])
    
    print("Chatbot started! Type 'quit' to exit.")
    
    while True:
        user_input = input("\nYou: ").strip()
        
        if user_input.lower() in ['quit', 'exit', 'bye']:
            print("Goodbye!")
            break
            
        if not user_input:
            continue
            
        try:
            response = agent(user_input)
            print(f"Bot: {response}")
        except Exception as e:
            print(f"Error: {e}")

if __name__ == "__main__":
    main()

示例对话：

You: Add https://github.com/fastapi/fastapi to the knowledge base
Bot: ✓ Added 247 files from repository with 1,543 chunks

You: How does FastAPI handle dependency injection?
Bot: FastAPI uses a sophisticated dependency injection system...

📖 完整示例： 请参阅 SETUP.md 了解完整代码和更多框架。

快速开始

添加你的项目

You: Add all Python files from ./src to the knowledge base
LLM: ✓ Added 23 Python files with 156 chunks

You: How does the authentication system work?
LLM: The authentication system uses JWT tokens. The login flow starts in 
     auth/login.py where credentials are validated, then a token is generated
     with the user's ID and expiration time...

You: Show me all the database models
LLM: Based on the codebase, here are the main database models:
     1. User model (models/user.py) - handles user accounts and authentication
     2. Post model (models/post.py) - manages blog posts with relationships...

从开源中学习

You: Add https://github.com/fastapi/fastapi to the knowledge base
LLM: ✓ Added 247 files from repository with 1,543 chunks

You: How does FastAPI handle dependency injection?
LLM: FastAPI uses a sophisticated dependency injection system. The Depends()
     function in fastapi/dependencies.py analyzes function signatures and
     automatically resolves dependencies. Here's how it works...

You: Compare FastAPI's routing to Flask
LLM: FastAPI uses decorator-based routing similar to Flask, but with key
     differences: 1) Type hints for automatic validation, 2) Async support
     built-in, 3) Automatic OpenAPI documentation generation...

分析文档

You: Add all contracts from ./legal/contracts
LLM: ✓ Added 12 contract documents with 487 chunks

You: Find all termination clauses
LLM: I found termination clauses in 8 contracts. Here's a summary:
     - Service Agreement: 30-day notice required for either party
     - Vendor Contract: Immediate termination for breach of confidentiality...

You: What are the payment terms across all contracts?
LLM: Payment terms vary by contract type:
     - Service contracts: Net 30 days from invoice date
     - Vendor agreements: 50% upfront, 50% on delivery...

从 URL 获取文件

You: Add https://raw.githubusercontent.com/fastapi/fastapi/master/README.md
LLM: ✓ Document 'README.md' added successfully with 42 chunks

You: What is FastAPI and what are its key features?
LLM: FastAPI is a modern, fast web framework for building APIs with Python 3.7+.
     Key features include:
     - Fast performance (on par with NodeJS and Go)
     - Automatic API documentation
     - Type hints for validation
     - Async support built-in...

📖 更多示例和查询模式： 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) - 结构体、trait、impl 块、函数
• 📄 其他文件 (.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 服务更擅长：

• 🔧 仓库管理 - 创建 issue、管理 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

文档

• 📖 安装指南 - 面向所有客户端的详细安装说明与配置选项
• 📚 使用指南 - 示例、查询与最佳实践
• 🎨 解析示例 - 智能解析的工作原理
• 🔧 故障排查 - 常见问题与解决方案
• ⚙️ 技术细节 - 架构、技术栈与性能
• 📋 注册表信息 - MCP Registry 验证与安装
• 🤝 贡献指南 - 如何贡献、路线图
• 📦 发布指南 - MCP Registry 发布流程（面向维护者）

贡献

欢迎贡献！请：

1. 先提交 issue 讨论你的想法
2. 获得批准后再开始工作
3. 提交 PR 并引用该 issue

详情请参阅 CONTRIBUTING.md。

许可证

MIT License - 详情请参阅 LICENSE。

---

如果觉得有用，请给仓库点个 Star！ ⭐