内容
# 🔍 上下文维基
[](https://github.com/eunhwa99/MCPContentSearch/actions/workflows/ci.yml)
**为LLM客户端提供的私有知识检索MCP服务器。**
将Notion、Tistory、GitHub和Obsidian同步到向量和元数据存储中，并返回带有引用的上下文。
---
## 🏗️ 架构
```text
[ 来源 ]
Notion / Tistory / GitHub / Obsidian
|
v
[ ingestion 服务 ]
/ \
v v
[ Chroma ] [ SQLite ]
语义搜索 元数据门户
\ /
v v
[ 验证上下文 ]
```
---
## 🛠️ MCP 工具
| 工具 | 描述 |
|------|-------------|
| `list_sources()` | 列出已配置的来源 |
| `sync_source(source_id)` | 同步特定来源 |
| `sync_all()` | 一次同步所有来源 |
| `get_sync_status(source_id="")` | 获取来源和同步作业状态 |
| `search_context(query, ...)` | 使用SQLite验证的语义搜索 |
| `search_documents(query, ...)` | 按文档分组的搜索结果 |
| `fetch_context(document_id="", chunk_id="")` | 直接获取特定文档或块 |
> 💡 在生产环境中，使用 `search_context` / `search_documents` 来收集有根据的证据，然后让下游LLM生成最终答案。
---
## ⚡ 快速开始
**前提条件：** Python `3.13`，[`uv`](https://docs.astral.sh/uv/)
```bash
uv sync --locked
cp .env.example .env
uv run --locked python main.py
```
**Docker：**
```bash
docker build -t contextwiki .
cp .env.example .env
docker run --rm -i \
--env-file .env \
-v contextwiki_data:/home/appuser/.mcp_content_search \
contextwiki
```
> 对于Docker中的Obsidian，添加 `-v "/path/to/vault:/vault:ro"` 并设置 `CONTEXTWIKI_OBSIDIAN_VAULT_PATH=/vault`。
---
## ⚙️ 配置
### 来源激活
| 来源 | 来源ID | 启用环境变量 |
|--------|-----------|-------------------|
| Notion | `source_notion` | `NOTION_API_KEY` |
| Tistory | `source_tistory` | `TISTORY_BLOG_NAME` |
| GitHub | `source_github` | `CONTEXTWIKI_GITHUB_REPOSITORIES` |
| Obsidian | `source_obsidian` | `CONTEXTWIKI_OBSIDIAN_VAULT_PATH` |
仅设置您计划使用的来源。来源在启用配置缺失或为空时保持禁用。错误的凭证仍可能在刷新或同步期间失败。某些无效的目标值可能在启动或来源刷新时更早地失败；例如，格式错误的 `CONTEXTWIKI_GITHUB_REPOSITORIES` 值可能导致服务器无法干净地启动。
来源特定的环境变量仅注册并启用每个来源。默认嵌入设置中，成功的同步/索引还需要 `OPENAI_API_KEY`，除非您重新配置嵌入。
### `.env` 示例
```bash
OPENAI_API_KEY=... # 默认嵌入/索引所需；也用于可选重写
NOTION_API_KEY=...
TISTORY_BLOG_NAME=devlog # 仅子域名，不包括完整URL
CONTEXTWIKI_GITHUB_REPOSITORIES=eunhwa99/MCPContentSearch@main
GITHUB_TOKEN=... # 私有仓库或更高速率限制需要它
CONTEXTWIKI_OBSIDIAN_VAULT_PATH=/absolute/path/to/vault
```
重要GitHub注意事项：
- 使用 `owner/repo` 或 `owner/repo@ref`。
- 不要在 `.env` 中用引号包裹 `CONTEXTWIKI_GITHUB_REPOSITORIES`。
- `GITHUB_TOKEN` 是可选的，但私有仓库和更高的速率限制通常需要它。
**Notion 示例**
```bash
NOTION_API_KEY=...
```
仅在您要启用Notion来源时设置。
**Tistory 示例**
```bash
TISTORY_BLOG_NAME=devlog
```
仅使用博客子域名，不包括完整URL。例如，使用 `devlog`，不要使用 `https://devlog.tistory.com`。
**Obsidian 示例**
```bash
CONTEXTWIKI_OBSIDIAN_VAULT_PATH=/absolute/path/to/your/vault
CONTEXTWIKI_OBSIDIAN_MAX_FILES=2000
CONTEXTWIKI_OBSIDIAN_MAX_FILE_BYTES=512000
```
使用 vault 根路径，不要使用单个 `.md` 文件路径。
### 搜索查询重写（可选）
```bash
CONTEXTWIKI_SEARCH_LLM_ENABLED=true
CONTEXTWIKI_SEARCH_LLM_PROVIDER=openai
CONTEXTWIKI_SEARCH_LLM_MODEL=gpt-4.1-mini
```
---
## 🚀 使用
### Claude Desktop — 本地 uv（推荐）
这是macOS上最简单的设置路径，因为：
- Claude Desktop可以直接启动服务器。
- ContextWiki在启动时加载存储库本地的 `.env`，因此Claude Desktop不需要在 `claude_desktop_config.json` 中使用纯文本环境变量。
- Obsidian可以直接使用您的真实主机 vault 路径。
- 您不需要为 vault 设置Docker挂载。
重要：
- 存储库 `.env` 值不会覆盖已经由Claude Desktop或您的shell设置的任何环境变量。
- 如果您之前在 `claude_desktop_config.json` 或父shell中设置了 `OPENAI_API_KEY`、`NOTION_API_KEY`、`GITHUB_TOKEN` 或其他来源环境变量，请清除这些过时的值。
按以下顺序操作：
1. 在存储库根目录中创建 `.env`。
2. 将您的真实值放入其中。
3. 将以下MCP条目添加到Claude Desktop。
4. 完全重启Claude Desktop。
5. 在新的Claude Desktop聊天中，询问它调用 `list_sources()`。
示例 `.env`：
```bash
# 默认同步/索引所需，因为默认情况下嵌入使用OpenAI
OPENAI_API_KEY=...
# 可选：启用Notion来源
NOTION_API_KEY=...
# 可选：启用Tistory来源
TISTORY_BLOG_NAME=devlog
# 可选：启用GitHub来源
CONTEXTWIKI_GITHUB_REPOSITORIES=eunhwa99/MCPContentSearch
CONTEXTWIKI_GITHUB_DEFAULT_REF=main
# 私有仓库或更高的GitHub API速率限制是可选的
GITHUB_TOKEN=...
# 可选：启用Obsidian来源
CONTEXTWIKI_OBSIDIAN_VAULT_PATH=/absolute/path/to/your/vault
```
在macOS上，将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"content-search-server": {
"command": "/absolute/path/to/uv",
"args": [
"--directory", "/absolute/path/to/MCPContentSearch",
"run", "--python", "3.13", "python", "main.py"
]
}
}
}
```
> 运行 `which uv` 以查找路径。**完全重启Claude Desktop** 以应用任何配置更改。
### Claude Desktop — Docker
```json
{
"mcpServers": {
"content-search-server": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env-file", "/absolute/path/to/MCPContentSearch/.env",
"-v", "contextwiki_data:/home/appuser/.mcp_content_search",
"contextwiki:latest"
]
}
}
}
```
### Cursor
将上述本地uv配置添加到 `.cursor/mcp.json`。
### 连接后
1. 调用 `sync_all()` 或 `sync_source("source_notion")`
2. 使用 `search_context()` 或 `search_documents()` 进行搜索
**示例提示：**
```text
查找我的DynamoDB项目，并使用STAR方法组织。英文回答。
```
---
## 🔧 故障排除
| 症状 | 修复方法 |
|---------|-----|
| MCP 服务器未发现 | 重新检查配置路径并完全重启客户端 |
| 仅在手动启动后才有效 | 直接在终端中运行 `command` + `args` 以查看错误 |
| `Invalid GitHub repository spec` | 从 `.env` 中删除引号；使用 `owner/repo` 而不是完整URL |
| Docker 中的 Obsidian 无法工作 | 设置卷挂载和 `CONTEXTWIKI_OBSIDIAN_VAULT_PATH=/vault` |
| 配置更改后来源仍禁用 | 完全重启MCP客户端 — 聊天刷新是不够的 |
| `sync_all()` 太慢 | 单独同步：`sync_source("source_github")` 等 |
---
## ✅ 验证
```bash
./scripts/demo.sh # 使用样本 vault 进行快速流程检查（不需要凭证）
./scripts/verify_all.sh # 代码更改后的完整验证
./scripts/demo.sh --query "your question" # 自定义查询
```
- `./scripts/demo.sh` 是默认的审查路径。它使用捆绑的样本 vault，不需要凭证，默认情况下保留检索和帮助器预览在同一输入上。
---
## 📁 项目结构
```text
main.py FastMCP 服务器入口点
api/ MCP 工具处理程序
core/ 共享模型、异常、实用程序
environments/ 环境变量和机密加载
fetching/ 来源连接器（Notion、Tistory、GitHub、Obsidian）
indexing/ 分块、重复数据删除、Chroma 索引
search/ 搜索、排名、元数据门户、引用答案支持
storage/ SQLite 生命周期管理
tests/, scripts/ 验证套件和实用程序
```
---
## 📖 附加文档
- [架构](.agents/docs/architecture.md)
