上下文镜头

赋予你的人工智能理解含义的能力，而不仅仅是匹配关键字。

](https://badge.fury.io/py/context-lens) ![Python 3.11+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT)

什么是上下文镜头？

Context Lens将任何内容转换为 可搜索知识库 为您的AI助手。这个自包含的模型上下文协议（MCP）服务器内置了无服务器向量存储（LanceDB），为您的对话带来了语义搜索。将它指向任何内容——代码库、文档、合同或文本文件——你的人工智能就可以立即理解并回答有关内容的问题。

传统关键词搜索 查找包含特定单词的文件。错过了确切的术语？错过了内容。

上下文镜头 理解意义。询问“身份验证”并查找有关登录、凭据、令牌、OAuth和访问控制的代码，即使这些文件从未使用过“身份验证“一词

在行动中看到它

想了解Context Lens的工作原理吗？有趣的是：你可以使用Context Lens来了解Context Lens。

Context-Lens Demo

*演示：使用带有Context Lens的Claude Desktop来索引和查询此存储库本身。没有git克隆，没有代码滚动，只有问题和答案。*

为什么选择LanceDB？

上下文镜头使用 LanceDB -现代无服务器矢量数据库：

🆓 完全免费&本地 -没有云服务、API密钥或订阅
⚡ 零基础设施 -嵌入式数据库，只是磁盘上的一个文件
🚀 快速高效 -基于Apache Arrow构建，针对矢量搜索进行了优化
💾 简易贮藏 -单文件数据库，易于备份或移动

可以把它想象成“用于AI嵌入的SQLite”——向量搜索的所有功能，没有复杂性。

特性

🔍 语义搜索 -理解含义，而不仅仅是关键词
🚀 零设置 -没有安装，没有配置，没有API密钥
💾 无服务器存储 -内置LanceDB，无需外部数据库
🔒 100%本地和私人 -所有数据都保留在您的机器上
📁 本地和GitHub -索引本地文件或公共GitHub存储库
🎯 智能解析 -语言感知组块，以获得更好的结果

建筑

Context Lens Architecture

运作原理

当您向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箭头柱状格式
搜索方法	余弦相似性
处理	100%本地，无外部API调用

📖 想要定制吗？ 看设置.md 有关配置选项和技术.md 用于性能基准测试。

快速设置

开发 IDE

增添 .kiro/settings/mcp.json:

{
  "mcpServers": {
    "context-lens": {
      "command": "uvx",
      "args": ["context-lens"],
      "autoApprove": ["list_documents", "search_documents"]
    }
  }
}

重新加载：命令选项板→ “MCP:重新加载服务器”

光标

增添 .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"]
    }
  }
}

📖 需要详细的设置说明吗？ 看设置.md 对于所有客户端，程序使用和配置选项。

MCP注册表

Context Lens正式发布模型上下文协议注册表作为 io.github.cornelcroi/context-lens.

📖 注册表详细信息和验证： 看注册.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():
    # 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...

📖 完整示例： 看设置.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...

📖 更多示例和查询模式： 用法\_ GIDE.md

智能解析与分块

Context Lens不仅仅是盲目地分割文本——它理解代码结构，并创建尊重语言边界的智能块。

区别： 通用分块根据字符数任意分割代码，通常会在中途破坏函数。智能解析理解代码的结构，并创建完整、有意义的块。

支持的文件类型

🐍 python (.py, .pyw)-函数、类、导入
⚡ JavaScript/TypeScript (.js, .jsx, .ts, .tsx, .mjs, .cjs)-函数、类、导入
📦 JSON (.json, .jsonc)-顶级键、嵌套对象
📋 YAML (.yaml, .yml)-顶级密钥、列表、映射
📝 标记语言 (.md, .markdown, .mdx)-标题层次结构、代码块
🦀 锈 (.rs)-结构、特征、内部块、功能
📄 其他文件 (.txt, .log, .cpp, .java等）-智能段落/句子分割

益处

✅ 完整的代码单位 -永远不要中途拆分函数或类\ ✅ 保留的上下文 -文档字符串、注释和结构保持不变\ ✅ 更好的搜索 -查找完整、可理解的代码片段\ ✅ 自动 -无需配置，基于文件扩展名工作

📖 想看看它是如何工作的吗？ 结账停车_停车.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/ -法律文件

📖 查看更多示例： 用法\_ GIDE.md

可用工具

📥 add_document -添加文件、文件夹或GitHub URL
🔍 搜索文档 -跨所有内容的语义搜索
📋 list_文档 -浏览索引文档
ℹ️ get_document_info -获取文档的元数据
🗑️ remove_document -删除特定文档
🧹 clear_knowledge_base -删除所有文档

📖 请参阅详细示例： 用法\_ GIDE.md

常见问题解答

这与GitHub的MCP服务器相比如何？\ 它们服务于不同的目的，相辅相成：

Context Lens更适合：

🧠 语义理解-“查找身份验证代码”返回登录名、凭据、令牌、OAuth，即使没有确切的关键字
📚 学习代码库-询问“X是如何工作的？”并在整个项目中获得概念上相关的结果
🔍 模式发现-查找类似的代码模式、错误处理方法或架构决策
💾 离线开发-一旦索引，无需互联网连接即可工作
🔒 隐私-所有处理都在本地进行，没有数据发送到外部服务

GitHub的MCP服务器更适合：

🔧 存储库管理-创建问题、管理PR、处理CI/CD操作
📊 实时状态-始终从GitHub获取最新版本
🌐 GitHub特有的功能-与GitHub的生态系统（操作、项目等）集成

主要区别： 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/
视窗: %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的数据库空间。

📖 更多问题： 故障排除.md

文档

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

贡献

欢迎投稿！拜托：

先打开一个问题来讨论你的想法
开始工作前获得批准
提交一份引用该问题的PR

看贡献.md 了解详情。

许可证

MIT许可证-请参阅许可证了解详情。

______________________________________________________________________

如果你觉得回购有用，请为其加星！ ⭐

Context Lens

快速接入

详细介绍