Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: add MCP integration guide (EN + ZH) (#518)
r266-tech277d6e21df91
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdnew file mode 100644index 000000000..e85161017--- /dev/null+++ b/docs/en/guides/06-mcp-integration.md@@ -0,0 +1,230 @@+# MCP Integration Guide++OpenViking can be used as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, allowing any MCP-compatible client to access its memory and resource capabilities.++## Transport Modes++OpenViking supports two MCP transport modes:++| | HTTP (SSE) | stdio |+|---|---|---|+| **How it works** | Single long-running server process; clients connect via HTTP | Host spawns a new OpenViking process per session |+| **Multi-session safe** | ✅ Yes — single process, no lock contention | ⚠️ **No** — multiple processes contend for the same data directory |+| **Recommended for** | Production, multi-agent, multi-session | Single-session local development only |+| **Setup complexity** | Requires running `openviking-server` separately | Zero setup — host manages the process |++### Choosing the Right Transport++- **Use HTTP** if your host opens multiple sessions, runs multiple agents, or needs concurrent access.+- **Use stdio** only for single-session, single-agent local setups where simplicity is the priority.++> ⚠️ **Important:** When an MCP host spawns multiple stdio OpenViking processes (e.g., one per chat session), all instances compete for the same underlying data directory. This causes **lock/resource contention** in the storage layer (AGFS and VectorDB).+>+> Symptoms include misleading errors such as:+> - `Collection 'context' does not exist`+> - `Transport closed`+> - Intermittent search failures+>+> **The root cause is not a broken index** — it is multiple processes contending for the same storage files. Switch to HTTP mode to resolve this. See [Troubleshooting](#troubleshooting) for details.++## Setup++### Prerequisites++1. OpenViking installed (`pip install openviking` or from source)+2. A valid configuration file (see [Configuration Guide](01-configuration.md))+3. For HTTP mode: `openviking-server` running (see [Deployment Guide](03-deployment.md))++### HTTP Mode (Recommended)++Start the OpenViking server first:++```bash+openviking-server --config /path/to/config.yaml+# Default: http://localhost:1933+```++Then configure your MCP client to connect via HTTP.++### stdio Mode++No separate server needed — the MCP host spawns OpenViking directly.++## Client Configuration++### Claude Code (CLI)++**HTTP mode:**++```bash+claude mcp add openviking \+ --transport sse \+ "http://localhost:1933/mcp"+```++**stdio mode:**++```bash+claude mcp add openviking \+ --transport stdio \+ -- python -m openviking.server --transport stdio \+ --config /path/to/config.yaml+```++### Claude Desktop++Edit `claude_desktop_config.json`:++**HTTP mode:**++```json+{+ "mcpServers": {+ "openviking": {+ "url": "http://localhost:1933/mcp"+ }+ }+}+```++**stdio mode:**++```json+{+ "mcpServers": {+ "openviking": {+ "command": "python",+ "args": [+ "-m", "openviking.server",+ "--transport", "stdio",+ "--config", "/path/to/config.yaml"+ ]+ }+ }+}+```++### Cursor++In Cursor Settings → MCP:++**HTTP mode:**++```json+{+ "mcpServers": {+ "openviking": {+ "url": "http://localhost:1933/mcp"+ }+ }+}+```++**stdio mode:**++```json+{+ "mcpServers": {+ "openviking": {+ "command": "python",+ "args": [+ "-m", "openviking.server",+ "--transport", "stdio",+ "--config", "/path/to/config.yaml"+ ]+ }+ }+}+```++### OpenClaw++In your OpenClaw configuration (`openclaw.json` or `openclaw.yaml`):++**HTTP mode (recommended):**++```json+{+ "mcp": {+ "servers": {+ "openviking": {+ "url": "http://localhost:1933/mcp"+ }+ }+ }+}+```++**stdio mode:**++```json+{+ "mcp": {+ "servers": {+ "openviking": {+ "command": "python",+ "args": [+ "-m", "openviking.server",+ "--transport", "stdio",+ "--config", "/path/to/config.yaml"+ ]+ }+ }+ }+}+```++## Available MCP Tools++Once connected, OpenViking exposes the following MCP tools:++| Tool | Description |+|------|-------------|+| `search` | Semantic search across memories and resources |+| `add_memory` | Store a new memory |+| `add_resource` | Add a resource (file, text, URL) |+| `get_status` | Check system health and component status |+| `list_memories` | Browse stored memories |+| `list_resources` | Browse stored resources |++Refer to OpenViking's tool documentation for full parameter details.++## Troubleshooting++### `Collection 'context' does not exist`++**Likely cause:** Multiple stdio MCP instances contending for the same data directory.++**Fix:** Switch to HTTP mode. If you must use stdio, ensure only one OpenViking process accesses a given data directory at a time.++### `Transport closed`++**Likely cause:** The MCP stdio process crashed or was killed due to resource contention. Can also occur when a client holds a stale connection after the backend was restarted.++**Fix:**+1. Switch to HTTP mode to avoid contention.+2. If using HTTP: reload the MCP connection in your client (restart the session or reconnect).++### Connection refused on HTTP endpoint++**Likely cause:** `openviking-server` is not running, or is running on a different port.++**Fix:** Verify the server is running:++```bash+curl http://localhost:1933/health+# Expected: {"status": "ok"}+```++### Authentication errors++**Likely cause:** API key mismatch between client config and server config.++**Fix:** Ensure the API key in your MCP client configuration matches the one in your OpenViking server configuration. See [Authentication Guide](04-authentication.md).++## References++- [MCP Specification](https://modelcontextprotocol.io/)+- [OpenViking Configuration](01-configuration.md)+- [OpenViking Deployment](03-deployment.md)+- [Related issue: stdio contention (#473)](https://github.com/volcengine/OpenViking/issues/473)diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdnew file mode 100644index 000000000..7ed728cda--- /dev/null+++ b/docs/zh/guides/06-mcp-integration.md@@ -0,0 +1,230 @@+# MCP 集成指南++OpenViking 可以作为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器使用,任何兼容 MCP 的客户端都可以访问其记忆和资源能力。++## 传输模式++OpenViking 支持两种 MCP 传输模式:++| | HTTP (SSE) | stdio |+|---|---|---|+| **工作方式** | 单个长期运行的服务器进程;客户端通过 HTTP 连接 | 宿主为每个会话生成一个新的 OpenViking 进程 |+| **多会话安全** | ✅ 是 — 单进程,无锁竞争 | ⚠️ **否** — 多进程争用同一数据目录 |+| **推荐用于** | 生产环境、多 Agent、多会话 | 仅限单会话本地开发 |+| **配置复杂度** | 需要单独运行 `openviking-server` | 零配置 — 宿主管理进程 |++### 选择合适的传输模式++- **使用 HTTP**:如果你的宿主会打开多个会话、运行多个 Agent,或需要并发访问。+- **使用 stdio**:仅在单会话、单 Agent 的本地环境中,且追求简单时使用。++> ⚠️ **重要提示:** 当 MCP 宿主为每个会话生成独立的 stdio OpenViking 进程时(例如每个聊天会话一个进程),所有实例会争用同一底层数据目录。这会导致存储层(AGFS 和 VectorDB)的 **锁/资源竞争**。+>+> 表现为以下误导性错误:+> - `Collection 'context' does not exist`+> - `Transport closed`+> - 间歇性搜索失败+>+> **根因不是索引损坏** — 而是多个进程争用同一存储文件。切换到 HTTP 模式即可解决。详见[故障排除](#故障排除)。++## 配置++### 前提条件++1. 已安装 OpenViking(`pip install openviking` 或从源码安装)+2. 有效的配置文件(参见[配置指南](01-configuration.md))+3. HTTP 模式需要:`openviking-server` 正在运行(参见[部署指南](03-deployment.md))++### HTTP 模式(推荐)++首先启动 OpenViking 服务器:++```bash+openviking-server --config /path/to/config.yaml+# 默认地址:http://localhost:1933+```++然后配置你的 MCP 客户端通过 HTTP 连接。++### stdio 模式++无需单独启动服务器 — MCP 宿主直接启动 OpenViking。++## 客户端配置++### Claude Code (CLI)++**HTTP 模式:**++```bash+claude mcp add openviking \+ --transport sse \+ "http://localhost:1933/mcp"+```++**stdio 模式:**++```bash+claude mcp add openviking \+ --transport stdio \+ -- python -m openviking.server --transport stdio \+ --config /path/to/config.yaml+```++### Claude Desktop++编辑 `claude_desktop_config.json`:++**HTTP 模式:**++```json+{+ "mcpServers": {+ "openviking": {+ "url": "http://localhost:1933/mcp"+ }+ }+}+```++**stdio 模式:**++```json+{+ "mcpServers": {+ "openviking": {+ "command": "python",+ "args": [+ "-m", "openviking.server",+ "--transport", "stdio",+ "--config", "/path/to/config.yaml"+ ]+ }+ }+}+```++### Cursor++在 Cursor 设置 → MCP 中配置:++**HTTP 模式:**++```json+{+ "mcpServers": {+ "openviking": {+ "url": "http://localhost:1933/mcp"+ }+ }+}+```++**stdio 模式:**++```json+{+ "mcpServers": {+ "openviking": {+ "command": "python",+ "args": [+ "-m", "openviking.server",+ "--transport", "stdio",+ "--config", "/path/to/config.yaml"+ ]+ }+ }+}+```++### OpenClaw++在 OpenClaw 配置文件(`openclaw.json` 或 `openclaw.yaml`)中:++**HTTP 模式(推荐):**++```json+{+ "mcp": {+ "servers": {+ "openviking": {+ "url": "http://localhost:1933/mcp"+ }+ }+ }+}+```++**stdio 模式:**++```json+{+ "mcp": {+ "servers": {+ "openviking": {+ "command": "python",+ "args": [+ "-m", "openviking.server",+ "--transport", "stdio",+ "--config", "/path/to/config.yaml"+ ]+ }+ }+ }+}+```++## 可用的 MCP 工具++连接后,OpenViking 提供以下 MCP 工具:++| 工具 | 说明 |+|------|------|+| `search` | 跨记忆和资源的语义搜索 |+| `add_memory` | 存储新记忆 |+| `add_resource` | 添加资源(文件、文本、URL) |+| `get_status` | 检查系统健康状态和组件状态 |+| `list_memories` | 浏览已存储的记忆 |+| `list_resources` | 浏览已存储的资源 |++完整参数详情请参考 OpenViking 的工具文档。++## 故障排除++### `Collection 'context' does not exist`++**可能原因:** 多个 stdio MCP 实例争用同一数据目录。++**解决方案:** 切换到 HTTP 模式。如果必须使用 stdio,请确保同一时间只有一个 OpenViking 进程访问给定的数据目录。++### `Transport closed`++**可能原因:** MCP stdio 进程因资源竞争而崩溃或被终止。也可能发生在后端重启后客户端持有过期连接时。++**解决方案:**+1. 切换到 HTTP 模式以避免竞争。+2. 如果使用 HTTP:在客户端中重新加载 MCP 连接(重启会话或重新连接)。++### HTTP 端点连接被拒绝++**可能原因:** `openviking-server` 未运行,或运行在不同端口上。++**解决方案:** 验证服务器是否正在运行:++```bash+curl http://localhost:1933/health+# 预期返回:{"status": "ok"}+```++### 认证错误++**可能原因:** 客户端配置与服务器配置中的 API 密钥不匹配。++**解决方案:** 确保 MCP 客户端配置中的 API 密钥与 OpenViking 服务器配置中的一致。参见[认证指南](04-authentication.md)。++## 参考++- [MCP 规范](https://modelcontextprotocol.io/)+- [OpenViking 配置](01-configuration.md)+- [OpenViking 部署](03-deployment.md)+- [相关 Issue:stdio 竞争问题 (#473)](https://github.com/volcengine/OpenViking/issues/473)