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
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""MCP (Model Context Protocol) endpoint for OpenViking server.
Exposes OpenViking tools (filesystem, retrieval, memory, watch management,
health) to Claude Code (or any MCP client) via streamable HTTP; the
`@mcp.tool` registrations below are the authoritative list.
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)
are extracted from HTTP request scope and propagated via contextvars.
"""
from __future__ import annotations
import base64
import contextvars
import dataclasses
import os
import shlex
from contextlib import asynccontextmanager
from datetime import datetime, timezone
from functools import wraps
from pathlib import PurePosixPath
from typing import Annotated, Any, Dict, List, Literal, Optional, Union
from urllib.parse import quote
from mcp.server.fastmcp import Context, FastMCP
from mcp.server.transport_security import TransportSecuritySettings
from mcp.types import (
AudioContent,
CallToolResult,
ContentBlock,
ImageContent,
TextContent,
ToolAnnotations,
)
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.core.path_variables import resolve_path_variables
from openviking.core.retrieval_targets import default_target_directories
from openviking.core.retrieval_types import SearchType
from openviking.core.uri_validation import (
validate_content_target_uri,
validate_request_viking_uri,
)
from openviking.parse.mode import ParseMode, normalize_parse_mode
from openviking.privacy.operations import (
build_privacy_tree,
privacy_field_metadata,
resolve_privacy_field,
)
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.resource.processing_mode import DEFAULT_PROCESSING_MODE, ProcessingMode
from openviking.retrieve.context_assembler import (
DEFAULT_MAX_TOKENS,
MAX_EXCLUDE_URIS,
AssembleParams,
assemble_context,
)
from openviking.retrieve.skill_results import skill_root_uri
from openviking.server.auth import (
_build_request_context,
_extract_api_key,
get_api_key_manager_or_raise,
is_personal_api_key_auth,
normalize_actor_peer_header,
resolve_identity,
should_expose_user_key,
)
from openviking.server.dependencies import get_server_config, get_service
from openviking.server.error_mapping import map_exception
from openviking.server.identity import AuthMode, RequestContext, Role
from openviking.server.local_input_guard import (
TEMP_FILE_ID_RE,
is_remote_resource_source,
looks_like_local_path,
)
from openviking.server.resource_ingest import ingest_temp_upload
from openviking.server.routers.search import context_only_fields_error
from openviking.server.skill_ingest import install_skills
from openviking.server.temp_upload_store import TempUploadStore
from openviking.server.upload_token_store import download_token_store, upload_token_store
from openviking.service.skill_sources import GIT_SKILL_SOURCE_PREFIXES
from openviking.storage.acl import AclSpec
from openviking.utils.media_limits import MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
from openviking.utils.search_filters import (
SearchContextTypeInput,
merge_search_filter,
resolve_context_types,
)
from openviking.utils.skill_processor import SkillProcessor
from openviking.utils.time_decay import validate_event_time_decay_request
from openviking_cli.exceptions import (
FailedPreconditionError,
InvalidArgumentError,
NotFoundError,
OpenVikingError,
PermissionDeniedError,
UnauthenticatedError,
)
from openviking_cli.retrieve import ContextType
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
)
# URL hints from the incoming request, captured by middleware so MCP tools can
# reconstruct the agent-facing public URL without knowing about ASGI/Starlette.
# Only used as a fallback when neither OPENVIKING_PUBLIC_BASE_URL nor
# ServerConfig.public_base_url is set.
_request_url_ctx: contextvars.ContextVar[Optional[dict]] = contextvars.ContextVar(
"_request_url_ctx", default=None
)
def _get_ctx() -> RequestContext:
ctx = _mcp_ctx.get()
if ctx is None:
raise UnauthenticatedError("MCP request identity not set")
return ctx
def _resolve_mcp_workspace_uri(uri: str, ctx: RequestContext) -> str:
"""Resolve MCP workspace URIs, expanding the viking://~ home alias, at its boundary."""
return validate_request_viking_uri(resolve_path_variables(uri), ctx)
def _scope_to_origin(scope: Scope) -> Optional[str]:
"""Derive the public-facing origin (scheme://host) from an ASGI scope.
Resolution order matches openviking.server.oauth.router._public_origin:
1. ``OPENVIKING_PUBLIC_BASE_URL`` environment variable
2. ``app.state.oauth_config.issuer`` (if OAuth enabled)
3. ``X-Forwarded-Proto`` / ``X-Forwarded-Host``
4. scope's own scheme + Host header
"""
import os as _os
env_value = _os.environ.get("OPENVIKING_PUBLIC_BASE_URL", "").strip()
if env_value:
return env_value.rstrip("/")
app = scope.get("app")
if app is not None:
cfg = getattr(app.state, "oauth_config", None)
configured = getattr(cfg, "issuer", None) if cfg else None
if configured:
return configured.rstrip("/")
headers = {
k.decode("latin-1").lower(): v.decode("latin-1") for k, v in scope.get("headers", [])
}
proto = headers.get("x-forwarded-proto") or scope.get("scheme") or "http"
proto = proto.split(",", 1)[0].strip()
host = headers.get("x-forwarded-host") or headers.get("host")
if not host:
server = scope.get("server")
if isinstance(server, (list, tuple)) and len(server) >= 2:
host = f"{server[0]}:{server[1]}" if server[1] else str(server[0])
if not host:
return None
host = host.split(",", 1)[0].strip()
return f"{proto}://{host}"
def _oauth_enabled(scope: Scope) -> bool:
"""Return True if app.state has an oauth_provider (i.e. OAuth is configured)."""
app = scope.get("app")
if app is None:
return False
return getattr(app.state, "oauth_provider", None) is not None
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)
x_api_key = request.headers.get("x-api-key")
authorization = request.headers.get("authorization")
try:
identity = await resolve_identity(
request,
x_api_key=x_api_key,
authorization=authorization,
x_openviking_account=request.headers.get("x-openviking-account"),
x_openviking_user=request.headers.get("x-openviking-user"),
)
actor_peer_id = normalize_actor_peer_header(
request.headers.get("x-openviking-actor-peer")
)
ctx = await _build_request_context(
request,
identity,
actor_peer_id=actor_peer_id,
api_key=_extract_api_key(x_api_key, authorization),
)
except (UnauthenticatedError, PermissionDeniedError, InvalidArgumentError) as exc:
status = (
401
if isinstance(exc, UnauthenticatedError)
else (403 if isinstance(exc, PermissionDeniedError) else 400)
)
headers: dict[str, str] = {}
# When OAuth is enabled and the request is unauthenticated, advertise
# the OAuth 2.0 protected resource metadata so MCP clients (Claude.ai,
# Claude Desktop, etc.) can auto-discover the authorization server
# per RFC 9728 §5.1.
if status == 401 and _oauth_enabled(scope):
origin = _scope_to_origin(scope)
if origin:
headers["WWW-Authenticate"] = (
f'Bearer resource_metadata="{origin}/.well-known/oauth-protected-resource"'
)
resp = JSONResponse(
{"jsonrpc": "2.0", "id": None, "error": {"code": -32001, "message": str(exc)}},
status_code=status,
headers=headers,
)
return await resp(scope, receive, send)
url_info = {
"x_forwarded_proto": request.headers.get("x-forwarded-proto"),
"x_forwarded_host": request.headers.get("x-forwarded-host"),
"host": request.headers.get("host"),
}
ctx_token = _mcp_ctx.set(ctx)
url_token = _request_url_ctx.set(url_info)
try:
return await self.app(scope, receive, send)
finally:
_mcp_ctx.reset(ctx_token)
_request_url_ctx.reset(url_token)
# ---------------------------------------------------------------------------
# MCP server tools (aligned with vikingbot/agent/tools/ov_file.py)
# ---------------------------------------------------------------------------
mcp = FastMCP(
"openviking",
transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
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,
)
class _MCPToolFailure(str):
"""Mark a returned string as a whole-call tool execution failure."""
error: OpenVikingError | None = None
def _mcp_failure(message: str | OpenVikingError) -> _MCPToolFailure:
if isinstance(message, OpenVikingError):
result = _MCPToolFailure(f"{message.code}: {message.message}")
result.error = message
return result
return _MCPToolFailure(message)
def _mcp_error_results(*, structured_output: bool = True):
"""Adapt an already registered tool to return explicit MCP errors.
Apply this above ``@mcp.tool`` so the literal registration remains the
authoritative tool list. Direct Python calls keep the existing return value.
The registered MCP handler preserves business error codes and details and
converts failures to ``CallToolResult(isError=True)``.
"""
def decorator(func):
registered_tool = next(
(tool for tool in mcp._tool_manager.list_tools() if tool.fn is func), None
)
if registered_tool is None:
raise RuntimeError(f"MCP tool is not registered: {func.__name__}")
@wraps(func)
async def wire_handler(*args, **kwargs):
try:
result = await func(*args, **kwargs)
except OpenVikingError as exc:
result = _mcp_failure(exc)
if not isinstance(result, _MCPToolFailure):
return result
message = str(result)
structured = {"result": message}
if result.error is not None:
structured["error"] = {
"code": result.error.code,
"message": result.error.message,
"details": result.error.details,
}
return CallToolResult(
content=[TextContent(type="text", text=message)],
structuredContent=structured if structured_output else None,
isError=True,
)
# Keep the schema and metadata produced by the literal @mcp.tool
# registration. Only replace the callable used at the wire boundary.
registered_tool.fn = wire_handler
@wraps(func)
async def direct_handler(*args, **kwargs):
result = await func(*args, **kwargs)
return str(result) if isinstance(result, _MCPToolFailure) else result
return direct_handler
return decorator
# -- account directory and resource ACL ------------------------------------
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def list_users(
context: Context,
query: str = "",
limit: Annotated[int, Field(ge=1)] = 100,
page: Annotated[int, Field(ge=1)] = 1,
include_credentials: bool = False,
) -> dict[str, Any]:
"""Find users to grant access to in the caller's account. Returns user_id and
matching total by default, including for administrators. query matches a
substring of user_id. include_credentials=true returns all keys to ROOT,
the caller's own key and masked prefixes to ADMIN, and only the caller's own
key to USER authenticated with a personal API key. Other users' keys and
prefixes are omitted for USER. Credential disclosure is forbidden in trusted mode.
Resource manage permission does not grant account administrator privileges.
"""
ctx = _get_ctx()
if include_credentials and ctx.role not in (Role.USER, Role.ADMIN, Role.ROOT):
raise PermissionDeniedError("include_credentials requires USER, ADMIN or ROOT role")
request = context.request_context.request
if include_credentials and not should_expose_user_key(request):
raise PermissionDeniedError("Credential disclosure is disabled in trusted auth mode")
manager = get_api_key_manager_or_raise(request)
result = await manager.list_users_page(
ctx.account_id,
limit=limit,
page=page,
query_filter=query,
expose_key=include_credentials
and (ctx.role != Role.USER or is_personal_api_key_auth(request, ctx)),
mask_keys=ctx.role != Role.ROOT,
hide_other_keys=ctx.role == Role.USER,
viewer_account_id=ctx.account_id,
viewer_user_id=ctx.user.user_id,
)
fields = ("user_id", "role", "api_key", "key_prefix") if include_credentials else ("user_id",)
return {
"users": [{key: user[key] for key in fields if key in user} for user in result["users"]],
"total": result["total"],
}
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def list_groups(context: Context) -> dict[str, Any]:
"""List group IDs that can be granted resource access in the caller's account.
Available to all account users; does not disclose group membership.
"""
ctx = _get_ctx()
manager = get_api_key_manager_or_raise(context.request_context.request)
groups = await manager.get_groups(ctx.account_id)
return {"groups": [{"group_id": group["group_id"]} for group in groups]}
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def get_acl(uri: str) -> dict[str, Any]:
"""Read a shared resource's full ACL (direct, inherited, effective grants).
Requires manage permission on that resource, or account ADMIN role.
"""
ctx = _get_ctx()
return await get_service().fs.get_acl(_resolve_mcp_workspace_uri(uri, ctx), ctx=ctx)
@_mcp_error_results()
@mcp.tool(annotations=_RETRY_SAFE_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def set_acl(uri: str, acl: AclSpec) -> dict[str, Any]:
"""Set a shared resource's ACL; requires manage permission before the change.
entries replaces direct grants; omitted entries preserves them. Each entry
has principal (user:<id>, group:<id>, or user:*) and level (read/write/manage).
acl_mode=inherit adds parent grants; restricted uses only direct grants.
Reset with acl={"acl_mode":"inherit","entries":[]}. A restricted ACL can
remove your own access. Account ADMIN retains implicit management access.
"""
ctx = _get_ctx()
return await get_service().fs.set_acl(
_resolve_mcp_workspace_uri(uri, ctx),
[entry.to_dict() for entry in acl.entries] if acl.entries is not None else None,
ctx=ctx,
acl_mode=acl.acl_mode,
)
# -- privacy ---------------------------------------------------------------
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def privacy_tree(
category: Annotated[
Optional[str], Field(description="Only list this category, e.g. credential or skill")
] = None,
) -> dict[str, Any]:
"""Find saved API keys, tokens and other private fields for the current user.
Use when you need to check whether a GitHub PAT or a skill's api_key is saved.
Returns categories, targets, active versions, configured flags and complete
{{ov_privacy:...}} references, never secret values or history. Pass a returned
reference to privacy_resolve when you need the actual value for a task.
"""
ctx = _get_ctx()
return await build_privacy_tree(get_service().privacy_configs, ctx, category)
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def privacy_resolve(
reference: Annotated[
str,
Field(
min_length=1,
max_length=2048,
description="Copy the entire {{ov_privacy:...}} placeholder unchanged, or supply one field-level Privacy URI. Omit surrounding text such as Authorization: Bearer.",
),
],
) -> dict[str, Any]:
"""Turn an {{ov_privacy:...}} placeholder into its actual API key or token.
When a SKILL.md, document or tool result contains, for example,
{{ov_privacy:alice:viking://~/privacy/credential/github#/values/pat}},
and the task needs that credential, pass the whole placeholder as reference.
Use the returned value in the API's Authorization header or credential field;
do not send the placeholder itself as a key. Returns one current field owned
by the caller. Keep references in saved documents and do not echo the secret
in chat. If you do not know the reference, use privacy_tree first.
"""
ctx = _get_ctx()
return await resolve_privacy_field(get_service().privacy_configs, ctx, reference)
@_mcp_error_results()
@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def privacy_upsert(
category: Annotated[str, Field(description="Credential category, e.g. credential or skill")],
target_key: Annotated[
str, Field(description="Credential target, e.g. github or the skill name")
],
values: Annotated[
dict[str, Any],
Field(
description='Fields to save, e.g. {"pat": "user-provided-token"}. Unspecified fields are preserved.'
),
],
) -> dict[str, Any]:
"""Save a credential the user supplies, e.g. a GitHub PAT or a skill's api_key.
For a GitHub PAT use category="credential", target_key="github", values={"pat":
"<user-provided-token>"}. Creates the target or merges the supplied fields;
updating pat preserves other fields such as username. Changed values create
and activate a version; this does not rotate keys at GitHub or other providers.
Returns updated-field metadata and {{ov_privacy:...}} references, never values.
Use those references instead of embedding the key in saved documents or memory.
"""
ctx = _get_ctx()
privacy = get_service().privacy_configs
if privacy is None:
raise FailedPreconditionError("Privacy configuration service is unavailable")
current = await privacy.patch_values(
ctx, category, target_key, values, updated_by=ctx.user.user_id
)
return {
"owner_user_id": ctx.user.user_id,
"category": category,
"target_key": target_key,
"version": current.version,
"fields": privacy_field_metadata(
ctx, category, target_key, {field: current.values[field] for field in values}
),
}
# -- 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_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def find(
query: str,
target_uri: str = "",
limit: int = 10,
min_score: float = 0.35,
level: Optional[List[int]] = None,
context_type: Optional[Union[str, List[str]]] = None,
read_content: bool = False,
events_time_decay_protection: Optional[str] = None,
) -> str:
"""Fast semantic retrieval without session context. Returns ranked memories, resources, and skills with URI, abstract, and score. context_type="skill" returns one hit per skill package, pointing at its SKILL.md, and without target_uri searches both the user's own and the account-shared skills."""
try:
validate_event_time_decay_request(events_time_decay_protection)
except ValueError as exc:
raise InvalidArgumentError(str(exc)) from exc
service = get_service()
ctx = _get_ctx()
context_filter = _resolve_context_type_filter(context_type)
skill_only = resolve_context_types(context_type) == [ContextType.SKILL.value]
if target_uri:
target_uri = _resolve_mcp_workspace_uri(target_uri, ctx)
elif skill_only:
# The generic default targets stop at the user root and miss viking://agent/skills.
target_uri = default_target_directories(ctx, context_type=ContextType.SKILL)
# A query-less call is a filter-only listing, which package retrieval does not serve.
if skill_only and query.strip():
# A skill is indexed as a whole package, so an item-level find returns one hit per
# file. find_skills collapses those to the best hit per package.
result = await service.search.find_skills(
query=query,
ctx=ctx,
target_uri=target_uri,
limit=limit,
score_threshold=min_score,
level=level,
)
else:
result = await service.search.find(
query=query,
ctx=ctx,
target_uri=target_uri,
limit=limit,
score_threshold=min_score,
filter=context_filter,
level=level,
events_time_decay_protection=events_time_decay_protection,
)
return await _format_search_result(result, service=service, ctx=ctx, read_content=read_content)
# This tool exposes two of the router's context-only fields as a pair each, so a caller
# that sets either half has set the field the router names.
_MCP_CONTEXT_ONLY_ALIASES = {
"detail_by_category": "detail",
"other_peer_penalties": "other_peer_penalty",
}
@_mcp_error_results()
@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def search(
query: str,
search_type: SearchType = "semantic",
target_uri: str = "",
session_id: Optional[str] = None,
limit: int = 10,
min_score: Optional[float] = None,
level: Optional[List[int]] = None,
context_type: Optional[Union[str, List[str]]] = None,
mode: Literal["list", "context"] = "list",
query_expansion: Literal["off", "auto"] = "auto",
max_tokens: Annotated[int, Field(ge=64, le=32000)] = DEFAULT_MAX_TOKENS,
quotas: Optional[Dict[str, int]] = None,
purpose: Optional[Literal["chat", "coding"]] = None,
detail: Literal["auto", "abstract", "overview", "full"] = "auto",
detail_by_category: Optional[Dict[str, str]] = None,
dedup_turns: Annotated[int, Field(ge=0, le=100)] = 0,
exclude_uris: Annotated[Optional[List[str]], Field(max_length=MAX_EXCLUDE_URIS)] = None,
peer_scope: Literal["actor", "all"] = "all",
other_peer_penalty: Optional[float] = None,
other_peer_penalties: Optional[Dict[str, float]] = None,
rewrite: Literal["off", "auto"] = "off",
rewrite_max_bullets: Annotated[int, Field(ge=1, le=20)] = 6,
read_content: bool = False,
events_time_decay_protection: Optional[str] = None,
) -> str:
"""Retrieval with optional session context and intent analysis.
``mode="list"`` returns ranked memories, resources, and skills with URI,
abstract, and score. ``mode="context"`` returns an injection-ready,
token-budgeted context block and supports category quotas, purpose presets,
detail tiers, cross-turn deduplication, peer scoping, and optional rewriting.
``target_uri`` is only supported in list mode.
"""
try:
validate_event_time_decay_request(events_time_decay_protection)
except ValueError as exc:
raise InvalidArgumentError(str(exc)) from exc
service = get_service()
ctx = _get_ctx()
if search_type == "keywords" and not query.strip():
raise InvalidArgumentError("query must not be empty when search_type='keywords'")
context_filter = _resolve_context_type_filter(context_type)
if mode == "context":
if read_content:
raise InvalidArgumentError("read_content is only supported in mode='list'")
if target_uri:
raise InvalidArgumentError("target_uri is not supported in mode='context'")
if detail != "auto" and detail_by_category:
raise InvalidArgumentError(
"detail cannot be combined with detail_by_category in mode='context'"
)
if other_peer_penalty is not None and other_peer_penalties:
raise InvalidArgumentError(
"other_peer_penalty cannot be combined with other_peer_penalties in mode='context'"
)
# Resolve exclusions with the same strictness as the REST search router,
# so alias URIs match the canonical URIs they are compared against.
resolved_exclude_uris = [
_resolve_mcp_workspace_uri(exclude_uri, ctx) for exclude_uri in (exclude_uris or ())
]
result = await assemble_context(
service=service,
ctx=ctx,
params=AssembleParams(
query=query,
search_type=search_type,
limit=limit,
score_threshold=min_score,
filter=context_filter,
events_time_decay_protection=events_time_decay_protection,
session_id=session_id,
query_expansion=query_expansion,
max_tokens=max_tokens,
quotas=quotas,
purpose=purpose,
detail=detail_by_category or (None if detail == "auto" else detail),
dedup_turns=dedup_turns,
exclude_uris=resolved_exclude_uris,
peer_scope=peer_scope,
other_peer_penalty=other_peer_penalties or other_peer_penalty,
rewrite=rewrite == "auto",
rewrite_max_bullets=rewrite_max_bullets,
),
)
if result.digest.strip():
return result.digest
if result.rendered.strip():
return result.rendered
return "No matching context found."
# POST /search rejects these in list mode and this tool did not, so the two faces of
# one feature disagreed about whether the request was valid. The list path calls
# SearchService.search, whose signature has no parameter for any of them, so passing
# one here did nothing at all -- for exclude_uris that means excluded URIs come back
# in the results with no error.
#
# The names and the wording come from the router rather than being restated here, so
# a field added to CONTEXT_ONLY_FIELDS reaches both faces at once. This tool splits
# two of those fields in two, and each half maps back onto the one the router knows.
supplied_by_caller = {
name: value
for name, (value, default) in {
"query_expansion": (query_expansion, "auto"),
"max_tokens": (max_tokens, DEFAULT_MAX_TOKENS),
"quotas": (quotas, None),
"purpose": (purpose, None),
"detail": (detail, "auto"),
"detail_by_category": (detail_by_category, None),
"dedup_turns": (dedup_turns, 0),
"exclude_uris": (exclude_uris, None),
"peer_scope": (peer_scope, "all"),
"other_peer_penalty": (other_peer_penalty, None),
"other_peer_penalties": (other_peer_penalties, None),
"rewrite": (rewrite, "off"),
"rewrite_max_bullets": (rewrite_max_bullets, 6),
}.items()
if value != default
}
as_named_by_caller: Dict[str, set] = {}
for name in supplied_by_caller:
as_named_by_caller.setdefault(_MCP_CONTEXT_ONLY_ALIASES.get(name, name), set()).add(name)
error = context_only_fields_error(as_named_by_caller, as_named_by_caller=as_named_by_caller)
if error:
raise InvalidArgumentError(error)
if target_uri:
target_uri = _resolve_mcp_workspace_uri(target_uri, ctx)
session = None
# Intent off: skip session.load — SearchService will not scan session either.
if session_id and service.search.is_intent_enabled():
session = service.sessions.session(ctx, session_id)
await session.load()
result = await service.search.search(
query=query,
search_type=search_type,
ctx=ctx,
target_uri=target_uri,
session=session,
limit=limit,
score_threshold=0.35 if min_score is None else min_score,
filter=context_filter,
context_types=[ContextType(value) for value in resolve_context_types(context_type)],
level=level,
events_time_decay_protection=events_time_decay_protection,
)
return await _format_search_result(result, service=service, ctx=ctx, read_content=read_content)
def _hit_uri(ctx_type: str, uri: str) -> str:
"""The URI an agent should read for a hit.
A skill is indexed as a whole package: the hit may be its .abstract.md, its
.overview.md, or any file inside the directory. The skill itself is the
package's SKILL.md.
"""
if ctx_type == "skill":
root = skill_root_uri(uri)
if root:
return f"{root}/SKILL.md"
return uri
def _package_abstract(uri: str, abstract: str) -> str:
"""The skill's own frontmatter, or "" when the package has no usable abstract."""
text = (abstract or "").strip()
return "" if text == f"# {uri} [Directory abstract is not ready]" else text
async def _describe_skills_by_package(items: List[Dict[str, Any]], *, service, ctx) -> None:
"""Describe a skill by its own abstract, not by whichever file inside it matched."""
import asyncio
pending = {}
for item in items:
if item["type"] != "skill" or not item["uri"].endswith("/SKILL.md"):
continue
root = item["uri"][: -len("/SKILL.md")]
if item["hit_uri"] in (f"{root}/.abstract.md", f"{root}/.overview.md", item["uri"]):
continue
pending[root] = item
semaphore = asyncio.Semaphore(10)
async def _describe(root: str) -> None:
async with semaphore:
try:
abstract = _package_abstract(root, await service.fs.abstract(root, ctx=ctx))
except Exception:
return
if abstract:
pending[root]["abstract"] = abstract
await asyncio.gather(*(_describe(root) for root in pending))
async def _format_search_result(result, *, service, ctx, read_content: bool = False) -> str:
items: List[Dict[str, Any]] = []
seen: dict[str, int] = {}
for ctx_type, contexts in [
("memory", result.memories),
("resource", result.resources),
("skill", result.skills),
]:
for m in contexts:
uri = _hit_uri(ctx_type, m.uri)
item = {
"type": ctx_type,
"uri": uri,
"hit_uri": m.uri,
"score": getattr(m, "score", 0.0),
"abstract": getattr(m, "abstract", "") or getattr(m, "overview", ""),
"origin_score": getattr(m, "origin_score", None),
"time_score": getattr(m, "time_score", None),
}
# Several files of one skill package can match; keep the best-scored hit.
previous = seen.get(uri)
if previous is not None:
if item["score"] > items[previous]["score"]:
items[previous] = item
continue
seen[uri] = len(items)
items.append(item)
if not items:
return "No matching context found."
await _describe_skills_by_package(items, service=service, ctx=ctx)
contents: dict[str, str] = {}
if read_content:
import asyncio
semaphore = asyncio.Semaphore(10)
async def _read(uri: str) -> None:
async with semaphore:
try:
contents[uri] = await service.fs.read_visible(uri, ctx=ctx)
except Exception:
pass
await asyncio.gather(*(_read(item["uri"]) for item in items))
lines = []
for item in items:
abstract = (item["abstract"] or "(no abstract)").strip()
uri = item["uri"]
line = f"- [{item['type']} {item['score'] * 100:.0f}%] {uri}\n {abstract}"
origin_score = item["origin_score"]
time_score = item["time_score"]
if origin_score is not None or time_score is not None:
line += f"\n origin_score={origin_score}, time_score={time_score}"
if uri in contents:
line += f"\n\n {contents[uri]}"
lines.append(line)
return (
f"Found {len(items)} item(s):\n\n"
+ "\n".join(lines)
+ ("" if read_content else "\n\nUse the read tool to expand a URI.")
)
# -- read ------------------------------------------------------------------
_MCP_IMAGE_EXTENSIONS = {".gif", ".jpeg", ".jpg", ".png", ".webp"}
_MCP_AUDIO_EXTENSIONS = {".flac", ".m4a", ".mp3", ".oga", ".ogg", ".wav"}
_MCP_VIDEO_EXTENSIONS = {".avi", ".m4v", ".mkv", ".mov", ".mp4", ".webm"}
_MCP_MEDIA_MAX_BYTES = MAX_INLINE_TOOL_RESULT_MEDIA_BYTES
def _mcp_uri_suffix(uri: str) -> str:
"""Lowercased file extension of a URI, ignoring any query or fragment."""
path = uri.split("#", 1)[0].split("?", 1)[0]
return PurePosixPath(path).suffix.lower()
def _is_mcp_image_uri(uri: str) -> bool:
return _mcp_uri_suffix(uri) in _MCP_IMAGE_EXTENSIONS
def _is_mcp_audio_uri(uri: str) -> bool:
return _mcp_uri_suffix(uri) in _MCP_AUDIO_EXTENSIONS
def _is_mcp_video_uri(uri: str) -> bool:
return _mcp_uri_suffix(uri) in _MCP_VIDEO_EXTENSIONS
def _sniff_mcp_image_mime_type(data: bytes) -> Optional[str]:
"""Recognize the raster formats shared by common MCP coding clients."""
if data.startswith(b"\x89PNG\r\n\x1a\n"):
return "image/png"
if data.startswith(b"\xff\xd8\xff"):
return "image/jpeg"
if data.startswith((b"GIF87a", b"GIF89a")):
return "image/gif"
if len(data) >= 12 and data.startswith(b"RIFF") and data[8:12] == b"WEBP":
return "image/webp"
return None
def _mcp_image_content(data: bytes, mime_type: str) -> ImageContent:
encoded = base64.b64encode(data).decode("ascii")
return ImageContent(type="image", data=encoded, mimeType=mime_type)
def _sniff_mcp_audio_mime_type(data: bytes, uri: str) -> Optional[str]:
"""Recognize audio formats represented by MCP AudioContent."""
suffix = _mcp_uri_suffix(uri)
if data.startswith(b"RIFF") and len(data) >= 12 and data[8:12] == b"WAVE":
return "audio/wav"
if data.startswith(b"fLaC"):
return "audio/flac"
if data.startswith(b"OggS") and suffix in {".oga", ".ogg"}:
return "audio/ogg"
if data.startswith(b"ID3") or (len(data) >= 2 and data[0] == 0xFF and data[1] & 0xE0 == 0xE0):
return "audio/mpeg"
if len(data) >= 12 and data[4:8] == b"ftyp" and suffix == ".m4a":
return "audio/mp4"
return None
def _mcp_audio_content(data: bytes, mime_type: str) -> AudioContent:
encoded = base64.b64encode(data).decode("ascii")
return AudioContent(type="audio", data=encoded, mimeType=mime_type)
def _mcp_media_download_hint(uri: str) -> str:
"""Return actionable fallbacks when media cannot be inlined."""
path = uri.split("#", 1)[0].split("?", 1)[0]
filename = PurePosixPath(path).name or "download"
return (
f'Call the download tool with uri="{uri}" for a temporary curl-able URL, '
f'or use `ov get "{uri}" "./{filename}"` to fetch the original file.'
)
@_mcp_error_results(structured_output=False)
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS, structured_output=False)
async def read(
uris: str | list[str],
offset: int = 0,
limit: int = -1,
) -> str | list[ContentBlock]:
"""Read one or more viking:// file URIs. Text reads accept line-based offset/limit. Raster images and supported audio return native MCP content blocks. 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 _preflight_one(
uri: str,
) -> tuple[str, Optional[int], Optional[_MCPToolFailure]]:
"""Resolve a URI and stat media before any binary bytes are loaded."""
try:
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
is_image = _is_mcp_image_uri(resolved_uri)
is_audio = _is_mcp_audio_uri(resolved_uri)
is_video = _is_mcp_video_uri(resolved_uri)
if not (is_image or is_audio or is_video):
return resolved_uri, None, None
async with semaphore:
stat = await service.fs.stat(resolved_uri, ctx=ctx, skip_count=True)
if stat.get("isDir"):
return (
resolved_uri,
None,
_mcp_failure(
f"Cannot render {uri}: URI points to a directory. "
"Use the list tool (or `ov ls` / `ov tree`) to browse its contents."
),
)
if is_video:
return (
resolved_uri,
None,
_mcp_failure(
f"Cannot render {uri}: MCP has no standard VideoContent block. "
f"{_mcp_media_download_hint(uri)}"
),
)
size = stat.get("size") if stat else None
if isinstance(size, bool) or not isinstance(size, int) or size < 0:
return (
resolved_uri,
None,
_mcp_failure(
f"Cannot render {uri}: file size is unavailable. "
f"{_mcp_media_download_hint(uri)}"
),
)
return resolved_uri, size, None
except OpenVikingError as exc:
return uri, None, _mcp_failure(exc)
preflight = await asyncio.gather(*[_preflight_one(uri) for uri in uri_list])
checked: list[tuple[str, Optional[int], Optional[_MCPToolFailure]]] = []
media_total = 0
for uri, (resolved_uri, size, error) in zip(uri_list, preflight, strict=True):
if error is None and size is not None:
if size > _MCP_MEDIA_MAX_BYTES:
error = _mcp_failure(
f"Media file is too large to inline through MCP ({size} bytes; limit "
f"{_MCP_MEDIA_MAX_BYTES} bytes). {_mcp_media_download_hint(uri)}"
)
elif media_total + size > _MCP_MEDIA_MAX_BYTES:
error = _mcp_failure(
f"Cannot inline {uri}: combined media size would exceed the MCP tool-call "
f"limit of {_MCP_MEDIA_MAX_BYTES} bytes. Read fewer media files at once. "
f"{_mcp_media_download_hint(uri)}"
)
else:
media_total += size
checked.append((resolved_uri, size, error))
async def _read_one(
uri: str, prepared: tuple[str, Optional[int], Optional[_MCPToolFailure]]
) -> str | ContentBlock:
async with semaphore:
try:
resolved_uri, declared_size, error = prepared
if error is not None:
return error
is_image = _is_mcp_image_uri(resolved_uri)
is_audio = _is_mcp_audio_uri(resolved_uri)
if is_image or is_audio:
data = await service.fs.read_file_bytes(resolved_uri, ctx=ctx)
if declared_size is None or len(data) > declared_size:
return _mcp_failure(
f"Cannot render {uri}: file changed after its size was checked. "
"Retry the read."
)
mime_type = (
_sniff_mcp_image_mime_type(data)
if is_image
else _sniff_mcp_audio_mime_type(data, resolved_uri)
)
if mime_type is None:
return _mcp_failure(
f"Cannot render {uri}: its bytes do not match a supported media "
f"format. {_mcp_media_download_hint(uri)}"
)
if is_image:
return _mcp_image_content(data, mime_type)
return _mcp_audio_content(data, mime_type)
content = await service.fs.read_visible(
resolved_uri,
ctx=ctx,
offset=offset,
limit=limit,
)
return content
except OpenVikingError as exc:
return _mcp_failure(exc)
if len(uri_list) == 1:
result = await _read_one(uri_list[0], checked[0])
if isinstance(result, str):
return result
return [TextContent(type="text", text=f"Source: {uri_list[0]}"), result]
results = await asyncio.gather(
*[_read_one(uri, prepared) for uri, prepared in zip(uri_list, checked, strict=True)]
)
if any(not isinstance(result, str) for result in results):
blocks: list[ContentBlock] = []
for uri, result in zip(uri_list, results, strict=True):
blocks.append(TextContent(type="text", text=f"=== {uri} ==="))
if isinstance(result, str):
blocks.append(TextContent(type="text", text=result))
else:
blocks.append(result)
return blocks
parts = []
for uri, text in zip(uri_list, results, strict=True):
parts.append(f"=== {uri} ===\n{text}")
combined = "\n\n".join(parts)
if results and all(isinstance(result, _MCPToolFailure) for result in results):
return _mcp_failure(combined)
return combined
# -- download --------------------------------------------------------------
def _human_size(size: int) -> str:
if size < 1024:
return f"{size} B"
value = size / 1024
for unit in ("KB", "MB"):
if value < 1024:
return f"{value:.1f} {unit}"
value /= 1024
return f"{value:.1f} GB"
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def download(uri: str) -> str:
"""Get a short-lived URL for downloading the original bytes of one file (any type, including PDF, images, archives, audio and video). It does not return the content; use `read` to read text. Fetch the URL with `curl -fL -o <local path> <url>`; no OpenViking API key is needed. The link works once and expires in about 10 minutes; call download again for a new link. Directories are not supported: use `list` or `tree` and download files one at a time."""
service = get_service()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
server_config = get_server_config()
stat_ctx = ctx
if (
server_config is not None
and server_config.get_effective_auth_mode() != AuthMode.API_KEY.value
and ctx.role != Role.USER
):
# Outside API-key mode the token fetch runs as USER, so check with that authority.
stat_ctx = dataclasses.replace(ctx, role=Role.USER)
try:
stat = await service.fs.stat(resolved_uri, ctx=stat_ctx, skip_count=True)
except AGFSNotFoundError as exc:
raise NotFoundError(resolved_uri, "file") from exc
except AGFSClientError as exc:
mapped = map_exception(exc, resource=resolved_uri, resource_type="file")
if mapped is not None:
raise mapped from exc
raise
if stat.get("isDir"):
return _mcp_failure(
f"Cannot download {uri}: URI points to a directory. Downloads are per-file: "
"use the list or tree tool to find files and download them one at a time."
)
ttl_seconds = (
server_config.upload_signed_ttl_seconds
if server_config is not None
else _DEFAULT_UPLOAD_TTL_SECONDS
)
token, expires_at = download_token_store.issue(
ctx.user.account_id,
ctx.user.user_id,
ttl_seconds=ttl_seconds,
role=ctx.role,
from_oauth=ctx.from_oauth,
actor_peer_id=ctx.actor_peer_id or "",
uri=resolved_uri,
)
base_url, url_source = _resolve_public_base_url()
download_url = f"{base_url}/api/v1/content/download?token={quote(token, safe='')}"
expires_iso = datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(timespec="seconds")
minutes = max(1, ttl_seconds // 60)
filename = stat.get("name") or PurePosixPath(resolved_uri).name or "download"
size = stat.get("size")
details = (
f"{filename}, {_human_size(size)}"
if isinstance(size, int) and not isinstance(size, bool) and size >= 0
else filename
)
prose = (
f"Download link for {resolved_uri} ({details}):\n"
"\n"
f" curl -fL -o {shlex.quote('./' + filename)} {shlex.quote(download_url)}\n"
"\n"
"Choose any local path for -o. The URL's token authorizes this one download against "
"OpenViking itself (no OpenViking API key needed). It works once: if the fetch fails, "
"call download again for a new link.\n"
"\n"
"If the OpenViking server sits behind a private gateway or reverse proxy that "
"requires extra request headers (e.g. `openviking_name`, tenant/vault headers, "
"or a gateway API key), those headers are enforced on every request including "
"this download — replay the same headers you use for MCP calls when fetching the "
"file. A gateway rejection typically looks like HTTP 400/401/403 before the "
"token is even checked.\n"
"\n"
f"This download URL expires in ~{minutes} minutes ({expires_iso})."
)
if url_source not in ("env", "config"):
prose += (
"\n\n"
"Note for the user: this download URL was auto-detected from the incoming "
"request because OPENVIKING_PUBLIC_BASE_URL is not set on the server. "
"If the download fails (connection refused, wrong host, TLS error), ask the "
"server operator to set OPENVIKING_PUBLIC_BASE_URL to the agent-facing "
"URL of the OpenViking server (e.g. via docker-compose `environment:` "
"or systemd unit) and retry."
)
return prose
# -- list ------------------------------------------------------------------
@_mcp_error_results()
@mcp.tool(name="list", annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def ls(
uri: str = "viking://",
recursive: bool = False,
offset: int = 0,
limit: int | None = None,
sort_by: Literal["name", "mtime"] | None = None,
sort_order: Literal["asc", "desc"] = "asc",
) -> str:
"""List one sorted page under a viking:// directory URI.
Args:
uri: Directory URI to list; defaults to "viking://" like tree and glob.
recursive: Whether to recursively list descendants.
offset: Number of visible entries to skip.
limit: Optional maximum number of entries.
sort_by: Optional name or modification-time ordering.
sort_order: Ascending or descending order.
Returns:
A line-oriented directory listing.
"""
if offset < 0:
raise InvalidArgumentError("offset must be greater than or equal to 0")
if limit is not None and limit <= 0:
raise InvalidArgumentError("limit must be greater than 0")
service = get_service()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
options: dict[str, Any] = {
"ctx": ctx,
"recursive": recursive,
"output": "original",
}
if offset:
options["offset"] = offset
if limit is not None:
options["node_limit"] = limit
if sort_by is not None:
options["sort_by"] = sort_by
options["sort_order"] = sort_order
page = await service.fs.ls(resolved_uri, **options)
entries = page.entries
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}")
if page.has_more:
lines.append("(more entries available; use offset and limit to view the next page)")
return "\n".join(lines)
# -- tree ------------------------------------------------------------------
# Long enough to keep a full skill description (the Agent Skills limit is 1024 chars).
_TREE_ABSTRACT_LIMIT = 1024
def _tree_abstract(entry: Dict[str, Any]) -> str:
abstract = (entry.get("abstract") or "").strip()
# A directory with no generated .abstract.md (a skill's scripts/, say) comes back as a
# placeholder that carries no summary.
placeholders = (
"[.abstract.md is not ready]",
f"# {entry.get('uri', '')} [Directory abstract is not ready]",
)
if abstract in placeholders:
return ""
return " ".join(abstract.split())
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def tree(
uri: str = "viking://",
level_limit: int = 3,
node_limit: int = 1000,
include_abstract: bool = False,
offset: int = 0,
limit: int | None = None,
) -> str:
"""Show one visible page from a recursive directory tree.
Args:
uri: Directory URI to traverse.
level_limit: Maximum traversal depth.
node_limit: Existing default result limit.
include_abstract: Whether to include directory summaries (a skill directory's
summary is its name and description).
offset: Number of visible nodes to skip.
limit: Optional result limit that overrides node_limit.
Returns:
An indented directory tree.
"""
if offset < 0:
raise InvalidArgumentError("offset must be greater than or equal to 0")
if limit is not None and limit <= 0:
raise InvalidArgumentError("limit must be greater than 0")
service = get_service()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
output = "agent" if include_abstract else "original"
effective_limit = limit if limit is not None else node_limit
try:
page = await service.fs.tree(
resolved_uri,
ctx=ctx,
output=output,
abs_limit=_TREE_ABSTRACT_LIMIT,
node_limit=effective_limit,
level_limit=level_limit,
offset=offset,
)
except NotFoundError:
page = None
entries = page.entries if page is not None else []
if not entries:
return f"(nothing under {uri})"
lines = [
f"Tree of {uri} (depth <= {level_limit}, {len(entries)} entr{'y' if len(entries) == 1 else 'ies'}):"
]
for e in entries:
rel = (e.get("rel_path") or e.get("name") or "?").strip("/")
name = rel.rsplit("/", 1)[-1]
depth = len([part for part in rel.split("/") if part])
indent = " " * max(0, depth - 1)
if e.get("isDir"):
lines.append(f"{indent}{name}/")
else:
lines.append(f"{indent}{name} ({e.get('size', 0)} B)")
abstract = _tree_abstract(e)
if include_abstract and abstract:
lines.append(f"{indent} - {abstract}")
if page is not None and page.has_more:
lines.append(
f"(truncated at node_limit={effective_limit}; narrow the uri or raise node_limit to see more)"
)
return "\n".join(lines)
# -- remember --------------------------------------------------------------
class StoreMessage(BaseModel):
role: Literal["user", "assistant"] = Field(description="Message role")
content: str = Field(description="Message text content")
@_mcp_error_results()
@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def remember(messages: list[StoreMessage]) -> str:
"""Submit information for OpenViking long-term memory extraction. Use when the user says 'remember this', shares preferences, important facts, or decisions worth persisting. Extraction runs in the background and decides which memories to create or update."""
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.open(session_id, ctx, auto_create=True)
added = 0
for msg in messages:
if msg.content:
add_async = getattr(session, "add_message_async", None)
if callable(add_async):
await add_async(msg.role, [TextPart(text=msg.content)])
else:
session.add_message(msg.role, [TextPart(text=msg.content)])
added += 1
result = await service.sessions.commit_async(session_id, ctx)
task_id = result.get("task_id")
if not task_id:
reason = result.get("reason") or result.get("status") or "unknown"
return f"Nothing was committed for memory extraction (reason: {reason})."
return (
f"Submitted {added} message(s) for memory extraction (session {session_id}, "
f"task_id={task_id}). Extraction runs in the background and decides which memories "
"to create or update."
)
# -- write -----------------------------------------------------------------
@_mcp_error_results()
@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def write(
uri: str,
content: str,
mode: Literal["replace", "append", "create"] = "replace",
wait: bool = False,
timeout: Annotated[
Optional[float],
Field(
deprecated=True, description="Deprecated compatibility parameter; accepted and ignored."
),
] = None,
acl: Optional[AclSpec] = None,
) -> str:
"""Write text to a viking:// file. Use this for files you author yourself (notes, profiles, state), the same way you would use a working directory. To change part of an existing file, prefer the edit tool over a full rewrite. To store a file, document, URL, or repo the user gives you, use add_resource; for a skill, use add_skill. Do not copy its text into a file here instead.
- mode="replace" (default): overwrite the file; creates it and any missing parent directories if needed.
- mode="create": compatibility alias for replace; overwrite an existing file or create it if missing.
- Any new file (whether created by "replace", "append", or "create") must end in one of: .md .txt .json .yaml .yml .toml .py .js .ts
- mode="append": append to the end of an existing file; use the supplied content as the initial body if it is missing.
- acl: optional shared-resource ACL with acl_mode (inherit/restricted) and entries
(principal=user:<id>/group:<id>/user:*, level=read/write/manage). Explicit ACL
requires manage on the target, or its parent for a new file. Omit to preserve
existing ACL or inherit on creation.
Writable scopes: viking://resources/, viking://user/{user_id}/, viking://agent/. The viking://~ home alias expands to the caller's user root. The managed user subtrees skills/, peers/, privacy/ and sessions/ are read-only. Do not write inside a skill package under viking://agent/skills/ either: a plain write skips installation, so the skill's abstract, overview and source metadata go stale. Change a skill with the add_skill tool. After a write, semantic search indexes refresh in the background; pass wait=true to block until search reflects the change."""
# An explicit ACL uses the kernel's manage check before any content is written.
service = get_service()
ctx = _get_ctx()
uri = _resolve_mcp_workspace_uri(uri, ctx)
result = await service.fs.write(
uri=uri, content=content, ctx=ctx, mode=mode, wait=wait, acl=acl
)
written = result.get("written_bytes", 0)
message = (
f"Wrote {written} bytes to {result.get('uri', uri)} (mode={result.get('mode', mode)})."
)
return message + _indexing_hint(result)
@_mcp_error_results()
@mcp.tool(annotations=_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def edit(
uri: str,
old_string: str,
new_string: str,
replace_all: bool = False,
wait: bool = False,
timeout: Annotated[
Optional[float],
Field(
deprecated=True, description="Deprecated compatibility parameter; accepted and ignored."
),
] = None,
) -> str:
"""Replace an exact string with new text in an existing viking:// file. Use this for targeted changes instead of rewriting the whole file with the write tool. old_string must match the file's current content exactly, including indentation and newlines; use the read tool first to see it. The edit fails and the file is left unchanged if old_string is not found, or if it matches more than once and replace_all is false (pass more surrounding context to make it unique, or set replace_all=true to replace every occurrence). Pass new_string="" to delete old_string.
Editing a memory file preserves its metadata; after an edit, search indexes refresh in the background (pass wait=true to block until search reflects the change).
Do not edit files inside a skill package (.../skills/<name>/): read the skill's SKILL.md, revise the whole text, and install it again with the add_skill tool."""
service = get_service()
ctx = _get_ctx()
uri = _resolve_mcp_workspace_uri(uri, ctx)
if not old_string:
raise InvalidArgumentError("old_string must not be empty")
try:
current = await service.fs.read_visible(uri, ctx=ctx)
except (InvalidArgumentError, PermissionDeniedError, UnauthenticatedError):
raise
except Exception as exc:
raise NotFoundError(uri, "file") from exc
occurrences = current.count(old_string)
if occurrences == 0:
hint = ""
if current.replace("\r\n", "\n").count(old_string.replace("\r\n", "\n")):
hint = " old_string matches only after normalizing CRLF/LF line endings."
raise InvalidArgumentError(
f"old_string not found in {uri}.{hint} "
"Re-read the file with the read tool to get its current content."
)
if occurrences > 1 and not replace_all:
raise InvalidArgumentError(
f"old_string matches {occurrences} locations in {uri}. "
"Include more surrounding context to make it unique, or set replace_all=true."
)
updated = current.replace(old_string, new_string)
if updated == current:
return f"No changes: {uri} already matches the requested edit."
result = await service.fs.write(uri=uri, content=updated, ctx=ctx, mode="replace", wait=wait)
written = result.get("written_bytes", 0)
message = f"Edited {result.get('uri', uri)} ({written} bytes written)."
return message + _indexing_hint(result)
def _indexing_hint(result: Dict[str, Any]) -> str:
semantic = result.get("semantic_status")
vector = result.get("vector_status")
parts = [f"semantic={semantic}", f"vector={vector}"]
if result.get("overview_status") is not None:
parts.append(f"overview={result['overview_status']}")
hint = f"\nIndexing: {', '.join(parts)}."
if "queued" in (semantic, vector):
hint += " Search indexes update in the background; pass wait=true if a follow-up search must see this change immediately."
return hint
# -- add_resource ----------------------------------------------------------
_DEFAULT_UPLOAD_TTL_SECONDS = 600
def _resolve_public_base_url() -> tuple[str, str]:
"""Pick the URL the agent should POST uploads to. Returns ``(base_url, source)``.
Resolution order (first match wins):
1. ``env`` — ``OPENVIKING_PUBLIC_BASE_URL`` environment variable. Operator-set,
always wins.
2. ``config`` — ``ServerConfig.public_base_url``. Operator-set baseline in ov.conf.
3. ``forwarded`` — ``X-Forwarded-Host`` (+ ``X-Forwarded-Proto``) from the request.
Set by reverse proxies (nginx, ALB, ingress controllers, MCP proxies). Reliable
when the proxy chain forwards these headers, which is the standard default.
4. ``host`` — the raw ``Host`` header from a direct connection. Reliable for
same-host MCP clients (e.g. local Claude Code talking to localhost server).
5. ``listen`` — ``http://{listen_host}:{listen_port}`` last-resort fallback.
Only produces an agent-reachable URL when the server is bound to a routable
address; commonly wrong behind reverse proxies.
Sources 1 and 2 are "explicit" — operator vouched for the URL. Sources 3-5 are
inferred and may be wrong when the proxy chain doesn't forward request headers.
Callers should append a "set OPENVIKING_PUBLIC_BASE_URL if upload fails" hint
in that case.
"""
env_url = os.environ.get("OPENVIKING_PUBLIC_BASE_URL")
if env_url:
return env_url.rstrip("/"), "env"
config = get_server_config()
if config is not None and config.public_base_url:
return config.public_base_url.rstrip("/"), "config"
url_info = _request_url_ctx.get()
if url_info:
# X-Forwarded-Host / -Proto can be comma-separated lists when the request
# crosses multiple proxy hops. Take the first (left-most original-client)
# value, matching the normalization in openviking.server.oauth.router.
def _first(value: Optional[str]) -> Optional[str]:
if not value:
return None
head = value.split(",", 1)[0].strip()
return head or None
xfh = _first(url_info.get("x_forwarded_host"))
xfp = _first(url_info.get("x_forwarded_proto"))
host_hdr = _first(url_info.get("host"))
if xfh:
proto = xfp or "https"
return f"{proto}://{xfh}", "forwarded"
if host_hdr:
return f"http://{host_hdr}", "host"
if config is not None:
from openviking.server.config import map_bind_host_to_loopback
host = map_bind_host_to_loopback(config.host)
return f"http://{host}:{config.port}", "listen"
return "http://127.0.0.1:1933", "listen"
async def _maybe_sitemap_hint(path: str) -> str:
"""Best-effort sitemap/RSS suggestion for a single-page add (never crawls).
Policy: only suggest when the added URL is the site root / homepage (path is
empty or "/"). Adding a deep article URL implies intent for just that page, and
gating to the root also keeps the (bounded, non-recursive) probe from re-running
when many pages of the same site are added one-by-one.
Gated by config (``webfeed.suggest_feed``) and fully exception-safe so it can
never block or fail the add it is attached to.
"""
try:
from urllib.parse import urlparse
if urlparse(path).path not in ("", "/"):
return ""
from openviking.parse.accessors import discover_feed_hint
from openviking.utils.network_guard import ensure_public_remote_target
from openviking_cli.utils.config import get_openviking_config
webfeed = getattr(get_openviking_config(), "webfeed", None)
if webfeed is not None and not getattr(webfeed, "suggest_feed", True):
return ""
timeout = float(getattr(webfeed, "suggest_timeout", 2.5)) if webfeed else 2.5
hint = await discover_feed_hint(
path, timeout=timeout, request_validator=ensure_public_remote_target
)
return hint or ""
except Exception:
return ""
def _resource_add_error(result: Any) -> _MCPToolFailure | None:
if not isinstance(result, dict) or result.get("status") != "error":
return None
errors = result.get("errors")
detail = (
result.get("message")
or (errors[0] if isinstance(errors, list) and errors else None)
or "resource processing failed"
)
return _mcp_failure(f"Error adding resource: {detail}")
@_mcp_error_results()
@mcp.tool(annotations=_OPEN_WORLD_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def add_resource(
path: str = "",
temp_file_id: str = "",
add_type: str = "",
description: str = "",
watch_interval: float = 0,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
to: str = "",
parent: str = "",
tags: Optional[list[str]] = None,
tag_mode: str = "replace",
args: Optional[dict[str, Any]] = None,
acl: Optional[AclSpec] = None,
) -> str:
"""Add a resource to OpenViking. Asynchronous — processing happens in the background.
For an agent skill, use add_skill instead: a skill added here is stored as an ordinary
resource and never becomes an installed skill. Copying a source's text into a file with
write instead skips parsing and stores a plain file.
Preserve the existing Resource layout and account policy. Resource directory rules do not
apply to Memory, which is organized by the memory extraction system. Keep one stable root
per source; use ``parent`` for a new source and exact ``to`` for an in-place refresh.
Inspect the target space with ``list``/``tree`` before adding when practical and reuse its
existing directories; never create a synonymous category (e.g. ``documents/``, ``pdfs/``)
when one already fits. For a new category prefer the conventional names ``repos/``,
``docs/``, ``sites/``, ``datasets/``, ``media/``, ``artifacts/``,
``projects/<name>/`` for a multi-category project, or another plural domain noun for entity
collections (``items/``, ``people/``).
Where it goes: ``viking://resources/`` is shared with the whole account and is the
default when ``to`` and ``parent`` are empty (unless a default add target is
configured). ``viking://~/resources/`` is the caller's own resources, visible only to
them. If visibility cannot be inferred, prefer the current identity's
``parent="viking://~/resources/inbox"`` and report that choice; never silently put
identity-private material in the shared root.
Remote URL: pass ``path`` as an http(s)://, git@, ssh://, or git:// URL. A sitemap /
RSS / Atom URL ingests the WHOLE site as one resource tree; pass ``args={"site": true}``
to force whole-site ingestion from a bare domain.
Local file: pass ``path`` as a filesystem path (e.g. ``/tmp/foo.pdf``). The response is an
upload instruction — HTTP POST the file to the returned URL and the server ingests it
automatically; you do NOT need to call this tool again.
Args:
path: Remote URL or local filesystem path. Required unless ``temp_file_id`` is set.
temp_file_id: Server-minted upload id from a prior signed local-file upload.
add_type: Explicit Connector source type (e.g. "tos", "git"). When set, the
request routes through the Connector integration (must be enabled
server-side) and ``path`` is sent verbatim — never treated as a local
file. Requires an exact ``to`` target and cannot be combined with
``temp_file_id`` or ``parent``. Leave empty for the default path-probing
behavior.
description: Optional human-readable reason for adding the resource.
watch_interval: Auto-refresh cadence in minutes. 0 = no watch. Prefer >=1440 (24h)
unless the source changes faster — every refresh re-embeds the whole resource.
Only applies to remote-URL invocations.
processing_mode: "semantic_and_vectors" for normal semantic processing, or
"vectors_only" to skip semantic understanding and only build vector indexes.
to: Exact final URI including the leaf name (e.g.
"viking://resources/volcengine/OpenViking", or
"viking://~/resources/OpenViking" for an identity-private copy). Written verbatim; an existing
target is synced to match the new source, so visible entries it does not
contain are deleted. Required when ``add_type`` is set.
parent: Directory to store the resource under, for remote or
local-file imports (e.g. "viking://~/resources" or "viking://resources");
missing directories are created automatically. The leaf name comes from the source.
Never overwrites
— a collision reserves the next free name ("name_1", "name_2", ...) and
returns a warning. Mutually exclusive with ``to``; not supported when
``add_type`` is set. Leaving both empty derives the directory and the name
from the source and handles collisions like ``parent``.
tags: Optional explicit k=v retrieval tags to apply after ingestion.
tag_mode: Tag update mode: "replace", "append", or "clear". Clear removes
existing tags without requiring ``tags``. Defaults to "replace".
acl: Optional ACL on the final import root. Uses acl_mode (inherit/restricted)
and entries with principal (user:<id>, group:<id>, user:*) and level
(read/write/manage). Requires manage on the existing target or parent
for a new target. Omit to preserve existing ACL or inherit on creation.
args: Parser-specific options, e.g. {"auth_config": {"token": "..."}}
for native HTTPS Git imports and watches, {"feishu_access_token": "..."}
for Feishu imports, {"site": true} for whole-site ingestion, or
{"parse_mode": "no_split"} to keep each parsed document body in one file.
"""
from openviking.server.local_input_guard import require_remote_resource_source
service = get_service()
ctx = _get_ctx()
try:
to = resolve_path_variables(to).strip() if to else ""
if to:
to = validate_content_target_uri(to, ctx, kind="resource", field_name="to")
parent = resolve_path_variables(parent).strip() if parent else ""
if parent:
parent = validate_content_target_uri(
parent,
ctx,
kind="resource",
field_name="parent",
)
except (InvalidArgumentError, PermissionDeniedError) as exc:
return _mcp_failure(exc)
try:
mode = normalize_parse_mode((args or {}).get("parse_mode", ParseMode.DEFAULT))
except InvalidArgumentError as exc:
return _mcp_failure(f"Error: {exc}")
if watch_interval < 0:
return _mcp_failure(
"Error: watch_interval must be >= 0. Use 0 for one-shot add (no watch); "
"use a positive number of minutes (>=1440 recommended) to subscribe to auto-refresh."
)
add_type = add_type.strip()
if add_type and temp_file_id:
return _mcp_failure("Error: add_type cannot be combined with temp_file_id.")
if add_type and not path:
return _mcp_failure("Error: add_type requires 'path'.")
if add_type and parent:
return _mcp_failure("Error: add_type cannot be combined with parent.")
if add_type and not to:
return _mcp_failure("Error: add_type requires an exact 'to' target.")
if to and parent:
return _mcp_failure("Error: Cannot specify both 'to' and 'parent' at the same time.")
# Branch 1: ingest by temp_file_id. Kept for backward compat / REST-style use — the
# signed upload now auto-ingests server-side, so agents no longer need this second leg.
if temp_file_id:
from openviking.server.config import ServerConfig
server_config = get_server_config() or ServerConfig()
store = TempUploadStore.build(server_config)
try:
result = await ingest_temp_upload(
store,
temp_file_id,
ctx,
to=to,
parent=parent,
reason=description,
args=args,
processing_mode=processing_mode,
tags=tags,
tag_mode=tag_mode,
acl=acl,
)
except OpenVikingError as exc:
return _mcp_failure(exc)
except Exception as exc:
return _mcp_failure(f"Error adding resource: {exc}")
error = _resource_add_error(result)
if error is not None:
return error
root_uri = result.get("root_uri", "") if isinstance(result, dict) else ""
return (
f"Resource added: {root_uri}"
if root_uri
else "Resource added (processing in background)."
)
if not path:
return _mcp_failure(
"Error: provide either 'path' (remote URL or local file) or 'temp_file_id'."
)
# Branch 2: agent passed a temp_file_id-shaped string as `path` — guide them
if TEMP_FILE_ID_RE.match(path):
return _mcp_failure(
f"Error: '{path}' looks like a temp_file_id, not a path. "
f'Pass it as the temp_file_id kwarg: add_resource(temp_file_id="{path}")'
)
# Branch 3: remote URL, or an explicitly declared Connector source type
# (declared requests are delegated or rejected server-side, never resolved
# as local paths)
if add_type or is_remote_resource_source(path):
try:
path = require_remote_resource_source(
path, declared_connector_add_type=add_type or None
)
result = await service.resources.add_resource(
path=path,
ctx=ctx,
add_type=add_type or None,
to=to or None,
parent=parent or None,
create_parent=bool(parent),
reason=description,
wait=False,
watch_interval=watch_interval,
processing_mode=processing_mode,
enforce_public_remote_targets=True,
args=args,
tags=tags,
tag_mode=tag_mode,
acl=acl,
)
except OpenVikingError as exc:
return _mcp_failure(exc)
except Exception as exc:
return _mcp_failure(f"Error adding resource: {exc}")
error = _resource_add_error(result)
if error is not None:
return error
root_uri = result.get("root_uri", "")
task_id = result.get("task_id", "")
if watch_interval > 0:
watch_suffix = f" (watch enabled, refresh every {watch_interval:g} minute(s))"
else:
watch_suffix = ""
if root_uri:
message = f"Resource added: {root_uri}{watch_suffix}"
elif task_id:
message = (
f"Resource accepted (task_id: {task_id}; processing in background){watch_suffix}."
)
else:
message = f"Resource added (processing in background){watch_suffix}."
# Detect-and-suggest: if this single page belongs to a site that exposes a
# sitemap/RSS feed, hint at whole-site ingestion. Never auto-crawls; the
# add above is already done, so a slow/failed probe has no functional impact.
# Declared Connector imports ingest the whole source already — no hint.
hint = None if add_type else await _maybe_sitemap_hint(path)
if hint:
message += "\n" + hint
return message
# Branch 4: local path — mint token, return upload instruction
server_config = get_server_config()
ttl_seconds = (
server_config.upload_signed_ttl_seconds
if server_config is not None
else _DEFAULT_UPLOAD_TTL_SECONDS
)
token, expires_at = upload_token_store.issue(
ctx.user.account_id,
ctx.user.user_id,
ttl_seconds=ttl_seconds,
role=ctx.role,
from_oauth=ctx.from_oauth,
to=to,
parent=parent,
reason=description,
actor_peer_id=ctx.actor_peer_id or "",
processing_mode=processing_mode,
tags=tags,
tag_mode=tag_mode,
parse_mode=mode.value,
acl=acl,
)
base_url, url_source = _resolve_public_base_url()
upload_url = f"{base_url}/api/v1/resources/temp_upload?token={quote(token, safe='')}"
expires_iso = datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(timespec="seconds")
minutes = max(1, ttl_seconds // 60)
prose = (
"Local file detected — upload it to ingest this resource.\n"
"\n"
'HTTP POST the file bytes (multipart/form-data, field name "file") to:\n'
"\n"
f" {upload_url}\n"
"\n"
"The URL's token authorizes the upload against OpenViking itself (no OpenViking "
"API key needed); the server ingests the file automatically once received — you "
"do NOT need to call add_resource again.\n"
"\n"
"If the OpenViking server sits behind a private gateway or reverse proxy that "
"requires extra request headers (e.g. `openviking_name`, tenant/vault headers, "
"or a gateway API key), those headers are enforced on every request including "
"this upload — replay the same headers you use for MCP calls when POSTing the "
"file. A gateway rejection typically looks like HTTP 400/401/403 before the "
"token is even checked.\n"
"\n"
f"This upload URL expires in ~{minutes} minutes ({expires_iso})."
)
if url_source not in ("env", "config"):
prose += (
"\n\n"
"Note for the user: this upload URL was auto-detected from the incoming "
"request because OPENVIKING_PUBLIC_BASE_URL is not set on the server. "
"If the upload fails (connection refused, wrong host, TLS error), ask the "
"server operator to set OPENVIKING_PUBLIC_BASE_URL to the agent-facing "
"URL of the OpenViking server (e.g. via docker-compose `environment:` "
"or systemd unit) and retry."
)
return prose
# -- add_skill -------------------------------------------------------------
def _format_skill_install_result(result: Dict[str, Any], *, list_only: bool) -> str:
if result.get("status") == "error":
return _mcp_failure(
f"Error adding skill: {result.get('message') or 'skill processing failed'}"
)
if list_only:
found = result.get("skills") or []
lines = [f"Skills in the source ({len(found)}); nothing was installed:"]
for item in found:
description = " ".join(str(item.get("description") or "").split())
lines.append(f"- {item.get('name', '?')} ({item.get('path', '')}): {description}")
return "\n".join(lines)
installed = result.get("installed") if "installed" in result else [result]
lines = [f"Skill added: {item['root_uri']}" for item in installed]
lines.append(
"Read <uri>/SKILL.md to use it now; semantic search finds it once indexing completes."
)
return "\n".join(lines)
@_mcp_error_results()
@mcp.tool(annotations=_OPEN_WORLD_DESTRUCTIVE_TOOL_ANNOTATIONS)
async def add_skill(
data: str = "",
path: str = "",
skills: Optional[list[str]] = None,
target_uri: str = "",
list_only: bool = False,
) -> str:
"""Create, install, or replace an agent skill in OpenViking.
New skill: pass the full SKILL.md text (YAML frontmatter with ``name`` and
``description``, then the Markdown body) as ``data``.
Git source: pass a repository URL or a GitHub ``.../tree/<ref>/<dir>`` URL as ``path``.
Every skill in the source is installed unless ``skills`` names some; ``list_only=true``
lists them without installing.
Local skill: pass the path of a SKILL.md, a skill directory, or a .zip as ``path``. The
response is an upload instruction — zip a directory first, then HTTP POST the file to the
returned URL and the server installs it; you do NOT need to call this tool again.
Installing under an existing name replaces that skill's SKILL.md and adds the new files;
files the new version no longer has are kept. Ask the user before installing from a
source they did not name.
This is the only MCP tool that creates or changes a skill. To update one, read its
SKILL.md, revise the whole text, and call add_skill again with the same name and the same
``target_uri``; do not use the write or edit tools on files inside a skill package, and do
not use forget or a directory move to delete or rename one -- remove a skill with
``ov skills remove <name>`` or ``DELETE /api/v1/skills/{name}``, and rename it by
installing it under the new name and removing the old one.
Args:
data: Full SKILL.md text of a skill to create or replace.
path: Git URL, or a local path to a SKILL.md, a skill directory, or a .zip.
skills: Names of the skill directories to install from a multi-skill source.
target_uri: Skill root to install under. Empty installs into the caller's own
skills; "viking://agent/skills" shares the skill with the whole account.
list_only: Describe the skills in a Git or local source without installing them.
"""
ctx = _get_ctx()
path = path.strip()
if data.strip() and path:
return _mcp_failure("Error: pass either 'data' (SKILL.md text) or 'path', not both.")
if not data.strip() and not path:
return _mcp_failure(
"Error: provide 'data' (full SKILL.md text) or 'path' (Git URL or local path)."
)
if data.strip() and looks_like_local_path(data.strip()):
return _mcp_failure(
f"Error: 'data' looks like a file path. Pass it as add_skill(path=\"{data.strip()}\")."
)
if path.startswith("viking://"):
return _mcp_failure(
"Error: 'path' must be a Git URL or a local path. To copy a skill already in "
"OpenViking, read its SKILL.md and pass the text as 'data'."
)
is_git = path.startswith(GIT_SKILL_SOURCE_PREFIXES)
if path and not is_git and is_remote_resource_source(path):
return _mcp_failure(
f"Error: unsupported skill source '{path}'. Pass a Git URL "
f"({', '.join(GIT_SKILL_SOURCE_PREFIXES)}) or a local path."
)
try:
target = resolve_path_variables(target_uri).strip() if target_uri else ""
if target:
target = validate_content_target_uri(target, ctx, kind="skill", field_name="target_uri")
# Fail here, not after a one-time upload token is spent on a root the installer rejects.
target = SkillProcessor._resolve_skill_root_uri(ctx, target) # noqa: SLF001
except (InvalidArgumentError, PermissionDeniedError) as exc:
return _mcp_failure(exc)
if data.strip() or is_git:
try:
result = await install_skills(
data or path,
ctx,
names=skills,
list_only=list_only,
target_uri=target,
source_metadata=(
{"type": "mcp", "source": "inline_content", "operation": "add"}
if data.strip()
else None
),
)
except OpenVikingError as exc:
return _mcp_failure(exc)
except Exception as exc:
return _mcp_failure(f"Error adding skill: {exc}")
return _format_skill_install_result(result, list_only=list_only)
server_config = get_server_config()
ttl_seconds = (
server_config.upload_signed_ttl_seconds
if server_config is not None
else _DEFAULT_UPLOAD_TTL_SECONDS
)
token, expires_at = upload_token_store.issue(
ctx.user.account_id,
ctx.user.user_id,
ttl_seconds=ttl_seconds,
role=ctx.role,
from_oauth=ctx.from_oauth,
actor_peer_id=ctx.actor_peer_id or "",
kind="skill",
skill_target_uri=target,
skill_names=skills,
list_only=list_only,
)
base_url, url_source = _resolve_public_base_url()
upload_url = f"{base_url}/api/v1/resources/temp_upload?token={quote(token, safe='')}"
expires_iso = datetime.fromtimestamp(expires_at, tz=timezone.utc).isoformat(timespec="seconds")
minutes = max(1, ttl_seconds // 60)
if list_only:
headline = "Local skill source detected — upload it to list the skills it contains.\n"
outcome = (
"The URL's token authorizes this one upload (no OpenViking API key needed). The "
"server only lists the skills in the file and installs nothing; the upload response "
"carries each skill's name, path, and description. To install, call add_skill again "
"without list_only (skills=[...] picks some) and upload to the new URL.\n"
)
else:
headline = "Local skill detected — upload it to install.\n"
outcome = (
"The URL's token authorizes this one upload (no OpenViking API key needed) and the "
"server installs the skill once the file arrives — you do NOT need to call add_skill "
"again. The upload response carries the installed skill URIs.\n"
)
prose = (
headline + "\n"
"A skill directory must be zipped first (a single SKILL.md can be uploaded as is). "
"Every file in the archive is stored with the skill, so leave out VCS data and "
"secrets, for example:\n"
"\n"
" cd <parent dir> && rm -f /tmp/<name>.zip && zip -r /tmp/<name>.zip <name> "
"-x '*/.git/*' '*/.env*' '*/node_modules/*' '*/.DS_Store'\n"
"\n"
'Then HTTP POST the file (multipart/form-data, field name "file") to:\n'
"\n"
f" {upload_url}\n"
"\n" + outcome + "\n"
"If the OpenViking server sits behind a private gateway or reverse proxy that "
"requires extra request headers, replay the same headers you use for MCP calls "
"when POSTing the file.\n"
"\n"
f"This upload URL expires in ~{minutes} minutes ({expires_iso})."
)
if url_source not in ("env", "config"):
prose += (
"\n\n"
"Note for the user: this upload URL was auto-detected from the incoming "
"request because OPENVIKING_PUBLIC_BASE_URL is not set on the server. "
"If the upload fails (connection refused, wrong host, TLS error), ask the "
"server operator to set OPENVIKING_PUBLIC_BASE_URL to the agent-facing "
"URL of the OpenViking server and retry."
)
return prose
# -- watch management ------------------------------------------------------
# MCP exposes the minimum closure: list + cancel. Pause/resume/trigger and
# the unified `update` verb are intentionally NOT exposed — they're either
# low-value for agents or invite unwanted autonomous decisions. Power users
# should reach for the REST API or the `ov task watch *` CLI (`pause`,
# `resume`, `trigger`, `update --interval`, etc.) for those operations.
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
async def list_watches() -> str:
"""List watch tasks (auto-refresh subscriptions) visible to the current user."""
service = get_service()
ctx = _get_ctx()
scheduler = getattr(service, "watch_scheduler", None)
if scheduler is None or not scheduler.is_running:
return _mcp_failure("Error: Watch scheduler not running")
wm = scheduler.watch_manager
if wm is None:
return _mcp_failure("Error: Watch scheduler not running")
# get_all_tasks does not raise PermissionDeniedError — it silently filters
# tasks the caller cannot see (watch_manager.py:596-624), so we just
# accept the filtered list.
tasks = await wm.get_all_tasks(
ctx.account_id,
ctx.user.user_id,
str(ctx.role),
active_only=False,
)
if not tasks:
return "No watch tasks."
lines = []
for t in tasks:
status = "active" if t.is_active else "paused"
nxt = t.next_execution_time.isoformat() if t.next_execution_time else "n/a"
lines.append(
f"- {t.to_uri or '(no uri)'} interval={t.watch_interval:g}m {status} next={nxt}"
)
return "\n".join(lines)
@_mcp_error_results()
@mcp.tool(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
service = get_service()
ctx = _get_ctx()
to_uri = _resolve_mcp_workspace_uri(to_uri, ctx)
scheduler = getattr(service, "watch_scheduler", None)
if scheduler is None or not scheduler.is_running:
return _mcp_failure("Error: Watch scheduler not running")
wm = scheduler.watch_manager
if wm is None:
return _mcp_failure("Error: Watch scheduler not running")
task = await wm.get_task_by_uri(
to_uri,
ctx.account_id,
ctx.user.user_id,
str(ctx.role),
)
if task is None:
return _mcp_failure(f"No watch task found for {to_uri}")
try:
# Return value (bool) is intentionally ignored: delete_task returns
# False only when the task was removed between our lookup and the
# delete call (a concurrent cancel from another caller). In that case
# the post-condition the caller wanted ("no watch on this URI") still
# holds, so we report the same success message either way. Permission
# errors still surface via the explicit except below.
_ = await wm.delete_task(
task.task_id,
ctx.account_id,
ctx.user.user_id,
str(ctx.role),
)
except _wm_mod.PermissionDeniedError as exc:
return _mcp_failure(PermissionDeniedError(str(exc), resource=to_uri))
return f"Watch cancelled: {to_uri}"
# -- grep ------------------------------------------------------------------
@_mcp_error_results()
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
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()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
patterns = [pattern] if isinstance(pattern, str) else pattern
semaphore = asyncio.Semaphore(10)
async def _grep_one(p: str) -> tuple[str, list[dict], Optional[str]]:
async with semaphore:
try:
result = await service.fs.grep(
resolved_uri,
p,
ctx=ctx,
case_insensitive=case_insensitive,
node_limit=node_limit,
)
return (p, result.get("matches", []), None)
except Exception as exc:
# One bad pattern must not cost the others their matches -- that is what
# the fan-out is for -- but an empty list is indistinguishable from a real
# miss, so carry the reason instead of dropping it. POST /search/grep maps
# and re-raises these; reporting them is what keeps the two faces agreeing
# about whether a failure is a result.
code = exc.code if isinstance(exc, OpenVikingError) else type(exc).__name__
return (p, [], f"{code}: {exc}")
results = await asyncio.gather(*[_grep_one(p) for p in patterns])
merged: dict[str, list[tuple]] = {}
total = 0
failures: list[tuple[str, str]] = []
for p, matches, error in results:
if error is not None:
failures.append((p, error))
total += len(matches)
for m in matches:
m_uri = m.get("uri", "?")
merged.setdefault(m_uri, []).append((m.get("line", "?"), m.get("content", ""), p))
failure_lines = [f" {p}: {error}" for p, error in failures]
if not merged:
if failures and len(failures) == len(results):
return _mcp_failure("grep failed for every pattern:\n" + "\n".join(failure_lines))
if failures:
successful = [p for p, _, error in results if error is None]
return (
f"No matches found for successful pattern(s): {', '.join(successful)}\n"
"Patterns that could not be searched:\n" + "\n".join(failure_lines)
)
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}")
if failures:
lines.append("\nPatterns that could not be searched:")
lines.extend(failure_lines)
return "\n".join(lines)
# -- glob ------------------------------------------------------------------
@_mcp_error_results()
@mcp.tool(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()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
try:
result = await service.fs.glob(pattern, ctx=ctx, uri=resolved_uri, node_limit=node_limit)
except OpenVikingError as exc:
return _mcp_failure(exc)
except Exception as e:
return _mcp_failure(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 ----------------------------------------------------------------
@_mcp_error_results()
@mcp.tool(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.
Deleting a skill directory this way leaves the skill's stored privacy values behind:
remove a skill with ``ov skills remove <name>`` or ``DELETE /api/v1/skills/{name}``."""
service = get_service()
ctx = _get_ctx()
resolved_uri = _resolve_mcp_workspace_uri(uri, ctx)
await service.fs.rm(resolved_uri, ctx=ctx, recursive=recursive)
return f"Deleted: {resolved_uri}"
# -- health ----------------------------------------------------------------
@mcp.tool(annotations=_READ_ONLY_TOOL_ANNOTATIONS)
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}"
# ---------------------------------------------------------------------------
# Portable tool schemas
# ---------------------------------------------------------------------------
#
# FastMCP derives tool input schemas from Python type hints, so Optional/Union
# parameters become `anyOf` nodes with no top-level `type`, and nested models
# become `$ref`/`$defs`. That is valid JSON Schema, but several LLM function
# calling APIs (notably Gemini's OpenAPI 3.0 subset) require an explicit
# `type` on every schema node and reject `anyOf`/`$ref`, so MCP clients that
# forward our schemas verbatim get the whole request rejected. Rewrite the
# advertised schemas into a plain-typed form: drop null branches, collapse
# unions to their most general branch, and inline $refs. Runtime argument
# validation still uses the original function signatures, so union parameters
# keep accepting every branch (e.g. `read` still takes a bare URI string even
# though the schema advertises an array).
_PORTABLE_TYPE_PREFERENCE = ("array", "object", "string", "number", "integer", "boolean")
def _portable_schema(schema: Any, defs: Optional[Dict[str, Any]] = None) -> Any:
if not isinstance(schema, dict):
return schema
if defs is None:
defs = schema.get("$defs") or {}
node = {k: v for k, v in schema.items() if k != "$defs"}
ref = node.pop("$ref", None)
if isinstance(ref, str) and ref.startswith("#/$defs/"):
target = defs.get(ref.rsplit("/", 1)[-1])
if isinstance(target, dict):
return _portable_schema({**target, **node}, defs)
any_of = node.pop("anyOf", None)
if isinstance(any_of, list):
branches = [
b
for b in (_portable_schema(b, defs) for b in any_of)
if isinstance(b, dict) and b.get("type") != "null"
]
if branches:
def _rank(branch: Dict[str, Any]) -> int:
branch_type = branch.get("type")
if branch_type in _PORTABLE_TYPE_PREFERENCE:
return _PORTABLE_TYPE_PREFERENCE.index(branch_type)
return len(_PORTABLE_TYPE_PREFERENCE)
node = {**min(branches, key=_rank), **node}
# A null default contradicts the collapsed non-null type; omission
# already means "not provided", so drop it.
if node.get("default", "") is None:
node.pop("default")
if isinstance(node.get("properties"), dict):
node["properties"] = {
key: _portable_schema(value, defs) for key, value in node["properties"].items()
}
for key in ("items", "additionalProperties"):
if isinstance(node.get(key), dict):
node[key] = _portable_schema(node[key], defs)
if "type" not in node:
if "properties" in node:
node["type"] = "object"
elif "items" in node:
node["type"] = "array"
else:
enum_values = node.get("enum") or ([node["const"]] if "const" in node else [])
sample = enum_values[0] if enum_values else ""
if isinstance(sample, bool):
node["type"] = "boolean"
elif isinstance(sample, int):
node["type"] = "integer"
elif isinstance(sample, float):
node["type"] = "number"
else:
node["type"] = "string"
return node
def _apply_portable_schemas() -> None:
for tool in mcp._tool_manager.list_tools():
tool.parameters = _portable_schema(tool.parameters)
_apply_portable_schemas()
# ---------------------------------------------------------------------------
# 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():
tools = mcp._tool_manager.list_tools()
logger.info(
"MCP endpoint ready (%d tools: %s)", len(tools), ", ".join(tool.name for tool in tools)
)
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)