Context Lens

🚀 Context Lens

Context Lens 賦予你的 AI 理解語義的能力，而非僅僅進行關鍵詞匹配，能將任何內容轉化為可供 AI 助手搜索的知識庫。

🚀 快速開始

添加你的項目

你: 將 ./src 目錄下的所有 Python 文件添加到知識庫
大語言模型: ✓ 已添加 23 個 Python 文件，共 156 個知識塊

你: 認證系統是如何工作的？
大語言模型: 認證系統使用 JWT 令牌。登錄流程從 auth/login.py 文件開始，在該文件中驗證憑證，然後使用用戶 ID 和過期時間生成令牌...

你: 展示所有數據庫模型
大語言模型: 根據代碼庫，主要的數據庫模型如下：
1. 用戶模型 (models/user.py) - 處理用戶賬戶和認證
2. 文章模型 (models/post.py) - 管理博客文章及其關聯關係...

從開源項目中學習

你: 將 https://github.com/fastapi/fastapi 添加到知識庫
大語言模型: ✓ 已添加該倉庫的 247 個文件，共 1,543 個知識塊

你: FastAPI 如何處理依賴注入？
大語言模型: FastAPI 使用複雜的依賴注入系統。fastapi/dependencies.py 中的 Depends() 函數會分析函數簽名並自動解析依賴。其工作原理如下...

你: 比較 FastAPI 和 Flask 的路由機制
大語言模型: FastAPI 和 Flask 類似，都使用基於裝飾器的路由，但有幾個關鍵區別：1) 使用類型提示進行自動驗證；2) 內置異步支持；3) 自動生成 OpenAPI 文檔...

分析文檔

你: 添加 ./legal/contracts 目錄下的所有合同文件
大語言模型: ✓ 已添加 12 個合同文件，共 487 個知識塊

你: 查找所有終止條款
大語言模型: 我在 8 個合同中找到了終止條款。以下是總結：
- 服務協議：任何一方需提前 30 天通知
- 供應商合同：若違反保密條款可立即終止...

你: 所有合同的付款條款是什麼？
大語言模型: 付款條款因合同類型而異：
- 服務合同：發票日期後 30 天內付款
- 供應商協議：預付 50%，交付時支付 50%...

從 URL 獲取文件

你: 添加 https://raw.githubusercontent.com/fastapi/fastapi/master/README.md
大語言模型: ✓ 文檔 'README.md' 已成功添加，共 42 個知識塊

你: 什麼是 FastAPI，它的主要特性有哪些？
大語言模型: FastAPI 是一個現代、快速的 Python 3.7+ Web 框架，用於構建 API。主要特性包括：
- 高性能（與 NodeJS 和 Go 相當）
- 自動生成 API 文檔
- 使用類型提示進行驗證
- 內置異步支持...

📖 更多示例和查詢模式：USAGE_GUIDE.md

✨ 主要特性

• 🔍 語義搜索 - 理解語義，而非僅匹配關鍵詞
• 🚀 零設置 - 無需安裝、配置和 API 密鑰
• 💾 無服務器存儲 - 內置 LanceDB，無需外部數據庫
• 🔒 100% 本地和私密 - 所有數據都保存在本地機器上
• 📁 支持本地和 GitHub - 可索引本地文件或公共 GitHub 倉庫
• 🎯 智能解析 - 基於語言特性進行分塊，以獲得更好的搜索結果

📦 安裝指南

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，其中包含所有客戶端的詳細設置、編程式用法和配置選項。

💻 使用示例

基礎用法

#!/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，其中包含完整代碼和更多框架的使用示例。

📚 詳細文檔

什麼是 Context Lens？

Context Lens 可將任何內容轉化為供 AI 助手搜索的 知識庫。這個自包含的模型上下文協議（MCP）服務器內置無服務器向量存儲（LanceDB），能為對話帶來語義搜索功能。你可以將其指向任何內容，如代碼庫、文檔、合同或文本文件，這樣你的 AI 就能立即理解並回答關於這些內容的問題。

傳統關鍵詞搜索 只能找到包含特定單詞的文件。如果未使用確切的術語，就會錯過相關內容。

Context Lens 能夠理解語義。當你詢問 “身份驗證” 時，它可以找到關於登錄、憑證、令牌、OAuth 和訪問控制的代碼，即使這些文件中從未使用過 “身份驗證” 這個詞。

實際演示

想了解 Context-Lens 是如何工作的嗎？有趣的是，你可以使用 Context-Lens 來學習 Context-Lens 本身。

演示：使用 Claude Desktop 和 Context-Lens 對本倉庫進行索引和查詢。無需克隆倉庫，也無需滾動查看代碼，只需提問和獲取答案。

為什麼選擇 LanceDB？

Context Lens 使用 LanceDB 這一現代無服務器向量數據庫：

• 🆓 完全免費且本地運行 - 無需雲服務、API 密鑰或訂閱
• ⚡ 零基礎設施 - 嵌入式數據庫，僅為磁盤上的一個文件
• 🚀 快速高效 - 基於 Apache Arrow 構建，針對向量搜索進行了優化
• 💾 存儲簡單 - 單文件數據庫，易於備份和移動

可以將其視為 “用於 AI 嵌入的 SQLite”，具備向量搜索的強大功能，且不復雜。

MCP 註冊表

Context Lens 已發佈到官方 模型上下文協議註冊表，名稱為 io.github.cornelcroi/context-lens。

📖 註冊表詳細信息和驗證：請參閱 REGISTRY.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

文檔資源

• 📖 設置指南 - 所有客戶端的詳細設置和配置選項
• 📚 使用指南 - 示例、查詢和最佳實踐
• 🎨 解析示例 - 智能解析的工作原理
• 🔧 故障排除 - 常見問題和解決方案
• ⚙️ 技術細節 - 架構、技術棧和性能
• 📋 註冊表信息 - MCP 註冊表驗證和安裝
• 🤝 貢獻指南 - 如何貢獻、路線圖
• 📦 發佈指南 - MCP 註冊表發佈流程（適用於維護者）

貢獻說明

歡迎貢獻代碼！請按以下步驟操作：

1. 首先創建一個 issue 討論你的想法
2. 在開始工作前獲得批准
3. 提交 PR 並引用相關 issue

詳細信息請參閱 CONTRIBUTING.md。

🔧 技術細節

架構

工作原理

當你向 Context Lens 添加內容時，它並非簡單地將文本存儲到數據庫中，實際過程如下：

智能讀取：Context Lens 會檢測文件類型並使用專門的解析器。對於 Python 文件，使用 AST 解析；對於 JSON 文件，進行結構化解析；對於 Markdown 文件，按標題進行分割。這樣可以保留內容的自然結構。

有意義的分塊：內容會被智能分塊，而非按任意字符限制分割，例如完整的函數、邏輯段落或完整的部分。代碼不會在函數中間被分割。

語義向量：每個知識塊會使用本地嵌入模型轉換為 384 維向量。這些向量捕獲語義，而非僅關注單詞。“身份驗證” 和 “登錄系統” 會轉換為相似的向量，即使它們沒有共同的單詞。

本地存儲：所有內容都存儲在 LanceDB 中，這是一個無服務器向量數據庫，僅為磁盤上的一個文件。無需雲服務和 API 調用，完全私密。

概念搜索：當你提出問題時，問題也會轉換為向量。Context Lens 會查找具有相似向量（相似語義）的知識塊，並按相關性排序。你將獲得基於概念的答案，而非基於關鍵詞匹配。

技術規格

📖 想要自定義？ 請參閱 SETUP.md 以獲取配置選項，參閱 TECHNICAL.md 以獲取性能基準測試。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE。

如果你覺得這個項目有用，請給它加星！ ⭐