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
feat(server): native MCP endpoint with 9 tools aligned to VikingBot (#1738)
t0sakiccad9c5e0e00
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex e85161017..8368fade3 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -1,211 +1,115 @@# 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.+OpenViking server has a built-in [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoint, allowing any MCP-compatible client to access its memory and resource capabilities over HTTP — no additional processes needed.-## 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+## Prerequisites1. 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)+3. `openviking-server` running (see [Deployment Guide](03-deployment.md))-Start the OpenViking server first:+The MCP endpoint is at `http://<server>:1933/mcp`, sharing the same process and port as the REST API.-```bash-openviking-server --config /path/to/config.yaml-# Default: http://localhost:1933-```--Then configure your MCP client to connect via HTTP.--### stdio Mode+## Verified Platforms-No separate server needed — the MCP host spawns OpenViking directly.+The following platforms have been successfully integrated with OpenViking MCP:-## Client Configuration+| Platform | Integration Method |+|----------|-------------------|+| **Claude Code** | `type: http` |+| **ChatGPT & Codex** | Standard MCP config |+| **Claude.ai / Claude Desktop** | Via MCP-Key2OAuth proxy |+| **Manus** | Standard MCP config |+| **Trae** | Standard MCP config |-### Claude Code (CLI)+## Authentication-**HTTP mode:**+The MCP endpoint shares the same API-Key authentication system as the OpenViking REST API. Pass either header:-```bash-claude mcp add openviking \- --transport sse \- "http://localhost:1933/mcp"-```+- `X-Api-Key: <your-key>`+- `Authorization: Bearer <your-key>`-**stdio mode:**+No authentication is required in local dev mode (server bound to localhost).-```bash-claude mcp add openviking \- --transport stdio \- -- python -m openviking.server --transport stdio \- --config /path/to/config.yaml-```--### Claude Desktop+## Client Configuration-Edit `claude_desktop_config.json`:+### Generic MCP Clients-**HTTP mode:**+Most MCP-compatible platforms (Trae, Manus, Cursor, etc.) use the standard `mcpServers` format:```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"- ]+ "url": "https://your-server.com/mcp",+ "headers": {+ "Authorization": "Bearer your-api-key-here"+ }}}}```-### Cursor--In Cursor Settings → MCP:+### Claude Code-**HTTP mode:**+Claude Code requires `"type": "http"`. Add via CLI:-```json-{- "mcpServers": {- "openviking": {- "url": "http://localhost:1933/mcp"- }- }-}+```bash+claude mcp add --transport http openviking \+ https://your-server.com/mcp \+ --header "Authorization: Bearer your-api-key-here"```-**stdio mode:**+Or in `.mcp.json`:```json{"mcpServers": {"openviking": {- "command": "python",- "args": [- "-m", "openviking.server",- "--transport", "stdio",- "--config", "/path/to/config.yaml"- ]+ "type": "http",+ "url": "https://your-server.com/mcp",+ "headers": {+ "Authorization": "Bearer your-api-key-here"+ }}}}```-### OpenClaw+Add `--scope user` to make the config global (shared across all projects).-In your OpenClaw configuration (`openclaw.json` or `openclaw.yaml`):+### Claude.ai / Claude Desktop (OAuth Proxy)-**HTTP mode (recommended):**+Claude.ai and Claude Desktop Connector require MCP servers to use OAuth authentication — API Keys cannot be passed directly. Use [MCP-Key2OAuth](https://mcp.767911.xyz/) to proxy API Key auth as an OAuth flow:-```json-{- "mcp": {- "servers": {- "openviking": {- "url": "http://localhost:1933/mcp"- }- }- }-}-```+1. Visit https://mcp.767911.xyz/+2. Enter your OpenViking MCP server URL (e.g., `https://your-server.com/mcp`)+3. Generate the proxied URL+4. In Claude.ai / Claude Desktop, enter the generated URL — it will redirect to the proxy for auth+5. After authorization, MCP tools are available-**stdio mode:**+> ⚠️ MCP-Key2OAuth is a community project. OpenViking does not guarantee its security.-```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:+Once connected, OpenViking exposes 9 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.+| Tool | Description | Key Parameters |+|------|-------------|----------------|+| `search` | Semantic search across memories, resources, and skills | `query`, `target_uri` (optional), `limit`, `min_score` |+| `read` | Read one or more `viking://` URIs | `uris` (single string or array) |+| `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) |+| `store` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |+| `add_resource` | Add a local file or URL as a resource | `path`, `description` (optional) |+| `grep` | Regex content search across `viking://` files | `uri`, `pattern` (string or array), `case_insensitive` |+| `glob` | Find files matching a glob pattern | `pattern`, `uri` (optional scope) |+| `forget` | Delete any `viking://` URI (use `search` to find it first) | `uri` |+| `health` | Check OpenViking service health | none |## 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+### Connection refused**Likely cause:** `openviking-server` is not running, or is running on a different port.@@ -227,4 +131,3 @@ curl http://localhost:1933/health- [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.mdindex 7ed728cda..a2ac0c700 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -1,211 +1,115 @@# MCP 集成指南-OpenViking 可以作为 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器使用,任何兼容 MCP 的客户端都可以访问其记忆和资源能力。+OpenViking 服务器内置 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 端点,任何兼容 MCP 的客户端都可以通过 HTTP 直接访问其记忆和资源能力,无需部署额外进程。-## 传输模式--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 模式(推荐)+3. `openviking-server` 正在运行(参见[部署指南](03-deployment.md))-首先启动 OpenViking 服务器:+MCP 端点位于 `http://<server>:1933/mcp`,与 REST API 同进程、同端口。-```bash-openviking-server --config /path/to/config.yaml-# 默认地址:http://localhost:1933-```--然后配置你的 MCP 客户端通过 HTTP 连接。--### stdio 模式+## 已验证的接入平台-无需单独启动服务器 — MCP 宿主直接启动 OpenViking。+以下平台已成功接入并使用 OpenViking MCP:-## 客户端配置+| 平台 | 接入方式 |+|------|----------|+| **Claude Code** | `type: http` 接入 |+| **ChatGPT & Codex** | 标准 MCP 配置 |+| **Claude.ai / Claude Desktop** | 通过 MCP-Key2OAuth 代理接入 |+| **Manus** | 标准 MCP 配置 |+| **Trae** | 标准 MCP 配置 |-### Claude Code (CLI)+## 鉴权方式-**HTTP 模式:**+MCP 端点的鉴权与 OpenViking REST API 完全一致,复用同一套 API-Key 认证系统。传入以下任一 header 即可:-```bash-claude mcp add openviking \- --transport sse \- "http://localhost:1933/mcp"-```+- `X-Api-Key: <your-key>`+- `Authorization: Bearer <your-key>`-**stdio 模式:**+本地开发模式(服务器绑定 localhost)下无需认证。-```bash-claude mcp add openviking \- --transport stdio \- -- python -m openviking.server --transport stdio \- --config /path/to/config.yaml-```--### Claude Desktop+## 客户端配置-编辑 `claude_desktop_config.json`:+### 通用 MCP 客户端-**HTTP 模式:**+大多数支持 MCP 的平台(如 Trae、Manus、Cursor 等)使用标准的 `mcpServers` 配置格式:```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"- ]+ "url": "https://your-server.com/mcp",+ "headers": {+ "Authorization": "Bearer your-api-key-here"+ }}}}```-### Cursor--在 Cursor 设置 → MCP 中配置:+### Claude Code-**HTTP 模式:**+Claude Code 需要额外指定 `"type": "http"`。可通过命令行添加:-```json-{- "mcpServers": {- "openviking": {- "url": "http://localhost:1933/mcp"- }- }-}+```bash+claude mcp add --transport http openviking \+ https://your-server.com/mcp \+ --header "Authorization: Bearer your-api-key-here"```-**stdio 模式:**+或在 `.mcp.json` 中手动配置:```json{"mcpServers": {"openviking": {- "command": "python",- "args": [- "-m", "openviking.server",- "--transport", "stdio",- "--config", "/path/to/config.yaml"- ]+ "type": "http",+ "url": "https://your-server.com/mcp",+ "headers": {+ "Authorization": "Bearer your-api-key-here"+ }}}}```-### OpenClaw+加 `--scope user` 可将配置设为全局(所有项目共享)。-在 OpenClaw 配置文件(`openclaw.json` 或 `openclaw.yaml`)中:+### Claude.ai / Claude Desktop(OAuth 代理鉴权)-**HTTP 模式(推荐):**+Claude.ai 和 Claude Desktop Connector 强制要求 MCP 服务器使用 OAuth 鉴权,无法直接传入 API Key。可借助 [MCP-Key2OAuth](https://mcp.767911.xyz/) 将 API Key 认证代理为 OAuth 流程:-```json-{- "mcp": {- "servers": {- "openviking": {- "url": "http://localhost:1933/mcp"- }- }- }-}-```+1. 访问 https://mcp.767911.xyz/+2. 填入你的 OpenViking MCP 服务器 URL(如 `https://your-server.com/mcp`)+3. 生成代理后的新 URL+4. 在 Claude.ai / Claude Desktop 中填入生成的新 URL,连接时会跳转至代理站进行鉴权+5. 授权完成后即可正常使用-**stdio 模式:**+> ⚠️ MCP-Key2OAuth 为社区项目,OpenViking 不保证其安全性。-```json-{- "mcp": {- "servers": {- "openviking": {- "command": "python",- "args": [- "-m", "openviking.server",- "--transport", "stdio",- "--config", "/path/to/config.yaml"- ]- }- }- }-}-```## 可用的 MCP 工具-连接后,OpenViking 提供以下 MCP 工具:+连接后,OpenViking MCP 端点暴露 9 个工具:-| 工具 | 说明 |-|------|------|-| `search` | 跨记忆和资源的语义搜索 |-| `add_memory` | 存储新记忆 |-| `add_resource` | 添加资源(文件、文本、URL) |-| `get_status` | 检查系统健康状态和组件状态 |-| `list_memories` | 浏览已存储的记忆 |-| `list_resources` | 浏览已存储的资源 |--完整参数详情请参考 OpenViking 的工具文档。+| 工具 | 说明 | 主要参数 |+|------|------|----------|+| `search` | 语义搜索记忆、资源和技能 | `query`, `target_uri`(可选), `limit`, `min_score` |+| `read` | 读取一个或多个 `viking://` URI 的内容 | `uris`(单个字符串或数组) |+| `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) |+| `store` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |+| `add_resource` | 添加本地文件或 URL 作为资源 | `path`, `description`(可选) |+| `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串或数组), `case_insensitive` |+| `glob` | 按 glob 模式匹配文件 | `pattern`, `uri`(可选范围) |+| `forget` | 删除任意 `viking://` URI(先用 `search` 查找) | `uri` |+| `health` | 检查 OpenViking 服务健康状态 | 无 |## 故障排除-### `Collection 'context' does not exist`--**可能原因:** 多个 stdio MCP 实例争用同一数据目录。--**解决方案:** 切换到 HTTP 模式。如果必须使用 stdio,请确保同一时间只有一个 OpenViking 进程访问给定的数据目录。--### `Transport closed`--**可能原因:** MCP stdio 进程因资源竞争而崩溃或被终止。也可能发生在后端重启后客户端持有过期连接时。--**解决方案:**-1. 切换到 HTTP 模式以避免竞争。-2. 如果使用 HTTP:在客户端中重新加载 MCP 连接(重启会话或重新连接)。--### HTTP 端点连接被拒绝+### 连接被拒绝**可能原因:** `openviking-server` 未运行,或运行在不同端口上。@@ -227,4 +131,3 @@ curl http://localhost:1933/health- [MCP 规范](https://modelcontextprotocol.io/)- [OpenViking 配置](01-configuration.md)- [OpenViking 部署](03-deployment.md)-- [相关 Issue:stdio 竞争问题 (#473)](https://github.com/volcengine/OpenViking/issues/473)diff --git a/openviking/server/app.py b/openviking/server/app.pyindex cc220fb6b..13ade23ac 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -205,7 +205,11 @@ def create_app(tracer_module.init_tracer_from_server_config(config)init_otel_log_handler_from_server_config(config)- yield+ # Start MCP session manager (must be active before /mcp requests)+ from openviking.server.mcp_endpoint import mcp_lifespan++ async with mcp_lifespan():+ yield# Cleanupfrom openviking.metrics.global_api import shutdown_metrics_async@@ -409,4 +413,12 @@ def create_app(app.include_router(maintenance_router)app.include_router(bot_router, prefix="/bot/v1")+ # MCP endpoint — serves 5 tools (search, read, store, forget, health)+ # via streamable HTTP for Claude Code and other MCP clients.+ from starlette.routing import Route++ from openviking.server.mcp_endpoint import create_mcp_app++ app.routes.append(Route("/mcp", endpoint=create_mcp_app(), methods=["GET", "POST", "DELETE"]))+return appdiff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pynew file mode 100644index 000000000..5dfc1cb24--- /dev/null+++ b/openviking/server/mcp_endpoint.py@@ -0,0 +1,391 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""MCP (Model Context Protocol) endpoint for OpenViking server.++Exposes 7 tools to Claude Code (or any MCP client) via streamable HTTP:+ search, read, list, store, add_resource, forget, health++Mounted on the FastAPI app at /mcp. The MCP session manager lifecycle is+tied to the FastAPI app lifespan (not a sub-app lifespan) so the task group+is always initialized before requests arrive.++Identity headers (X-OpenViking-Account, X-OpenViking-User, X-OpenViking-Agent)+are extracted from HTTP request scope and propagated via contextvars.+"""++from __future__ import annotations++import contextvars+from contextlib import asynccontextmanager+from typing import Literal, Optional++from mcp.server.fastmcp import FastMCP+from mcp.server.transport_security import TransportSecuritySettings+from pydantic import BaseModel, Field+from starlette.requests import Request+from starlette.responses import JSONResponse+from starlette.types import ASGIApp, Receive, Scope, Send++from openviking.server.auth import resolve_identity+from openviking.server.dependencies import get_service+from openviking.server.identity import RequestContext+from openviking_cli.exceptions import (+ InvalidArgumentError,+ PermissionDeniedError,+ UnauthenticatedError,+)+from openviking_cli.session.user_id import UserIdentifier+from openviking_cli.utils import get_logger++logger = get_logger(__name__)++# ---------------------------------------------------------------------------+# Identity propagation via contextvars+# ---------------------------------------------------------------------------++_mcp_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.ContextVar(+ "_mcp_ctx", default=None+)+++def _get_ctx() -> RequestContext:+ ctx = _mcp_ctx.get()+ if ctx is None:+ raise UnauthenticatedError("MCP request identity not set")+ return ctx+++class _IdentityASGIMiddleware:+ """ASGI middleware: delegates to auth.resolve_identity (the same function+ used by all REST API routes) so authentication logic is never duplicated."""++ def __init__(self, app: ASGIApp):+ self.app = app++ async def __call__(self, scope: Scope, receive: Receive, send: Send):+ if scope["type"] != "http":+ return await self.app(scope, receive, send)++ request = Request(scope)+ try:+ identity = await resolve_identity(+ request,+ x_api_key=request.headers.get("x-api-key"),+ authorization=request.headers.get("authorization"),+ x_openviking_account=request.headers.get("x-openviking-account"),+ x_openviking_user=request.headers.get("x-openviking-user"),+ x_openviking_agent=request.headers.get("x-openviking-agent"),+ )+ except (UnauthenticatedError, PermissionDeniedError, InvalidArgumentError) as exc:+ status = (+ 401+ if isinstance(exc, UnauthenticatedError)+ else (403 if isinstance(exc, PermissionDeniedError) else 400)+ )+ resp = JSONResponse(+ {"jsonrpc": "2.0", "id": None, "error": {"code": -32001, "message": str(exc)}},+ status_code=status,+ )+ return await resp(scope, receive, send)++ ctx = RequestContext(+ user=UserIdentifier(+ identity.account_id or "default",+ identity.user_id or "default",+ identity.agent_id or "default",+ ),+ role=identity.role,+ namespace_policy=identity.namespace_policy,+ )+ token = _mcp_ctx.set(ctx)+ try:+ return await self.app(scope, receive, send)+ finally:+ _mcp_ctx.reset(token)+++# ---------------------------------------------------------------------------+# MCP server + 7 tools (aligned with vikingbot/agent/tools/ov_file.py)+# ---------------------------------------------------------------------------++mcp = FastMCP(+ "openviking",+ transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),+)+++# -- search ----------------------------------------------------------------+++async def search(query: str, target_uri: str = "", limit: int = 10, min_score: float = 0.35) -> str:+ """Search OpenViking context database (memories, resources, skills). Returns ranked results with URI, abstract, and score. Leave target_uri empty to search everything, or pass a viking:// URI to narrow scope."""+ service = get_service()+ ctx = _get_ctx()++ result = await service.search.find(+ query=query,+ ctx=ctx,+ target_uri=target_uri,+ limit=limit,+ score_threshold=min_score,+ )++ items = []+ for ctx_type, contexts in [+ ("memory", result.memories),+ ("resource", result.resources),+ ("skill", result.skills),+ ]:+ for m in contexts:+ items.append((ctx_type, m))++ if not items:+ return "No matching context found."++ lines = []+ for ctx_type, m in items:+ abstract = (m.abstract or m.overview or "(no abstract)").strip()+ lines.append(f"- [{ctx_type} {m.score * 100:.0f}%] {m.uri}\n {abstract}")++ return (+ f"Found {len(items)} item(s):\n\n"+ + "\n".join(lines)+ + "\n\nUse the read tool to expand a URI."+ )+++# -- read ------------------------------------------------------------------+++async def read(uris: str | list[str]) -> str:+ """Read full content from one or more viking:// file URIs. Pass a single URI string or a list for batch reads. For directory listing, use the list tool instead."""+ import asyncio++ service = get_service()+ ctx = _get_ctx()+ uri_list = uris if isinstance(uris, list) else [uris]+ semaphore = asyncio.Semaphore(10)++ async def _read_one(uri: str) -> str:+ async with semaphore:+ try:+ body = await service.fs.read(uri, ctx=ctx)+ if isinstance(body, str) and body.strip():+ return body+ except Exception:+ pass+ return f"(nothing found at {uri})"++ if len(uri_list) == 1:+ return await _read_one(uri_list[0])++ results = await asyncio.gather(*[_read_one(u) for u in uri_list])+ parts = []+ for uri, text in zip(uri_list, results, strict=True):+ parts.append(f"=== {uri} ===\n{text}")+ return "\n\n".join(parts)+++# -- list ------------------------------------------------------------------++[email protected](name="list")+async def ls(uri: str, recursive: bool = False) -> str:+ """List files and subdirectories under a viking:// directory URI. Use recursive=true for deep listing."""+ service = get_service()+ ctx = _get_ctx()++ entries = await service.fs.ls(uri, ctx=ctx, recursive=recursive, output="original")+ if not entries:+ return f"(no entries under {uri})"++ lines = []+ for e in entries:+ name = e.get("name", "?") if isinstance(e, dict) else getattr(e, "name", "?")+ is_dir = e.get("isDir", False) if isinstance(e, dict) else getattr(e, "is_dir", False)+ entry_uri = e.get("uri", "") if isinstance(e, dict) else getattr(e, "uri", "")+ if recursive and entry_uri:+ lines.append(f"[{'dir' if is_dir else 'file'}] {entry_uri}")+ else:+ lines.append(f"[{'dir' if is_dir else 'file'}] {name}")+ return "\n".join(lines)+++# -- store -----------------------------------------------------------------+++class StoreMessage(BaseModel):+ role: Literal["user", "assistant"] = Field(description="Message role")+ content: str = Field(description="Message text content")+++async def store(messages: list[StoreMessage]) -> str:+ """Store information into OpenViking long-term memory. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting."""+ import uuid++ from openviking.message.part import TextPart++ service = get_service()+ ctx = _get_ctx()+ session_id = f"mcp-store-{uuid.uuid4().hex[:12]}"+ session = await service.sessions.get(session_id, ctx, auto_create=True)+ for msg in messages:+ if msg.content:+ session.add_message(msg.role, [TextPart(text=msg.content)])+ await service.sessions.commit_async(session_id, ctx)+ return f"Stored {len(messages)} message(s) and committed for memory extraction."+++# -- add_resource ----------------------------------------------------------+++async def add_resource(path: str, description: str = "") -> str:+ """Add a resource (local file path or URL) to OpenViking. This is an asynchronous operation — the resource will be processed in the background."""+ service = get_service()+ ctx = _get_ctx()+ try:+ result = await service.resources.add_resource(+ path=path,+ ctx=ctx,+ reason=description,+ wait=False,+ )+ root_uri = result.get("root_uri", "")+ return (+ f"Resource added: {root_uri}"+ if root_uri+ else "Resource added (processing in background)."+ )+ except Exception as e:+ return f"Error adding resource: {e}"+++# -- grep ------------------------------------------------------------------+++async def grep(+ uri: str, pattern: str | list[str], case_insensitive: bool = False, node_limit: int = 10+) -> str:+ """Search content in viking:// files using regex patterns (like grep). Supports multiple patterns searched concurrently. Use this for exact text matching; use the search tool for semantic retrieval."""+ import asyncio++ service = get_service()+ ctx = _get_ctx()+ patterns = [pattern] if isinstance(pattern, str) else pattern+ semaphore = asyncio.Semaphore(10)++ async def _grep_one(p: str) -> tuple[str, list[dict]]:+ async with semaphore:+ try:+ result = await service.fs.grep(+ uri,+ p,+ ctx=ctx,+ case_insensitive=case_insensitive,+ node_limit=node_limit,+ )+ return (p, result.get("matches", []))+ except Exception:+ return (p, [])++ results = await asyncio.gather(*[_grep_one(p) for p in patterns])++ merged: dict[str, list[tuple]] = {}+ total = 0+ for p, matches in results:+ total += len(matches)+ for m in matches:+ m_uri = m.get("uri", "?")+ merged.setdefault(m_uri, []).append((m.get("line", "?"), m.get("content", ""), p))++ if not merged:+ return f"No matches found for pattern(s): {', '.join(patterns)}"++ lines = [f"Found {total} match(es) across {len(patterns)} pattern(s):"]+ for m_uri, hits in merged.items():+ hits.sort(key=lambda x: int(x[0]) if str(x[0]).isdigit() else 0)+ lines.append(f"\n{m_uri}")+ for line_no, content, p in hits:+ lines.append(f" L{line_no} [{p}]: {content}")+ return "\n".join(lines)+++# -- glob ------------------------------------------------------------------+++async def glob(pattern: str, uri: str = "viking://", node_limit: int = 100) -> str:+ """Find viking:// files matching a glob pattern (e.g. **/*.md, *.py). Use this for filename matching; use the search tool for content-based retrieval."""+ service = get_service()+ ctx = _get_ctx()++ try:+ result = await service.fs.glob(pattern, ctx=ctx, uri=uri, node_limit=node_limit)+ except Exception as e:+ return f"Error: {e}"++ matches = result.get("matches", [])+ if not matches:+ return f"No files found matching: {pattern}"++ lines = [f"Found {len(matches)} file(s):"]+ for m in matches:+ m_uri = m.get("uri", str(m)) if isinstance(m, dict) else str(m)+ lines.append(f" {m_uri}")+ return "\n".join(lines)+++# -- forget ----------------------------------------------------------------+++async def forget(uri: str) -> str:+ """Permanently delete a viking:// URI from OpenViking. This is irreversible. Only use when the user explicitly asks to forget or delete something. Always confirm with the user before calling this tool. Use the search tool first to find the exact URI, then pass it here."""+ service = get_service()+ ctx = _get_ctx()+ await service.fs.rm(uri, ctx=ctx)+ return f"Deleted: {uri}"+++# -- health ----------------------------------------------------------------+++async def health() -> str:+ """Check whether the OpenViking server is healthy."""+ try:+ service = get_service()+ return f"OpenViking is healthy (service initialized, storage: {type(service.viking_fs).__name__})"+ except Exception as e:+ return f"OpenViking is unhealthy: {e}"+++# ---------------------------------------------------------------------------+# App factory + lifespan+# ---------------------------------------------------------------------------+++@asynccontextmanager+async def mcp_lifespan():+ """Run the MCP session manager. Call this inside the FastAPI lifespan."""+ async with mcp.session_manager.run():+ logger.info(+ "MCP endpoint ready (9 tools: search, read, list, store, add_resource, grep, glob, forget, health)"+ )+ yield+++def create_mcp_app() -> ASGIApp:+ """Create the MCP ASGI app with identity middleware.++ IMPORTANT: call `mcp_lifespan()` inside the FastAPI lifespan BEFORE+ serving requests. The session manager task group must be initialized.+ """+ starlette_app = mcp.streamable_http_app()+ handler = starlette_app.routes[0].app+ return _IdentityASGIMiddleware(handler)diff --git a/pyproject.toml b/pyproject.tomlindex 759e7573d..41fc676f7 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -81,6 +81,7 @@ dependencies = ["cryptography>=42.0.0","argon2-cffi>=23.0.0","lark-oapi>=1.5.3",+ "mcp>=1.27.0",]diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.pynew file mode 100644index 000000000..45a71feb6--- /dev/null+++ b/tests/server/test_mcp_endpoint.py@@ -0,0 +1,269 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++"""Tests for MCP endpoint tools (openviking/server/mcp_endpoint.py).++Tests the tool functions directly by setting up the identity contextvar+and service dependency, avoiding MCP protocol complexity.+"""++import pytest++from openviking.server.dependencies import set_service+from openviking.server.identity import RequestContext, Role+from openviking.server.mcp_endpoint import (+ StoreMessage,+ _get_ctx,+ _mcp_ctx,+ add_resource,+ forget,+ glob,+ grep,+ health,+ read,+ search,+ store,+)+from openviking.server.mcp_endpoint import list_dir as list_tool+from openviking_cli.exceptions import UnauthenticatedError+from openviking_cli.session.user_id import UserIdentifier++DEFAULT_CTX = RequestContext(+ user=UserIdentifier.the_default_user("test_user"),+ role=Role.ROOT,+)++[email protected](autouse=True)+def _set_mcp_identity(service):+ """Set identity contextvar and wire service for all tests."""+ set_service(service)+ token = _mcp_ctx.set(DEFAULT_CTX)+ yield+ _mcp_ctx.reset(token)+++# ---------------------------------------------------------------------------+# _get_ctx+# ---------------------------------------------------------------------------+++def test_get_ctx_returns_set_context():+ ctx = _get_ctx()+ assert ctx.user.user_id == "test_user"+++def test_get_ctx_raises_when_unset():+ token = _mcp_ctx.set(None)+ try:+ with pytest.raises(UnauthenticatedError):+ _get_ctx()+ finally:+ _mcp_ctx.reset(token)+++# ---------------------------------------------------------------------------+# health tool+# ---------------------------------------------------------------------------+++async def test_health_returns_healthy(service):+ result = await health()+ assert "healthy" in result.lower()+ assert "VikingFS" in result+++async def test_health_returns_unhealthy_when_no_service(monkeypatch):+ monkeypatch.setattr(+ "openviking.server.mcp_endpoint.get_service",+ lambda: (_ for _ in ()).throw(RuntimeError("not initialized")),+ )+ result = await health()+ assert "unhealthy" in result.lower()+++# ---------------------------------------------------------------------------+# search tool+# ---------------------------------------------------------------------------+++async def test_search_no_results(service):+ result = await search(query="zzz_nonexistent_query_xyz_12345")+ assert result == "No matching context found."+++async def test_search_returns_formatted_results(service, client_with_resource):+ _, root_uri = client_with_resource+ result = await search(query="resource management semantic search", limit=3)+ assert "Found" in result or "No matching" in result+++async def test_search_with_target_uri(service):+ result = await search(query="test", target_uri="viking://resources", limit=3)+ assert isinstance(result, str)+++async def test_search_respects_min_score(service):+ result = await search(query="test", min_score=0.35)+ assert isinstance(result, str)+++# ---------------------------------------------------------------------------+# read tool+# ---------------------------------------------------------------------------+++async def test_read_nonexistent_uri(service):+ result = await read("viking://user/default/memories/does_not_exist.md")+ assert "nothing found" in result.lower()+++async def test_read_batch(service):+ result = await read(+ [+ "viking://user/default/memories/does_not_exist_1.md",+ "viking://user/default/memories/does_not_exist_2.md",+ ]+ )+ assert "===" in result+ assert "nothing found" in result.lower()+++# ---------------------------------------------------------------------------+# list tool+# ---------------------------------------------------------------------------+++async def test_list_root(service):+ result = await list_tool("viking://user")+ assert isinstance(result, str)+++async def test_list_empty_dir(service):+ ctx = DEFAULT_CTX+ await service.viking_fs.mkdir(+ "viking://user/default/memories/empty_test", ctx=ctx, exist_ok=True+ )+ result = await list_tool("viking://user/default/memories/empty_test")+ assert isinstance(result, str)+++# ---------------------------------------------------------------------------+# store tool+# ---------------------------------------------------------------------------+++async def test_store_single_message(service):+ result = await store(messages=[StoreMessage(role="user", content="The sky is blue")])+ assert "stored" in result.lower()+ assert "1 message" in result+++async def test_store_batch_messages(service):+ result = await store(+ messages=[+ StoreMessage(role="user", content="Remember my favorite color is blue"),+ StoreMessage(role="assistant", content="Noted, your favorite color is blue."),+ ]+ )+ assert "stored" in result.lower()+ assert "2 message" in result+++# ---------------------------------------------------------------------------+# add_resource tool+# ---------------------------------------------------------------------------+++async def test_add_resource_nonexistent_path(service):+ result = await add_resource(path="/tmp/definitely_does_not_exist_xyz.md")+ assert (+ "error" in result.lower() or "not found" in result.lower() or "resource" in result.lower()+ )+++# ---------------------------------------------------------------------------+# forget tool+# ---------------------------------------------------------------------------+++async def test_forget_by_uri_deletes_memory(service):+ ctx = DEFAULT_CTX+ uri = "viking://user/default/memories/test_forget.md"+ await service.viking_fs.mkdir("viking://user/default/memories", ctx=ctx, exist_ok=True)+ await service.viking_fs.write(uri, "test data", ctx=ctx)++ result = await forget(uri=uri)+ assert "deleted" in result.lower()+ assert "test_forget.md" in result+++async def test_forget_by_uri_deletes_resource(service):+ """forget should work on any viking:// URI, not just memories."""+ ctx = DEFAULT_CTX+ uri = "viking://resources/test_forget_resource.md"+ await service.viking_fs.mkdir("viking://resources", ctx=ctx, exist_ok=True)+ await service.viking_fs.write(uri, "resource data", ctx=ctx)++ result = await forget(uri=uri)+ assert "deleted" in result.lower()+++# ---------------------------------------------------------------------------+# grep tool+# ---------------------------------------------------------------------------+++async def test_grep_no_matches(service):+ result = await grep(uri="viking://resources", pattern="zzz_no_match_xyz_99999")+ assert "No matches found" in result+++async def test_grep_single_pattern(service, client_with_resource):+ _, root_uri = client_with_resource+ result = await grep(uri=root_uri, pattern=".*")+ assert isinstance(result, str)+++async def test_grep_multiple_patterns(service):+ result = await grep(uri="viking://resources", pattern=["pattern_a_xyz", "pattern_b_xyz"])+ assert "No matches found" in result+ assert "pattern_a_xyz" in result+ assert "pattern_b_xyz" in result+++async def test_grep_case_insensitive(service):+ result = await grep(uri="viking://resources", pattern="TEST", case_insensitive=True)+ assert isinstance(result, str)+++# ---------------------------------------------------------------------------+# glob tool+# ---------------------------------------------------------------------------+++async def test_glob_no_matches(service):+ result = await glob(pattern="zzz_nonexistent_*.xyz")+ assert "No files found" in result+++async def test_glob_match_all_md(service, client_with_resource):+ _, root_uri = client_with_resource+ result = await glob(pattern="**/*.md", uri=root_uri)+ assert isinstance(result, str)+++async def test_glob_with_uri_scope(service):+ result = await glob(pattern="*", uri="viking://resources")+ assert isinstance(result, str)+++# ---------------------------------------------------------------------------+# Route registration+# ---------------------------------------------------------------------------+++def test_mcp_route_registered(app):+ """Verify the /mcp route exists in the app."""+ mcp_routes = [r for r in app.routes if hasattr(r, "path") and r.path == "/mcp"]+ assert len(mcp_routes) == 1diff --git a/uv.lock b/uv.lockindex 508813016..40ef8b075 100644--- a/uv.lock+++ b/uv.lock@@ -2398,7 +2398,7 @@ wheels = [[[package]]name = "llama-cpp-python"-version = "0.3.20"+version = "0.3.21"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "diskcache" },@@ -2407,7 +2407,7 @@ dependencies = [{ name = "numpy", version = "2.4.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },{ name = "typing-extensions" },]-sdist = { url = "https://files.pythonhosted.org/packages/45/95/c69c47c9c8dda97f712f5864688d13a22b0159aa9adae91a69067a728532/llama_cpp_python-0.3.20.tar.gz", hash = "sha256:70f01b7d915d31c617dc66610a332cb2d51cde84c8b152d09a352206323616f5", size = 59323017, upload-time = "2026-04-03T06:56:32.455Z" }+sdist = { url = "https://files.pythonhosted.org/packages/e6/0f/17c0e400ed17094b360e3bcc07e7fbca890e0042a5a1e9dabb056693d57f/llama_cpp_python-0.3.21.tar.gz", hash = "sha256:533636e23953d1efcf16ddf5862d963405e4bc0bccfc04ba90e9ee7afefefa75", size = 67604365, upload-time = "2026-04-27T05:17:44.296Z" }[[package]]name = "loguru"@@ -3504,6 +3504,7 @@ dependencies = [{ name = "litellm" },{ name = "loguru" },{ name = "markdownify" },+ { name = "mcp" },{ name = "olefile" },{ name = "openai" },{ name = "openpyxl" },@@ -3735,6 +3736,7 @@ requires-dist = [{ name = "llama-cpp-python", marker = "extra == 'local-embed'", specifier = ">=0.3.0" },{ name = "loguru", specifier = ">=0.7.3" },{ name = "markdownify", specifier = ">=0.11.0" },+ { name = "mcp", specifier = ">=1.27.0" },{ name = "mcp", marker = "extra == 'bot'", specifier = ">=1.0.0" },{ name = "msgpack", marker = "extra == 'bot'", specifier = ">=1.0.8" },{ name = "mypy", marker = "extra == 'dev'", specifier = ">=1.0.0" },