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(mcp): advertise tool behavior annotations (#5075)
z1gona86caca7010e
diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex 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, Fieldfrom 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.pynew file mode 100644index 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