# OpenViking MCP 完整配置指南
## 目录
1. [概述](#1-概述)
2. [系统架构](#2-系统架构)
3. [安装依赖](#3-安装依赖)
4. [配置详解](#4-配置详解)
5. [MCP服务器实现](#5-mcp服务器实现)
6. [OpenCode集成](#6-opencode集成)
7. [使用指南](#7-使用指南)
8. [数据管理](#8-数据管理)
9. [故障排查](#9-故障排查)
10. [最佳实践](#10-最佳实践)
---
## 1. 概述
### 1.1 什么是OpenViking
OpenViking 是字节跳动火山引擎开源的 **AI智能体上下文数据库**，专为LLM应用设计，提供：
- **语义搜索**：基于向量嵌入的语义检索
- **三级上下文加载**：L0(摘要) → L1(概览) → L2(详情)
- **多模态支持**：文本、PDF、图片等
- **本地部署**：数据存储在本地，保护隐私
### 1.2 什么是MCP
MCP (Model Context Protocol) 是一个开放标准，允许AI应用与外部工具和数据源进行标准化交互。
OpenViking MCP 是将OpenViking接入AI助手（如OpenCode、Claude Desktop）的桥梁。
### 1.3 系统组件
```
┌─────────────────────────────────────────────────────────────┐
│ OpenCode │
│ (AI助手客户端) │
└─────────────────────┬───────────────────────────────────────┘
│ MCP协议 (stdio)
▼
┌─────────────────────────────────────────────────────────────┐
│ openviking_mcp_server.py │
│ (MCP服务器) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ find │ │ read │ │ glob │ │ abstract/ │ │
│ │ │ │ │ │ │ │ overview/grep │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────────┘ │
└─────────────────────┬───────────────────────────────────────┘
│ Python SDK
▼
┌─────────────────────────────────────────────────────────────┐
│ OpenViking 库 │
│ (openviking 0.1.17) │
└─────────────────────┬───────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ viking_data/ │ Ollama API │ docs/ │
│ (向量数据库) │ (嵌入模型) │ (源文档) │
└──────────────┘ └──────────────┘ └──────────────┘
```
---
## 2. 系统架构
### 2.1 文件结构
```
D:\001\1+2+N\dnxz\Dnxz\
├── openviking_mcp_server.py # MCP服务器实现
├── viking_data\ # OpenViking数据目录
│ ├── .agfs\
│ │ └── config.yaml # AGFS配置
│ ├── vectordb\ # 向量数据库
│ │ └── context\ # 集合存储
│ │ ├── collection_meta.json
│ │ ├── index\ # 索引数据
│ │ └── store\ # 存储文件
│ └── viking\ # Viking元数据
│ ├── agent\
│ ├── resources\ # 资源文件索引
│ ├── session\
│ └── user\
└── docs\ # 待索引的文档
├── P\ # 个人文档
├── 风机说明书\ # 风机技术文档 (254个PDF)
└── ...
C:\Users\fenci\
└── .openviking\
└── ov.conf # OpenViking配置文件
```
### 2.2 OpenViking配置
**文件**: `C:\Users\fenci\.openviking\ov.conf`
```json
{
"embedding": {
"dense": {
"api_base": "http://192.168.1.100:11434/v1",
"api_key": "ollama",
"provider": "openai",
"dimension": 1024,
"model": "qwen3-embedding:0.6b"
}
}
}
```
**配置说明**:
| 参数 | 说明 | 示例值 |
|-----|------|-------|
| `api_base` | Ollama API地址 | `http://192.168.1.100:11434/v1` |
| `api_key` | API密钥 | `ollama` |
| `provider` | API提供商 | `openai` |
| `dimension` | 向量维度 | `1024` |
| `model` | 嵌入模型 | `qwen3-embedding:0.6b` |
### 2.3 AGFS配置
**文件**: `D:\001\1+2+N\dnxz\Dnxz\viking_data\.agfs\config.yaml`
```yaml
plugins:
localfs:
config:
local_dir: D:\001\1+2+N\dnxz\Dnxz\viking_data\viking
enabled: true
path: /local
queuefs:
enabled: true
path: /queue
serverinfofs:
config:
version: 1.0.0
enabled: true
path: /serverinfo
server:
address: :1833
log_level: warn
```
---
## 3. 安装依赖
### 3.1 Python环境
- **Python版本**: 3.13+
- **安装路径**: `C:\Users\fenci\AppData\Local\Packages\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\`
### 3.2 必需包
```bash
# 安装OpenViking
pip install openviking
# 安装MCP SDK
pip install mcp
# 验证安装
python -c "import openviking; print(openviking.__version__)"
# 输出: 0.1.17
python -c "import mcp; print(mcp.__version__)"
# 输出: 1.25.0
```
### 3.3 Ollama服务
需要运行Ollama服务，并安装嵌入模型：
```bash
# 启动Ollama
ollama serve
# 安装嵌入模型
ollama pull qwen3-embedding:0.6b
```
---
## 4. 配置详解
### 4.1 MCP服务器环境变量
| 环境变量 | 说明 | 示例值 |
|---------|------|-------|
| `OPENVIKING_DATA_PATH` | OpenViking数据目录 | `D:\001\1+2+N\dnxz\Dnxz\viking_data` |
| `OPENVIKING_DOCS_PATH` | 待索引文档目录 | `D:\001\1+2+N\dnxz\Dnxz\docs` |
| `OPENVIKING_CONFIG_FILE` | 配置文件路径 | `C:\Users\fenci\.openviking\ov.conf` |
| `PYTHONIOENCODING` | Python输出编码 | `utf-8` |
| `PYTHONUTF8` | UTF-8模式 | `1` |
### 4.2 OpenCode MCP配置
**文件**: `C:\Users\fenci\.config\opencode\opencode.json`
```json
{
"mcp": {
"openviking": {
"type": "local",
"command": [
"C:\\Users\\fenci\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\\python.exe",
"D:\\001\\1+2+N\\dnxz\\Dnxz\\openviking_mcp_server.py"
],
"environment": {
"OPENVIKING_DATA_PATH": "D:\\001\\1+2+N\\dnxz\\Dnxz\\viking_data",
"OPENVIKING_DOCS_PATH": "D:\\001\\1+2+N\\dnxz\\Dnxz\\docs",
"OPENVIKING_CONFIG_FILE": "C:\\Users\\fenci\\.openviking\\ov.conf",
"PYTHONIOENCODING": "utf-8",
"PYTHONUTF8": "1"
},
"enabled": true,
"timeout": 20000
}
}
}
```
---
## 5. MCP服务器实现
### 5.1 完整代码
**文件**: `D:\001\1+2+N\dnxz\Dnxz\openviking_mcp_server.py`
```python
#!/usr/bin/env python3
"""OpenViking MCP Server - 使用官方MCP Python SDK"""
import os
import sys
import json
import logging
logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
from mcp.server.fastmcp import FastMCP
try:
import openviking as ov
except ImportError:
print("Error: openviking not found", file=sys.stderr)
sys.exit(1)
mcp = FastMCP("OpenViking")
_client = None
def get_client():
"""获取或初始化OpenViking客户端"""
global _client
if _client is None:
data_path = os.environ.get("OPENVIKING_DATA_PATH", "./viking_data")
_client = ov.SyncOpenViking(path=data_path)
_client.initialize()
return _client
@mcp.tool()
def openviking_find(query: str, limit: int = 10) -> str:
"""语义搜索OpenViking知识库"""
try:
client = get_client()
results = client.find(query, target_uri="viking://", limit=limit)
formatted = []
for r in results.resources[:limit]:
try:
preview = client.read(r.uri)[:500]
except:
preview = "Error reading"
formatted.append({"uri": r.uri, "score": round(r.score, 4), "preview": preview})
return json.dumps(formatted, ensure_ascii=False, indent=2)
except Exception as e:
return json.dumps({"error": str(e)})
@mcp.tool()
def openviking_read(uri: str) -> str:
"""从指定URI读取完整内容"""
try:
return get_client().read(uri)
except Exception as e:
return f"Error: {e}"
@mcp.tool()
def openviking_glob(pattern: str) -> str:
"""使用glob模式匹配文件"""
try:
results = get_client().glob(pattern, uri="viking://")
return json.dumps(results, ensure_ascii=False, indent=2)
except Exception as e:
return json.dumps({"error": str(e)})
@mcp.tool()
def openviking_abstract(uri: str) -> str:
"""获取资源的L0摘要"""
try:
return get_client().abstract(uri)
except Exception as e:
return f"Error: {e}"
@mcp.tool()
def openviking_overview(uri: str) -> str:
"""获取资源的L1概览"""
try:
return get_client().overview(uri)
except Exception as e:
return f"Error: {e}"
@mcp.tool()
def openviking_grep(pattern: str, case_insensitive: bool = False) -> str:
"""全文内容搜索"""
try:
results = get_client().grep("viking://", pattern, case_insensitive=case_insensitive)
return json.dumps(results, ensure_ascii=False, indent=2)
except Exception as e:
return json.dumps({"error": str(e)})
if __name__ == "__main__":
mcp.run(transport="stdio")
```
### 5.2 可用工具
| 工具名 | 功能 | 参数 |
|-------|------|------|
| `openviking_find` | 语义搜索 | `query`, `limit` |
| `openviking_read` | 读取内容 | `uri` |
| `openviking_glob` | 模式匹配 | `pattern` |
| `openviking_abstract` | L0摘要 | `uri` |
| `openviking_overview` | L1概览 | `uri` |
| `openviking_grep` | 全文搜索 | `pattern`, `case_insensitive` |
---
## 6. OpenCode集成
### 6.1 配置位置
OpenCode MCP配置位于:
- **全局配置**: `C:\Users\fenci\.config\opencode\opencode.json`
- **工作区配置**: `D:\001\1+2+N\dnxz\Dnxz\.opencode\opencode.json`
### 6.2 完整配置示例
```json
{
"plugin": ["oh-my-opencode"],
"$schema": "https://opencode.ai/config.json",
"mcp": {
"openviking": {
"type": "local",
"command": [
"C:\\Users\\fenci\\AppData\\Local\\Microsoft\\WindowsApps\\PythonSoftwareFoundation.Python.3.13_qbz5n2kfra8p0\\python.exe",
"D:\\001\\1+2+N\\dnxz\\Dnxz\\openviking_mcp_server.py"
],
"environment": {
"OPENVIKING_DATA_PATH": "D:\\001\\1+2+N\\dnxz\\Dnxz\\viking_data",
"OPENVIKING_DOCS_PATH": "D:\\001\\1+2+N\\dnxz\\Dnxz\\docs",
"OPENVIKING_CONFIG_FILE": "C:\\Users\\fenci\\.openviking\\ov.conf",
"PYTHONIOENCODING": "utf-8",
"PYTHONUTF8": "1"
},
"enabled": true,
"timeout": 20000
},
"context7": {
"type": "remote",
"url": "https://mcp.context7.com/mcp",
"enabled": true
},
"gh_grep": {
"type": "remote",
"url": "https://mcp.grep.app",
"enabled": true
}
}
}
```
### 6.3 验证配置
```bash
# 测试MCP服务器
cd D:\001\1+2+N\dnxz\Dnxz
set OPENVIKING_DATA_PATH=D:\001\1+2+N\dnxz\Dnxz\viking_data
set OPENVIKING_CONFIG_FILE=C:\Users\fenci\.openviking\ov.conf
python openviking_mcp_server.py
# 测试初始化
# 输入: {"method": "initialize", "params": {...}}
# 输出: {"jsonrpc": "2.0", "result": {...}}
```
---
## 7. 使用指南
### 7.1 在OpenCode中使用
**启动新会话后**，直接使用以下命令：
```
使用 openviking 工具搜索"维斯塔斯接地"
```
OpenCode会自动调用以下工具：
1. `openviking_find` - 语义搜索
2. `openviking_read` - 读取内容
3. `openviking_overview` - 获取概览
### 7.2 工具调用示例
#### 语义搜索
```python
# 调用 openviking_find
参数: {
"query": "维斯塔斯接地",
"limit": 10
}
返回: [
{
"uri": "viking://resources/test_wind/test_wind_4.md",
"score": 0.5763,
"preview": "Vestas Earthing System..."
}
]
```
#### 文件匹配
```python
# 调用 openviking_glob
参数: {
"pattern": "**/*接地*.pdf"
}
返回: {
"matches": [
"viking://resources/docs_auto_sync/0000-3388.pdf"
],
"count": 1
}
```
#### 全文搜索
```python
# 调用 openviking_grep
参数: {
"pattern": "earthing system",
"case_insensitive": true
}
返回: {
"matches": [...],
"count": N
}
```
---
## 8. 数据管理
### 8.1 添加文档到知识库
```python
import openviking as ov
import os
os.environ['OPENVIKING_DATA_PATH'] = r'D:\001\1+2+N\dnxz\Dnxz\viking_data'
os.environ['OPENVIKING_CONFIG_FILE'] = r'C:\Users\fenci\.openviking\ov.conf'
client = ov.SyncOpenViking(path=r'D:\001\1+2+N\dnxz\Dnxz\viking_data')
client.initialize()
# 添加文档
client.add_resource(path=r'D:\001\1+2+N\dnxz\Dnxz\docs')
# 等待处理完成
client.wait_processed(timeout=600)
client.close()
```
### 8.2 数据目录说明
| 目录 | 说明 |
|-----|------|
| `vectordb/` | 向量数据库（可删除重建） |
| `viking/resources/` | 资源文件索引 |
| `.agfs/config.yaml` | AGFS服务配置 |
### 8.3 重置数据库
```powershell
# 1. 终止所有Python进程
taskkill /F /IM python.exe /T
taskkill /F /F /IM python3.13.exe /T
# 2. 删除向量数据库
Remove-Item -Recurse -Force "D:\001\1+2+N\dnxz\Dnxz\viking_data\vectordb"
# 3. 重新初始化
python -c "
import openviking as ov
client = ov.SyncOpenViking(path='./viking_data')
client.initialize()
client.close()
"
```
---
## 9. 故障排查
### 9.1 常见错误
#### 错误1: `AGFS failed to start within 5.0s`
**原因**: AGFS服务启动超时
**解决**:
1. 检查Ollama服务是否运行: `ollama serve`
2. 检查配置文件中API地址是否正确
#### 错误2: `Collection 'context' does not exist`
**原因**: 数据库未正确初始化或损坏
**解决**:
1. 终止所有Python进程
2. 删除vectordb目录
3. 重新初始化
#### 错误3: `LOCK file in use`
**原因**: 多个进程同时访问数据库
**解决**:
```powershell
# 查找并终止占用进程
tasklist | findstr python
# 删除LOCK文件
Remove-Item "D:\001\1+2+N\dnxz\Dnxz\viking_data\vectordb\context\store\LOCK"
```
#### 错误4: `'utf-8' codec can't decode byte`
**原因**: 数据库文件编码损坏
**解决**:
1. 完全删除vectordb目录
2. 重新初始化
### 9.2 诊断命令
```powershell
# 检查Ollama服务
curl http://192.168.1.100:11434/api/tags
# 检查AGFS进程
tasklist | findstr agfs
# 检查端口占用
netstat -an | findstr 1833
# 测试OpenViking
python -c "
import openviking as ov
client = ov.SyncOpenViking(path='./viking_data')
client.initialize()
print('OK:', client.is_healthy())
"
```
---
## 10. 最佳实践
### 10.1 性能优化
1. **避免同时运行多个MCP实例**
- 多个进程会导致数据库锁竞争
- 每次只运行一个OpenCode会话
2. **合理设置超时时间**
- 复杂搜索建议30秒以上
- `timeout: 30000`
3. **定期清理临时文件**
- 删除空的.md文件
- 清理LOCK文件
### 10.2 数据安全
1. **定期备份**
```powershell
# 备份viking_data
Copy-Item -Recurse "D:\001\1+2+N\dnxz\Dnxz\viking_data" "D:\001\1+2+N\dnxz\Dnxz\viking_data_backup"
```
2. **版本控制**
- 记录每次添加的文档
- 保留配置文件备份
### 10.3 维护计划
| 任务 | 频率 | 说明 |
|-----|------|------|
| 检查数据库健康 | 每周 | 运行 `client.is_healthy()` |
| 清理临时文件 | 每月 | 删除空文件和临时数据 |
| 重建索引 | 季度 | 删除vectordb后重新添加文档 |
| 备份数据 | 每周 | 备份整个viking_data目录 |
---
## 附录
### A. 相关资源
- **OpenViking GitHub**: https://github.com/volcengine/OpenViking
- **OpenCode**: https://github.com/anomalyco/opencode
- **MCP协议**: https://modelcontextprotocol.io
- **Ollama**: https://ollama.com
### B. 版本信息
| 组件 | 版本 |
|-----|------|
| OpenViking | 0.1.17 |
| MCP SDK | 1.25.0 |
| Python | 3.13.12 |
| 嵌入模型 | qwen3-embedding:0.6b |
### C. 联系方式
如有问题，请检查：
1. Ollama服务是否正常运行
2. 数据库文件是否被其他进程占用
3. 配置文件路径是否正确
---
**文档版本**: 1.0
**更新时间**: 2026-02-19
**作者**: AI助手
