Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(mcp): expose context_type filter (#3181)

huangruitengd0305c2f06fc
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.md
index 6f9625280..b20ffc7e4 100644
--- a/docs/en/guides/06-mcp-integration.md
+++ b/docs/en/guides/06-mcp-integration.md
@@ -133,8 +133,8 @@ Once connected, OpenViking exposes 16 tools:
| Tool | Description | Key Parameters |
|------|-------------|----------------|
-| `find` | Fast semantic retrieval without session context | `query`, `target_uri` (optional), `limit`, `min_score`, `level` (optional) |
-| `search` | Deep semantic retrieval with optional session context and intent analysis | `query`, `target_uri` (optional), `session_id` (optional), `limit`, `min_score`, `level` (optional) |
+| `find` | Fast semantic retrieval without session context | `query`, `target_uri` (optional), `limit`, `min_score`, `level` (optional), `context_type` (optional) |
+| `search` | Deep semantic retrieval with optional session context and intent analysis | `query`, `target_uri` (optional), `session_id` (optional), `limit`, `min_score`, `level` (optional), `context_type` (optional) |
| `recall` | Type-quota recall across memory categories | `query`, `quotas` (optional), `max_chars`, `min_score`, `peer_scope`, `other_peer_penalty` (optional) |
| `read` | Read one or more `viking://` URIs | `uris` (single string or array) |
| `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) |
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
index da93871e7..2fad231da 100644
--- a/docs/zh/guides/06-mcp-integration.md
+++ b/docs/zh/guides/06-mcp-integration.md
@@ -125,8 +125,8 @@ claude mcp add --transport http openviking \
| 工具 | 说明 | 主要参数 |
|------|------|----------|
-| `find` | 无 session 上下文的快速语义检索 | `query`, `target_uri`(可选), `limit`, `min_score`, `level`(可选) |
-| `search` | 支持可选 session 上下文和意图分析的深度语义检索 | `query`, `target_uri`(可选), `session_id`(可选), `limit`, `min_score`, `level`(可选) |
+| `find` | 无 session 上下文的快速语义检索 | `query`, `target_uri`(可选), `limit`, `min_score`, `level`(可选), `context_type`(可选) |
+| `search` | 支持可选 session 上下文和意图分析的深度语义检索 | `query`, `target_uri`(可选), `session_id`(可选), `limit`, `min_score`, `level`(可选), `context_type`(可选) |
| `recall` | 按记忆类别配额召回 | `query`, `quotas`(可选), `max_chars`, `min_score`, `peer_scope`, `other_peer_penalty`(可选) |
| `read` | 读取一个或多个 `viking://` URI 的内容 | `uris`(单个字符串或数组) |
| `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) |
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index fcf98f255..c1faff13b 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -21,7 +21,7 @@ import contextvars
import os
from contextlib import asynccontextmanager
from datetime import datetime, timezone
-from typing import Any, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Union
from urllib.parse import quote
from mcp.server.fastmcp import FastMCP
@@ -54,6 +54,7 @@ from openviking.server.local_input_guard import (
from openviking.server.resource_ingest import ingest_temp_upload
from openviking.server.temp_upload_store import TempUploadStore
from openviking.server.upload_token_store import upload_token_store
+from openviking.utils.search_filters import SearchContextTypeInput, merge_search_filter
from openviking_cli.exceptions import (
InvalidArgumentError,
PermissionDeniedError,
@@ -222,6 +223,15 @@ mcp = FastMCP(
# -- find / search ---------------------------------------------------------
+def _resolve_context_type_filter(
+ context_type: Optional[SearchContextTypeInput],
+) -> Optional[Dict[str, Any]]:
+ try:
+ return merge_search_filter(None, context_type=context_type)
+ except ValueError as exc:
+ raise InvalidArgumentError(str(exc)) from exc
+
+
@mcp.tool()
async def find(
query: str,
@@ -229,6 +239,7 @@ async def find(
limit: int = 10,
min_score: float = 0.35,
level: Optional[List[int]] = None,
+ context_type: Optional[Union[str, List[str]]] = None,
) -> str:
"""Fast semantic retrieval without session context. Returns ranked memories, resources, and skills with URI, abstract, and score."""
service = get_service()
@@ -238,6 +249,7 @@ async def find(
target_uri=target_uri,
limit=limit,
score_threshold=min_score,
+ filter=_resolve_context_type_filter(context_type),
level=level,
)
return _format_search_result(result)
@@ -251,6 +263,7 @@ async def search(
limit: int = 10,
min_score: float = 0.35,
level: Optional[List[int]] = None,
+ context_type: Optional[Union[str, List[str]]] = None,
) -> str:
"""Deep semantic retrieval with optional session context and intent analysis. Returns ranked memories, resources, and skills with URI, abstract, and score."""
service = get_service()
@@ -266,6 +279,7 @@ async def search(
session=session,
limit=limit,
score_threshold=min_score,
+ filter=_resolve_context_type_filter(context_type),
level=level,
)
return _format_search_result(result)
diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.py
index 089795eb4..017baed28 100644
--- a/tests/server/test_mcp_endpoint.py
+++ b/tests/server/test_mcp_endpoint.py
@@ -120,6 +120,15 @@ async def test_search_respects_min_score(service):
assert isinstance(result, str)
+async def test_search_tools_expose_only_context_type_parameter():
+ tools = {tool.name: tool for tool in await mcp_endpoint.mcp.list_tools()}
+
+ for tool_name in ("find", "search"):
+ properties = tools[tool_name].inputSchema["properties"]
+ assert "context_type" in properties
+ assert "filter" not in properties
+
+
async def test_find_tool_calls_lightweight_find(service, monkeypatch):
captured = {}
@@ -134,6 +143,7 @@ async def test_find_tool_calls_lightweight_find(service, monkeypatch):
target_uri="viking://resources",
limit=2,
min_score=0.2,
+ context_type=["memory", "resource"],
)
assert result == "No matching context found."
@@ -142,6 +152,11 @@ async def test_find_tool_calls_lightweight_find(service, monkeypatch):
assert captured["target_uri"] == "viking://resources"
assert captured["limit"] == 2
assert captured["score_threshold"] == 0.2
+ assert captured["filter"] == {
+ "op": "must",
+ "field": "context_type",
+ "conds": ["memory", "resource"],
+ }
async def test_search_tool_calls_context_aware_search_with_session(service, monkeypatch):
@@ -175,6 +190,7 @@ async def test_search_tool_calls_context_aware_search_with_session(service, monk
session_id="session-1",
limit=4,
min_score=0.1,
+ context_type="skill",
)
assert result == "No matching context found."
@@ -187,6 +203,11 @@ async def test_search_tool_calls_context_aware_search_with_session(service, monk
assert captured["session"] == session
assert captured["limit"] == 4
assert captured["score_threshold"] == 0.1
+ assert captured["filter"] == {
+ "op": "must",
+ "field": "context_type",
+ "conds": ["skill"],
+ }
async def test_recall_tool_returns_type_quota_memory_groups(service, monkeypatch):