使用说明

上下文引擎

一个仅限本地的语义搜索系统，从Chrome捕获网络文档，并使VS Code编码代理可以通过MCP对其进行搜索。

没有云，就没有订阅。一切都在你的机器上运行。

Chrome Extension  →  FastAPI Server (localhost:11811)  →  MCP Server  →  VS Code Agent

特性

Chrome 扩展 --一键捕获任何页面或选择；抓取整个文档站点
YouTube文字记录 --可选弹出工具，用于通过浏览器会话在本地添加活动YouTube视频的字幕
语义搜索 — BAAI/bge-base-en-v1.5 通过句子变换器嵌入（768 dim，完全本地）
多收藏店 --每个主题单独的zvec索引（例如。 raycast-docs, react-docs)
异步BFS爬虫 --礼貌地同时抓取文档网站
MCP服务器 --插入Claude Code、Cursor、Copilot、Continue.dev——任何与MCP兼容的代理

建筑

Chrome Extension (Manifest V3)
  ├── Popup: collection picker, add page, crawl site
  ├── Content Script: extract page text / selection
  ├── Context Menu: right-click → add to collection
  └── Service Worker: relay to local server
         │ HTTP (localhost:11811)
         ▼
FastAPI Server (server.py)
  ├── Multi-collection zvec store (~/.context-engine/collections/{name}/)
  ├── sentence-transformers BAAI/bge-base-en-v1.5 (local, 768-dim)
  ├── Async BFS web crawler (httpx + beautifulsoup4)
  └── REST API
         │ stdio
         ▼
MCP Server (mcp_server.py)
  ├── tool: search_docs
  ├── tool: list_collections
  └── tool: add_memory

文件结构

context-engine/
├── server.py          # FastAPI server (port 11811)
├── crawler.py         # Async BFS web crawler
├── mcp_server.py      # MCP stdio server for VS Code / Claude Code
├── requirements.txt
├── install.sh         # One-shot setup script
└── extension/         # Chrome Extension (Manifest V3)
    ├── manifest.json
    ├── popup.html
    ├── popup.css
    ├── popup.js
    ├── content.js
    ├── background.js
    └── icons/

设置

1.安装依赖项

git clone https://github.com/TeddyJubu/context-engine.git
cd context-engine
bash install.sh

这创建了一个 .venv/，安装所有Python deps，并打印下一步。

2.启动服务器

.venv/bin/python3 server.py

验证： curl http://localhost:11811/health

3.加载Chrome扩展程序

首选 chrome://extensions
启用 开发者模式
点击 装载时未包装 → 选择 extension/ 文件夹

4.连接到您的编码代理

python3 connect.py

此功能会自动检测已安装的代理（Claude Code、Cursor、VS Code、Windsurf、Claude Desktop）并对其进行配置。您还可以连接特定的代理：

python3 connect.py --claude-code --cursor
python3 connect.py --all
python3 connect.py --status    # check what's connected
python3 connect.py --all --remove    # disconnect all

Manual configuration

如果您更喜欢手动设置，请添加到代理的MCP配置中：

克劳德代码 (~/.claude.json):

{
  "mcpServers": {
    "context-engine": {
      "command": "/path/to/context-engine/.venv/bin/python3",
      "args": ["/path/to/context-engine/mcp_server.py"]
    }
  }
}

光标 (~/.cursor/mcp.json):

{
  "mcpServers": {
    "context-engine": {
      "command": "/path/to/context-engine/.venv/bin/python3",
      "args": ["/path/to/context-engine/mcp_server.py"]
    }
  }
}

VS代码/副本 (~/.vscode/mcp.json):

{
  "servers": {
    "context-engine": {
      "command": "/path/to/context-engine/.venv/bin/python3",
      "args": ["/path/to/context-engine/mcp_server.py"]
    }
  }
}

帆板运动 (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "context-engine": {
      "command": "/path/to/context-engine/.venv/bin/python3",
      "args": ["/path/to/context-engine/mcp_server.py"]
    }
  }
}

api参考

服务器运行在 http://localhost:11811.

大多数端点都需要 X-Context-Token 头球令牌在首次运行时自动生成并存储在 ~/.context-engine/token。使用以下方式检索：

cat ~/.context-engine/token

方法	路径	身份验证	正文	描述
`GET`	`/health`	否	--	状态、收集计数、型号名称
`GET`	`/collections`	是	--	列出所有具有文档计数的集合
`POST`	`/collections`	是的	`{name}`	创建收藏
`DELETE`	`/collections/{name}`	是	--	删除收藏
`POST`	`/add`	是的	`{text, collection, source?, tags?, source_type?, metadata?}`	添加文本（自动分块）
`POST`	`/search`	是的	`{query, collection?, top_k?, filter_tags?}`	语义搜索
`POST`	`/crawl`	是的	`{url, collection, max_pages?, path_prefix?}`	启动异步爬网
`GET`	`/crawl/{task_id}`	是	--	轮询爬网进度

当 collection 省略了 /search，搜索所有集合，并按分数合并结果。

快速示例

# Set TOKEN for convenience (replace with your actual token from ~/.context-engine/token)
TOKEN=$(cat ~/.context-engine/token)

# Create a collection
curl -X POST localhost:11811/collections \
  -H 'Content-Type: application/json' \
  -H "X-Context-Token: $TOKEN" \
  -d '{"name": "raycast-docs"}'

# Add a snippet
curl -X POST localhost:11811/add \
  -H 'Content-Type: application/json' \
  -H "X-Context-Token: $TOKEN" \
  -d '{"text": "Use getPreferenceValues() to read user preferences.", "collection": "raycast-docs", "source": "https://developers.raycast.com"}'

# Search
curl -X POST localhost:11811/search \
  -H 'Content-Type: application/json' \
  -H "X-Context-Token: $TOKEN" \
  -d '{"query": "how do I read user preferences", "collection": "raycast-docs"}'

# Crawl an entire doc site
curl -X POST localhost:11811/crawl \
  -H 'Content-Type: application/json' \
  -H "X-Context-Token: $TOKEN" \
  -d '{"url": "https://developers.raycast.com/basics/getting-started", "collection": "raycast-docs", "max_pages": 50}'

# Poll crawl status
curl -H "X-Context-Token: $TOKEN" localhost:11811/crawl/{task_id}

MCP工具

工具	参数	说明
`search_docs`	`query`, `collection?`, `top_k?`	跨索引文档的语义搜索
`list_collections`	--	显示集合和文档计数
`add_memory`	`text`, `collection`, `source?`	存储事实或注释

在代理中的使用

search_docs("how to create a Raycast command", collection="raycast-docs")
list_collections()
add_memory("Always use useNavigation for stack-based navigation", collection="raycast-docs")

Chrome 扩展

弹出窗口可让您完全控制：

状态点 --服务器可访问时为绿色，脱机时为红色
收藏选择器 --在集合之间切换或创建新的集合
添加此页面 --提取并索引当前页面的主要内容
添加选择 --仅索引您突出显示的文本
YouTube文字记录 --从活动的YouTube视频选项卡中提取字幕并将其存储为 youtube_transcript 上下文
爬行站点 --BFS从当前URL抓取最多N个页面，并实时显示进度

右键单击上下文菜单：

将选择添加到上下文引擎 --在任何选定的文本上
将页面添加到上下文引擎 --在任何页面上

YouTube文字记录

打开支持的YouTube视频选项卡，选择一个收藏，然后单击 添加成绩单 在弹出窗口中。
转录提取保留在扩展程序的本地，并使用浏览器的实时YouTube会话。
成功的项目存储在 source_type: youtube_transcript 以及元数据，包括视频id、标题、URL、语言、生成/手动字幕状态和提取方法。

爬行器详细信息

用途 httpx.AsyncClient 并发信号量为5
请求之间0.5秒的礼貌延迟
从中提取文本 <main> → <article> → <body> （优先级顺序）
条带 nav, footer, header, aside, script, style, svg
仅遵循指定路径前缀内的相同域链接
默认 max_pages: 200
在插入之前，每个页面都会被分块（约400个字符）、嵌入和重复数据消除

数据存储

藏品存放在 ~/.context-engine/collections/{name}/ 作为zvec指数。

每个文档存储： hash, text, source, tags, timestamp，以及768个暗淡的float32嵌入。

重复数据删除是通过文本的SHA-1哈希完成的——在重新添加时跳过相同的块。

需求

Python 3.10+
约500MB磁盘用于嵌入模型（首次运行时下载）
Chrome/Chromium扩展程序

fastapi>=0.110
uvicorn>=0.27
httpx>=0.27
beautifulsoup4>=4.12
sentence-transformers>=2.5
zvec
mcp>=1.0

环境变量

变量	默认值	描述
`CONTEXT_ENGINE_DIR`	`~/.context-engine`	数据目录
`EMBED_MODEL`	`BAAI/bge-base-en-v1.5`	句子转换模型
`CONTEXT_ENGINE_EMBED_DIM`	`768`	嵌入尺寸（必须与模型匹配）
`CONTEXT_TOP_K`	`8`	默认搜索结果计数
`CONTEXT_ENGINE_CHUNK_SIZE`	`2048`	最大块大小（以字符为单位）
`CONTEXT_ENGINE_CHUNK_OVERLAP`	`200`	字符块之间的重叠（夹紧到CHUNK_SIZE-1）
`CONTEXT_ENGINE_TOKEN`	（自动生成）	写入端点的身份验证令牌（覆盖 `~/.context-engine/token`)

使用说明

上下文引擎

特性

建筑

文件结构

设置

1.安装依赖项

2.启动服务器

3.加载Chrome扩展程序

4.连接到您的编码代理

api参考

快速示例

MCP工具

在代理中的使用

Chrome 扩展

YouTube文字记录

爬行器详细信息

数据存储

需求

环境变量

相关 MCP

AI持久记忆服务器

多格式文档转Markdown转换器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

本地LLM模型控制协议

文档搜索服务