Skip to content

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

feat(mcp): advertise tool behavior annotations (#5075)

z1gona86caca7010e
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.py
index e1d747646..ade7b8149 100644
--- a/openviking/server/mcp_endpoint.py
+++ b/openviking/server/mcp_endpoint.py
@@ -32,6 +32,7 @@ from mcp.types import (
ContentBlock,
ImageContent,
TextContent,
+ ToolAnnotations,
)
from pydantic import BaseModel, Field
from starlette.requests import Request
@@ -245,6 +246,32 @@ mcp = FastMCP(
stateless_http=True,
)
+# Each static profile describes the tool's most consequential supported mode.
+_READ_ONLY_TOOL_ANNOTATIONS = ToolAnnotations(
+ readOnlyHint=True,
+ destructiveHint=False,
+ idempotentHint=True,
+ openWorldHint=False,
+)
+_DESTRUCTIVE_TOOL_ANNOTATIONS = ToolAnnotations(
+ readOnlyHint=False,
+ destructiveHint=True,
+ idempotentHint=False,
+ openWorldHint=False,
+)
+_RETRY_SAFE_DESTRUCTIVE_TOOL_ANNOTATIONS = ToolAnnotations(
+ readOnlyHint=False,
+ destructiveHint=True,
+ idempotentHint=True,
+ openWorldHint=False,
+)
+_OPEN_WORLD_DESTRUCTIVE_TOOL_ANNOTATIONS = ToolAnnotations(
+ readOnlyHint=False,
+ destructiveHint=True,
+ idempotentHint=False,
+ openWorldHint=True,
+)
+
# -- find / search ---------------------------------------------------------
@@ -258,7 +285,7 @@ def _resolve_context_type_filter(
raise InvalidArgumentError(str(exc)) from exc
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def find(
query: str,
target_uri: str = "",
@@ -311,7 +338,7 @@ _MCP_CONTEXT_ONLY_ALIASES = {
}
[email protected](annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def search(
query: str,
target_uri: str = "",
@@ -634,7 +661,7 @@ def _mcp_media_download_hint(uri: str) -> str:
)
[email protected](structured_output=False)
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS, structured_output=False)
async def read(
uris: str | list[str],
offset: int = 0,
@@ -775,7 +802,7 @@ async def read(
# -- list ------------------------------------------------------------------
[email protected](name="list")
[email protected](name="list", annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def ls(
uri: str = "viking://",
recursive: bool = False,
@@ -856,7 +883,7 @@ def _tree_abstract(entry: Dict[str, Any]) -> str:
return " ".join(abstract.split())
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def tree(
uri: str = "viking://",
level_limit: int = 3,
@@ -935,7 +962,7 @@ class StoreMessage(BaseModel):
content: str = Field(description="Message text content")
[email protected](annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def remember(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
@@ -960,7 +987,7 @@ async def remember(messages: list[StoreMessage]) -> str:
# -- write -----------------------------------------------------------------
[email protected](annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def write(
uri: str,
content: str,
@@ -1000,7 +1027,7 @@ async def write(
return message + _indexing_hint(result)
[email protected](annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def edit(
uri: str,
old_string: str,
@@ -1159,7 +1186,7 @@ async def _maybe_sitemap_hint(path: str) -> str:
return ""
[email protected](annotations=_OPEN_WORLD_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def add_resource(
path: str = "",
temp_file_id: str = "",
@@ -1451,7 +1478,7 @@ def _format_skill_install_result(result: Dict[str, Any], *, list_only: bool) ->
return "\n".join(lines)
[email protected](annotations=_OPEN_WORLD_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def add_skill(
data: str = "",
path: str = "",
@@ -1616,7 +1643,7 @@ async def add_skill(
# `resume`, `trigger`, `update --interval`, etc.) for those operations.
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def list_watches() -> str:
"""List watch tasks (auto-refresh subscriptions) visible to the current user."""
service = get_service()
@@ -1648,7 +1675,7 @@ async def list_watches() -> str:
return "\n".join(lines)
[email protected](annotations=_RETRY_SAFE_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def cancel_watch(to_uri: str) -> str:
"""Cancel a watch task by its target URI (e.g. "viking://resources/volcengine/OpenViking")."""
from openviking.resource import watch_manager as _wm_mod
@@ -1691,7 +1718,7 @@ async def cancel_watch(to_uri: str) -> str:
# -- grep ------------------------------------------------------------------
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def grep(
uri: str, pattern: str | list[str], case_insensitive: bool = False, node_limit: int = 10
) -> str:
@@ -1760,7 +1787,7 @@ async def grep(
# -- glob ------------------------------------------------------------------
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS)
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()
@@ -1786,7 +1813,7 @@ async def glob(pattern: str, uri: str = "viking://", node_limit: int = 100) -> s
# -- forget ----------------------------------------------------------------
[email protected](annotations=_RETRY_SAFE_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def forget(uri: str, recursive: bool = False) -> str:
"""Permanently delete a viking:// URI from OpenViking. Irreversible — confirm with user before calling.
@@ -1802,7 +1829,7 @@ async def forget(uri: str, recursive: bool = False) -> str:
# -- health ----------------------------------------------------------------
[email protected](annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def health() -> str:
"""Check whether the OpenViking server is healthy."""
try:
diff --git a/tests/unit/test_mcp_tool_annotations.py b/tests/unit/test_mcp_tool_annotations.py
new file mode 100644
index 000000000..83674c72c
--- /dev/null
+++ b/tests/unit/test_mcp_tool_annotations.py
@@ -0,0 +1,38 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+"""Contract tests for MCP tool behavior annotations."""
+
+import openviking.server.mcp_endpoint as mcp_endpoint
+
+
+async def test_mcp_tools_advertise_behavior_annotations():
+ tools = {tool.name: tool for tool in await mcp_endpoint.mcp.list_tools()}
+ expected = {
+ "find": (True, False, True, False),
+ # Context mode can persist and prune the per-session recall ledger.
+ "search": (False, True, False, False),
+ "read": (True, False, True, False),
+ "list": (True, False, True, False),
+ "tree": (True, False, True, False),
+ "remember": (False, True, False, False),
+ "write": (False, True, False, False),
+ "edit": (False, True, False, False),
+ "add_resource": (False, True, False, True),
+ "add_skill": (False, True, False, True),
+ "list_watches": (True, False, True, False),
+ "cancel_watch": (False, True, True, False),
+ "grep": (True, False, True, False),
+ "glob": (True, False, True, False),
+ "forget": (False, True, True, False),
+ "health": (True, False, True, False),
+ }
+ fields = ("readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint")
+
+ observed = {}
+ for name, tool in tools.items():
+ assert tool.annotations is not None
+ annotations = tool.annotations.model_dump(by_alias=True, exclude_none=True)
+ observed[name] = tuple(annotations[field] for field in fields)
+
+ assert observed == expected