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): progressive single-entrypoint upload for local files (#1847)
t0saki41a33ec16aec
diff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex 74f01a318..b62219735 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -111,12 +111,49 @@ Once connected, OpenViking exposes 9 tools:| `read` | Read one or more `viking://` URIs | `uris` (single string or array) || `list` | List entries under a `viking://` directory | `uri`, `recursive` (optional) || `store` | Store messages into long-term memory (triggers extraction) | `messages` (list of `{role, content}`) |-| `add_resource` | Add a local file or URL as a resource | `path`, `description` (optional) |+| `add_resource` | Add a local file or URL as a resource (local files trigger a progressive upload flow) | `path`, `temp_file_id` (optional), `description` (optional), `watch_interval` (optional, minutes — auto-refresh cadence for remote URLs), `to` (optional, target `viking://resources/...` URI; required when `watch_interval > 0`) || `grep` | Regex content search across `viking://` files | `uri`, `pattern` (string or array), `case_insensitive` || `glob` | Find files matching a glob pattern | `pattern`, `uri` (optional scope) || `forget` | Delete any `viking://` URI (use `search` to find it first; pass `recursive=true` to delete a directory) | `uri`, `recursive` (optional) || `health` | Check OpenViking service health | none |+### Adding local-file resources (progressive upload)++The `add_resource` tool accepts both **remote URLs** and **local file paths**, handled differently:++- **Remote URL** (`http(s)://`, `git@`, `ssh://`, `git://`): single round-trip — the server fetches and ingests directly.+- **Local file path**: the tool returns a **two-step upload instruction** (plain prose with `Step 1` / `Step 2` formatting). The agent must:+ 1. POST the file as `multipart/form-data` to the `temp_upload_signed` URL given in the response (URL embeds a one-shot token; 10-minute TTL by default). The server mints the `temp_file_id` at write time and returns it as JSON: `{"temp_file_id": "..."}`.+ 2. Read `temp_file_id` from that response, then call `add_resource(temp_file_id="<id from step 1>")` again — the server resolves the file via `TempUploadStore` and ingests.++This lets any MCP client — including sandboxed environments without a local filesystem (Claude web, Manus, etc.) — push files into OpenViking without pre-installing the `ov` CLI. The signed endpoint shares the same persistence layer as the authenticated `temp_upload` route, so the `local` / `shared` upload modes (and multi-worker support via the `shared` mode) apply equally.++#### When you must set `OPENVIKING_PUBLIC_BASE_URL`++The upload URL the tool returns is resolved server-side in this order:++1. Environment variable `OPENVIKING_PUBLIC_BASE_URL`+2. `server.public_base_url` in `ov.conf`+3. Request headers `X-Forwarded-Host` / `X-Forwarded-Proto` (forwarded by the reverse-proxy chain)+4. Request `Host` header (direct connection)+5. Listen-address fallback: `http://{host}:{port}`++If the server runs behind a reverse proxy (nginx / cloud LB / k8s ingress / MCP proxy), **set `OPENVIKING_PUBLIC_BASE_URL` explicitly**. Layers 3–5 are inferred and break in these cases:++- The reverse proxy / MCP proxy does not forward `X-Forwarded-*` headers+- The server listens on `0.0.0.0` (fallback URL contains `0.0.0.0`, unreachable from agents)+- Multi-hop proxy with host rewriting++When the variable is unset and inference is used, the tool response automatically appends a hint asking the user to configure it. Docker Compose example:++```yaml+services:+ openviking:+ image: ghcr.io/volcengine/openviking:latest+ environment:+ OPENVIKING_PUBLIC_BASE_URL: "https://ov.your-domain.com"+```+## Troubleshooting### Connection refuseddiff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex f174c1cd1..b1d16e098 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -103,12 +103,49 @@ claude mcp add --transport http openviking \| `read` | 读取一个或多个 `viking://` URI 的内容 | `uris`(单个字符串或数组) || `list` | 列出 `viking://` 目录下的条目 | `uri`, `recursive`(可选) || `store` | 存储消息到长期记忆(触发记忆提取) | `messages`(`{role, content}` 列表) |-| `add_resource` | 添加本地文件或 URL 作为资源 | `path`, `description`(可选) |+| `add_resource` | 添加本地文件或 URL 作为资源(本地文件触发渐进式上传流) | `path`, `temp_file_id`(可选), `description`(可选), `watch_interval`(可选,分钟数 — 远程 URL 的自动刷新周期), `to`(可选,目标 `viking://resources/...` URI;`watch_interval > 0` 时必填) || `grep` | 在 `viking://` 文件中进行正则内容搜索 | `uri`, `pattern`(字符串或数组), `case_insensitive` || `glob` | 按 glob 模式匹配文件 | `pattern`, `uri`(可选范围) || `forget` | 删除任意 `viking://` URI(先用 `search` 查找;删除目录需 `recursive=true`) | `uri`, `recursive`(可选) || `health` | 检查 OpenViking 服务健康状态 | 无 |+### 添加本地文件资源(渐进式上传)++`add_resource` 工具同时接受**远程 URL** 和**本地文件路径**。两者的处理路径不同:++- **远程 URL**(`http(s)://`、`git@`、`ssh://`、`git://`):一次调用即完成,server 直接拉取并入库。+- **本地文件路径**:返回**两步上传指令**(纯文本,Step 1 / Step 2 排版),agent 需要:+ 1. 把文件以 `multipart/form-data` POST 到响应里给出的 `temp_upload_signed` URL(URL 内嵌一次性 token,默认 10 分钟过期)。Server 在写入时 mint `temp_file_id`,通过 JSON `{"temp_file_id": "..."}` 返回。+ 2. 从响应体读出 `temp_file_id`,再次调用 `add_resource(temp_file_id="<step 1 返回的 id>")`,server 通过 `TempUploadStore` 解析文件并入库。++这样设计是为了让任何 MCP 客户端(包括无本地文件系统的 Claude web、Manus 等沙箱环境)都能往 OpenViking 灌文件,而不需要客户端预装 `ov` CLI。签名端点和认证版的 `temp_upload` 共享同一个持久化层(`TempUploadStore`),所以 `local` / `shared` 上传模式(以及 `shared` 模式带来的多 worker 支持)在两个端点上行为一致。++#### 必须配置 `OPENVIKING_PUBLIC_BASE_URL` 的场景++工具响应里给出的上传 URL,server 端按以下顺序解析:++1. 环境变量 `OPENVIKING_PUBLIC_BASE_URL`+2. `ov.conf` 中的 `server.public_base_url`+3. 请求头 `X-Forwarded-Host` / `X-Forwarded-Proto`(由反代链转发)+4. 请求头 `Host`(直连场景)+5. 监听地址兜底 `http://{host}:{port}`++只要 server 部署在反向代理(nginx / cloud LB / k8s ingress)后,**强烈建议显式配置 `OPENVIKING_PUBLIC_BASE_URL`**。后两层是兜底推断,在以下情况会失败:++- 反代/MCP proxy 不转发 `X-Forwarded-*` 头+- server 监听 `0.0.0.0`(fallback URL 含 `0.0.0.0`,agent 无法连接)+- 多层代理存在 host 重写++未配置该变量且 fallback 推断生效时,工具响应末尾会自动附带提示,告知用户在 server 端设置该环境变量。Docker Compose 部署示例:++```yaml+services:+ openviking:+ image: ghcr.io/volcengine/openviking:latest+ environment:+ OPENVIKING_PUBLIC_BASE_URL: "https://ov.your-domain.com"+```+## 故障排除### 连接被拒绝diff --git a/openviking/server/app.py b/openviking/server/app.pyindex 47656cc1c..d23425800 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -23,7 +23,7 @@ from openviking.server.config import (load_server_config,validate_server_config,)-from openviking.server.dependencies import set_service+from openviking.server.dependencies import set_server_config, set_servicefrom openviking.server.error_mapping import map_exceptionfrom openviking.server.identity import AuthMode, Rolefrom openviking.server.models import ERROR_CODE_TO_HTTP_STATUS, ErrorInfo, Response@@ -311,6 +311,7 @@ def create_app()app.state.config = config+ set_server_config(config)# Add CORS middlewareapp.add_middleware(diff --git a/openviking/server/config.py b/openviking/server/config.pyindex 0062742ac..3de9e7048 100644--- a/openviking/server/config.py+++ b/openviking/server/config.py@@ -153,6 +153,13 @@ class ServerConfig(BaseModel):encryption_enabled: bool = False # Whether file-level AES encryption is enabledapi_key_hashing_enabled: bool = False # Whether API key Argon2id hashing is enabled (default: false, rely on file encryption)observability: ObservabilityConfig = Field(default_factory=ObservabilityConfig)+ # Public-facing base URL emitted in MCP-issued upload instructions. See+ # ``openviking.server.mcp_endpoint._resolve_public_base_url`` for the full+ # resolution chain: env var > this field > X-Forwarded-Host/Proto > Host header+ # > listen-address fallback. Set this (or the env var) when the server runs+ # behind a reverse proxy that does not forward X-Forwarded-* headers.+ public_base_url: Optional[str] = None+ upload_signed_ttl_seconds: int = 600temp_upload: TempUploadConfig = Field(default_factory=TempUploadConfig)model_config = {"extra": "forbid"}diff --git a/openviking/server/dependencies.py b/openviking/server/dependencies.pyindex c99564acb..1c9f11e74 100644--- a/openviking/server/dependencies.py+++ b/openviking/server/dependencies.py@@ -2,11 +2,15 @@# SPDX-License-Identifier: AGPL-3.0"""Dependency injection for OpenViking HTTP Server."""-from typing import Optional+from typing import TYPE_CHECKING, Optionalfrom openviking.service.core import OpenVikingService+if TYPE_CHECKING:+ from openviking.server.config import ServerConfig+_service: Optional[OpenVikingService] = None+_server_config: Optional["ServerConfig"] = Nonedef get_service() -> OpenVikingService:@@ -31,3 +35,18 @@ def set_service(service: OpenVikingService) -> None:"""global _service_service = service+++def get_server_config() -> Optional["ServerConfig"]:+ """Return the active ServerConfig if one was registered, else None.++ MCP tools that need server-level settings (e.g. public_base_url for upload URLs)+ use this to read the loaded ServerConfig without going through ``app.state``.+ """+ return _server_config+++def set_server_config(config: "ServerConfig") -> None:+ """Register the active ServerConfig at server bootstrap."""+ global _server_config+ _server_config = configdiff --git a/openviking/server/local_input_guard.py b/openviking/server/local_input_guard.pyindex 01c691e5c..9fdaccf20 100644--- a/openviking/server/local_input_guard.py+++ b/openviking/server/local_input_guard.py@@ -14,6 +14,11 @@ from openviking_cli.exceptions import PermissionDeniedError_WINDOWS_DRIVE_RE = re.compile(r"^[A-Za-z]:[\\/]")_REMOTE_SOURCE_PREFIXES = ("http://", "https://", "git@", "ssh://", "git://")+# Shape of temp_file_ids minted by TempUploadStore. Used by MCP add_resource to+# detect when an agent has passed a tfid as the `path` argument by mistake and+# give them a hint to use the `temp_file_id` kwarg instead.+TEMP_FILE_ID_RE = re.compile(r"^(upload_|shared_)[a-zA-Z0-9]+(\.[^/\\]+)?$")+def is_remote_resource_source(source: str) -> bool:"""Return True if *source* is a remotely fetchable resource location."""diff --git a/openviking/server/mcp_endpoint.py b/openviking/server/mcp_endpoint.pyindex 156cae9e6..f66171f81 100644--- a/openviking/server/mcp_endpoint.py+++ b/openviking/server/mcp_endpoint.py@@ -16,8 +16,11 @@ are extracted from HTTP request scope and propagated via contextvars.from __future__ import annotationsimport contextvars+import osfrom contextlib import asynccontextmanager+from datetime import datetime, timezonefrom typing import List, Literal, Optional+from urllib.parse import quotefrom mcp.server.fastmcp import FastMCPfrom mcp.server.transport_security import TransportSecuritySettings@@ -27,8 +30,14 @@ from starlette.responses import JSONResponsefrom starlette.types import ASGIApp, Receive, Scope, Sendfrom openviking.server.auth import resolve_identity-from openviking.server.dependencies import get_service+from openviking.server.dependencies import get_server_config, get_servicefrom openviking.server.identity import RequestContext+from openviking.server.local_input_guard import (+ TEMP_FILE_ID_RE,+ is_remote_resource_source,+)+from openviking.server.temp_upload_store import TempUploadStore+from openviking.server.upload_token_store import upload_token_storefrom openviking_cli.exceptions import (InvalidArgumentError,PermissionDeniedError,@@ -47,6 +56,14 @@ _mcp_ctx: contextvars.ContextVar[Optional[RequestContext]] = contextvars.Context"_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()@@ -155,11 +172,18 @@ class _IdentityASGIMiddleware:role=identity.role,namespace_policy=identity.namespace_policy,)- token = _mcp_ctx.set(ctx)+ 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(token)+ _mcp_ctx.reset(ctx_token)+ _request_url_ctx.reset(url_token)# ---------------------------------------------------------------------------@@ -343,17 +367,62 @@ async def remember(messages: list[StoreMessage]) -> str:# -- add_resource -----------------------------------------------------------_LOCAL_FILE_HINT = (- "MCP add_resource only accepts remote URLs (http(s)://, git@, ssh://, git://). "- "For local files or directories, use the `ov` CLI:\n"- " 1. Try first: ov add-resource <path>\n"- " (if `ov` is already on PATH, this is all you need)\n"- " 2. If `ov` is not installed, install the npm CLI package:\n"- " npm i -g @openviking/cli\n"- " 3. Only if connecting to a remote / multi-tenant OpenViking server, "- "configure ~/.openviking/ovcli.conf:\n"- ' {"url": "https://your-host", "api_key": "your-key"}'-)+_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:+ return f"http://{config.host}:{config.port}", "listen"+ return "http://127.0.0.1:1933", "listen"+_WATCH_REQUIRES_TO_HINT = ("watch_interval > 0 requires `to` to be specified (the stable target URI to refresh into). "@@ -367,44 +436,116 @@ _WATCH_REQUIRES_TO_HINT = (@mcp.tool()async def add_resource(- path: str,+ path: str = "",+ temp_file_id: str = "",description: str = "",watch_interval: float = 0,to: str = "",) -> str:- """Add a remote resource (HTTP/HTTPS URL or git URL) to OpenViking. Asynchronous — processed in the background. Local file paths are not supported here; use the `ov add-resource` CLI for local files.+ """Add a resource to OpenViking. Asynchronous — processing happens in the background.++ Three ways to invoke:++ 1. Remote URL: pass ``path`` set to an http(s)://, git@, ssh://, or git:// URL.+ Returns a success message immediately. Supports ``watch_interval`` + ``to`` for+ auto-refresh subscriptions.++ 2. Local file: pass ``path`` set to a local filesystem path (e.g. ``/tmp/foo.pdf``).+ The response is NOT a success message — it's a multi-step upload instruction.+ HTTP POST the file to the URL the response gives you, read ``temp_file_id`` from+ the upload response body, then call this tool again with that ``temp_file_id``.++ 3. Re-call after upload: pass ``temp_file_id`` set to the value the signed upload+ response returned. Omit ``path``. The server resolves the file via TempUploadStore+ and ingests it.Args:- path: Remote URL (http(s):// or git URL).+ path: Remote URL or local filesystem path.+ temp_file_id: Server-minted upload id from a prior signed upload. Either+ ``path`` or ``temp_file_id`` is required.description: Optional human-readable reason for adding the resource.- watch_interval: Auto-refresh cadence in minutes. 0 (default) = no watch. >0 = periodically re-fetch the resource at that cadence (full re-ingest each time). Prefer >=1440 (24h) unless the source genuinely changes faster — every refresh re-embeds the entire resource. Requires `to`.- to: Target URI under viking://resources/ (e.g. "viking://resources/volcengine/OpenViking"). Required when watch_interval > 0. Leave empty for one-shot adds — the system will auto-derive a URI from the source.+ watch_interval: Auto-refresh cadence in minutes. 0 (default) = no watch.+ >0 = periodically re-fetch the resource at that cadence (full re-ingest+ each time). Prefer >=1440 (24h) unless the source genuinely changes+ faster — every refresh re-embeds the entire resource. Requires ``to``.+ Only applies to remote-URL invocations.+ to: Target URI under viking://resources/ (e.g.+ "viking://resources/volcengine/OpenViking"). Required when+ watch_interval > 0. Leave empty for one-shot adds — the system will+ auto-derive a URI from the source."""from openviking.server.local_input_guard import require_remote_resource_sourceservice = get_service()ctx = _get_ctx()- try:- path = require_remote_resource_source(path)- except PermissionDeniedError:- return f"Error: {_LOCAL_FILE_HINT}"+if watch_interval < 0:return ("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.")- if watch_interval > 0 and not to:- return f"Error: {_WATCH_REQUIRES_TO_HINT}"- try:- result = await service.resources.add_resource(- path=path,- ctx=ctx,- to=to or None,- reason=description,- wait=False,- watch_interval=watch_interval,- enforce_public_remote_targets=True,++ # Branch 1: ingest by temp_file_id (second leg of progressive upload, or REST-style)+ if temp_file_id:+ from openviking.server.config import ServerConfig++ server_config = get_server_config() or ServerConfig()+ store = TempUploadStore.build(server_config)+ try:+ resolved = await store.resolve_for_consume(temp_file_id, ctx)+ except (PermissionDeniedError, InvalidArgumentError) as exc:+ return f"Error: {exc}"+ try:+ try:+ result = await service.resources.add_resource(+ path=resolved.local_path,+ ctx=ctx,+ reason=description,+ source_name=resolved.original_filename,+ wait=False,+ allow_local_path_resolution=True,+ enforce_public_remote_targets=True,+ )+ except Exception as exc:+ await store.mark_failed(resolved, ctx)+ return f"Error adding resource: {exc}"+ await store.mark_consumed(resolved, ctx)+ finally:+ await resolved.cleanup()+ root_uri = result.get("root_uri", "")+ return (+ f"Resource added: {root_uri}"+ if root_uri+ else "Resource added (processing in background)."+ )++ if not path:+ return "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 (+ 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 — same flow as before+ if is_remote_resource_source(path):+ if watch_interval > 0 and not to:+ return f"Error: {_WATCH_REQUIRES_TO_HINT}"+ try:+ path = require_remote_resource_source(path)+ result = await service.resources.add_resource(+ path=path,+ ctx=ctx,+ to=to or None,+ reason=description,+ wait=False,+ watch_interval=watch_interval,+ enforce_public_remote_targets=True,+ )+ except Exception as exc:+ return f"Error adding resource: {exc}"root_uri = result.get("root_uri", "")if watch_interval > 0:watch_suffix = f" (watch enabled, refresh every {watch_interval:g} minute(s))"@@ -415,8 +556,54 @@ async def add_resource(if root_urielse f"Resource added (processing in background){watch_suffix}.")- except Exception as e:- return f"Error adding resource: {e}"++ # 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,+ ctx.user.agent_id,+ ttl_seconds=ttl_seconds,+ )+ base_url, url_source = _resolve_public_base_url()+ upload_url = f"{base_url}/api/v1/resources/temp_upload_signed?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 required before this resource can be ingested.\n"+ "\n"+ 'Step 1. HTTP POST the file bytes (multipart/form-data, field name "file") to:\n'+ "\n"+ f" {upload_url}\n"+ "\n"+ ' The response will be JSON: {"temp_file_id": "<id>"}\n'+ "\n"+ "Step 2. Read `temp_file_id` from that response, then call this tool again:\n"+ "\n"+ ' add_resource(temp_file_id="<id from step 1>")\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 Step 1 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# -- watch management ------------------------------------------------------diff --git a/openviking/server/routers/resources.py b/openviking/server/routers/resources.pyindex dca02760e..5b95ba021 100644--- a/openviking/server/routers/resources.py+++ b/openviking/server/routers/resources.py@@ -4,21 +4,21 @@from typing import Any, Optional-from fastapi import APIRouter, Depends, File, Form, Request, UploadFile+from fastapi import APIRouter, Depends, File, Form, HTTPException, Query, Request, UploadFilefrom pydantic import BaseModel, ConfigDict, model_validatorfrom openviking.core.path_variables import resolve_path_variablesfrom openviking.server.auth import get_request_contextfrom openviking.server.dependencies import get_service-from openviking.server.identity import RequestContext-from openviking.server.local_input_guard import (- require_remote_resource_source,-)+from openviking.server.identity import AccountNamespacePolicy, RequestContext, Role+from openviking.server.local_input_guard import require_remote_resource_sourcefrom openviking.server.responses import response_from_resultfrom openviking.server.telemetry import run_operationfrom openviking.server.temp_upload_store import TempUploadStore+from openviking.server.upload_token_store import UploadTokenError, upload_token_storefrom openviking.telemetry import TelemetryRequestfrom openviking_cli.exceptions import InvalidArgumentError+from openviking_cli.session.user_id import UserIdentifierrouter = APIRouter(prefix="/api/v1", tags=["resources"])@@ -139,6 +139,51 @@ async def temp_upload(return response_from_result(execution.result, telemetry=execution.telemetry)[email protected]("/resources/temp_upload_signed")+async def temp_upload_signed(+ request: Request,+ file: UploadFile = File(...),+ token: str = Query(..., min_length=1),+ upload_mode: str = Query("local"),+):+ """Upload via short-lived signed token. Used by the MCP progressive-upload flow.++ No identity headers required — the token (issued by ``add_resource`` MCP for local-file+ paths) carries the bound (account_id, user_id, agent_id). The token is consumed on first+ use; subsequent attempts return 401. The server mints the ``temp_file_id`` at write time+ and returns it in the response body; the agent then calls ``add_resource`` with that id.++ Persistence flows through :class:`TempUploadStore`, so the same local/shared upload modes+ and size limit (``temp_upload.shared_max_size_bytes``) as the auth'd ``/temp_upload`` route+ apply here too.+ """+ try:+ account_id, user_id, agent_id = upload_token_store.consume(token)+ except UploadTokenError as exc:+ raise HTTPException(status_code=401, detail=str(exc)) from exc++ try:+ ctx = RequestContext(+ user=UserIdentifier(account_id, user_id, agent_id),+ role=Role.USER,+ namespace_policy=AccountNamespacePolicy(),+ )+ except ValueError as exc:+ raise HTTPException(status_code=400, detail=f"invalid identity in token: {exc}") from exc++ store = TempUploadStore.build(request.app.state.config)+ try:+ temp_file_id = await store.save_upload(file, upload_mode, ctx)+ except InvalidArgumentError as exc:+ # save_upload raises InvalidArgumentError for both bad mode and oversize.+ # Map oversize specifically to 413; the rest stay 400.+ msg = str(exc)+ status = 413 if "exceeds size limit" in msg else 400+ raise HTTPException(status_code=status, detail=msg) from exc++ return {"temp_file_id": temp_file_id}++@router.post("/resources")async def add_resource(http_request: Request,diff --git a/openviking/server/upload_token_store.py b/openviking/server/upload_token_store.pynew file mode 100644index 000000000..6a9d272db--- /dev/null+++ b/openviking/server/upload_token_store.py@@ -0,0 +1,93 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""In-memory store for short-lived upload tokens used by the MCP progressive upload flow.++Issued by the MCP ``add_resource`` tool when an agent passes a local-file path; consumed by+``POST /api/v1/resources/temp_upload_signed``. Tokens are 6-character base62 strings indexed+in a process-local dict — no signing key, no on-disk state, no replay-set bookkeeping.+``dict.pop`` doubles as the consume-and-burn primitive.++The token only carries the identity bound at issue time (account/user/agent). The+``temp_file_id`` is minted by :class:`openviking.server.temp_upload_store.TempUploadStore`+at upload time and returned to the agent in the upload response body — the token does+not pre-bind a filename, so the upload can flow through either the local or shared+TempUploadStore mode without a side-channel.++Single-worker only: tokens are lost on restart and not shared across uvicorn workers.+Multi-worker deployments should rely on the shared-mode TempUploadStore for the actual+file payload; only the brief upload-token handshake is process-local.+"""++from __future__ import annotations++import secrets+import string+import time+from dataclasses import dataclass+from typing import Optional, Tuple++_TOKEN_ALPHABET = string.ascii_letters + string.digits # base62+_TOKEN_LENGTH = 6+++class UploadTokenError(Exception):+ """Raised when an upload token is unknown or expired."""+++@dataclass(frozen=True)+class _TokenInfo:+ account_id: str+ user_id: str+ agent_id: str+ expires_at: float+++class UploadTokenStore:+ def __init__(self) -> None:+ self._store: dict[str, _TokenInfo] = {}++ def issue(+ self,+ account_id: str,+ user_id: str,+ agent_id: str,+ ttl_seconds: int,+ ) -> Tuple[str, float]:+ """Mint a fresh token bound to (account, user, agent). Returns (token, expires_at)."""+ self._purge_expired()+ expires_at = time.time() + max(1, ttl_seconds)+ info = _TokenInfo(account_id, user_id, agent_id, expires_at)+ for _ in range(8):+ token = "".join(secrets.choice(_TOKEN_ALPHABET) for _ in range(_TOKEN_LENGTH))+ if token not in self._store:+ self._store[token] = info+ return token, expires_at+ raise RuntimeError("upload_token_store: failed to mint a unique token after 8 attempts")++ def consume(self, token: str) -> Tuple[str, str, str]:+ """Pop the token and validate it. Returns (account_id, user_id, agent_id) on success."""+ if not token:+ raise UploadTokenError("missing upload token")+ info = self._store.pop(token, None)+ if info is None:+ raise UploadTokenError("unknown or already-consumed upload token")+ if info.expires_at < time.time():+ raise UploadTokenError("upload token expired")+ return info.account_id, info.user_id, info.agent_id++ def peek(self, token: str) -> Optional[_TokenInfo]:+ """Read a token without consuming. Test helper only."""+ return self._store.get(token)++ def clear(self) -> None:+ """Reset state. Test helper only."""+ self._store.clear()++ def _purge_expired(self) -> None:+ now = time.time()+ for token, info in list(self._store.items()):+ if info.expires_at < now:+ self._store.pop(token, None)+++upload_token_store = UploadTokenStore()diff --git a/tests/server/test_mcp_endpoint.py b/tests/server/test_mcp_endpoint.pyindex f1f4a3263..6cf131d45 100644--- a/tests/server/test_mcp_endpoint.py+++ b/tests/server/test_mcp_endpoint.py@@ -312,17 +312,134 @@ async def test_store_skips_empty_message_content(service, monkeypatch):# ----------------------------------------------------------------------------async def test_add_resource_rejects_local_path_with_cli_hint(service):- result = await add_resource(path="/tmp/definitely_does_not_exist_xyz.md")- assert "error" in result.lower()- assert "ov add-resource" in result- assert "ovcli.conf" in result+async def test_add_resource_local_path_returns_upload_instruction(service):+ from openviking.server.upload_token_store import upload_token_store++ upload_token_store.clear()+ result = await add_resource(path="/tmp/sample_local_file_xyz.pdf")+ assert "upload required" in result.lower()+ assert "Step 1." in result+ assert "Step 2." in result+ assert "/api/v1/resources/temp_upload_signed" in result+ assert "token=" in result+ # The server now mints temp_file_id at upload time; the prose tells the agent+ # to read it from the upload response.+ assert "temp_file_id" in result+ assert "<id from step 1>" in result+ # Default fixture sets neither env nor config.public_base_url → URL is auto-inferred+ # and the troubleshooting hint must appear.+ assert "OPENVIKING_PUBLIC_BASE_URL" in result+ upload_token_store.clear()+++async def test_add_resource_local_path_uses_env_var_when_set(service, monkeypatch):+ from openviking.server.upload_token_store import upload_token_store++ upload_token_store.clear()+ monkeypatch.setenv("OPENVIKING_PUBLIC_BASE_URL", "https://my-ov.example.com")+ result = await add_resource(path="/tmp/x.pdf")+ assert "https://my-ov.example.com/api/v1/resources/temp_upload_signed" in result+ # Explicit source → no troubleshooting hint+ assert "OPENVIKING_PUBLIC_BASE_URL is not set" not in result+ upload_token_store.clear()+++async def test_add_resource_local_path_uses_config_when_env_unset(service, monkeypatch):+ from openviking.server.config import ServerConfig+ from openviking.server.upload_token_store import upload_token_store++ upload_token_store.clear()+ monkeypatch.delenv("OPENVIKING_PUBLIC_BASE_URL", raising=False)+ monkeypatch.setattr(+ "openviking.server.dependencies._server_config",+ ServerConfig(public_base_url="https://configured.example.com"),+ )++ result = await add_resource(path="/tmp/x.pdf")+ assert "https://configured.example.com/api/v1/resources/temp_upload_signed" in result+ assert "OPENVIKING_PUBLIC_BASE_URL is not set" not in result+ upload_token_store.clear()+++async def test_add_resource_local_path_infers_from_x_forwarded_headers(service, monkeypatch):+ from openviking.server.mcp_endpoint import _request_url_ctx+ from openviking.server.upload_token_store import upload_token_store++ upload_token_store.clear()+ monkeypatch.delenv("OPENVIKING_PUBLIC_BASE_URL", raising=False)++ token = _request_url_ctx.set(+ {+ "x_forwarded_proto": "https",+ "x_forwarded_host": "ov.public.example.com",+ "host": "internal:1933",+ }+ )+ try:+ result = await add_resource(path="/tmp/x.pdf")+ finally:+ _request_url_ctx.reset(token)++ assert "https://ov.public.example.com/api/v1/resources/temp_upload_signed" in result+ # Inferred → hint must appear+ assert "OPENVIKING_PUBLIC_BASE_URL" in result+ upload_token_store.clear()+++async def test_add_resource_temp_file_id_lookalike_in_path_is_rejected(service):+ result = await add_resource(path="upload_abc123.pdf")+ assert "looks like a temp_file_id" in result.lower()+ assert 'temp_file_id="upload_abc123.pdf"' in result-async def test_add_resource_rejects_bare_filename_with_cli_hint(service):- result = await add_resource(path="some_local_file.md")+async def test_add_resource_neither_path_nor_temp_file_id(service):+ result = await add_resource()assert "error" in result.lower()- assert "ov add-resource" in result+ assert "path" in result.lower() or "temp_file_id" in result.lower()+++async def test_add_resource_remote_url_is_ingested(service, monkeypatch):+ captured = {}++ async def fake_add_resource(*, path, ctx, **kwargs):+ captured["path"] = path+ captured["enforce_public_remote_targets"] = kwargs.get("enforce_public_remote_targets")+ return {"root_uri": "viking://resources/test_remote"}++ monkeypatch.setattr(service.resources, "add_resource", fake_add_resource)+ result = await add_resource(path="https://example.com/x.md")+ assert "Resource added" in result+ assert captured["path"] == "https://example.com/x.md"+ assert captured["enforce_public_remote_targets"] is True+++async def test_add_resource_temp_file_id_branch_resolves_and_ingests(+ service, upload_temp_dir, monkeypatch+):+ """When temp_file_id is supplied, MCP resolves via TempUploadStore and ingests."""+ from openviking.server.upload_token_store import upload_token_store++ upload_token_store.clear()++ # Drop a file in the flat-local layout used by TempUploadStore._resolve_local.+ tfid = "upload_abcdef123.md"+ target = upload_temp_dir / tfid+ target.write_text("hello mcp")++ captured = {}++ async def fake_add_resource(*, path, ctx, **kwargs):+ captured["path"] = path+ captured["allow_local_path_resolution"] = kwargs.get("allow_local_path_resolution")+ return {"root_uri": "viking://resources/from_tfid"}++ monkeypatch.setattr(service.resources, "add_resource", fake_add_resource)++ result = await add_resource(temp_file_id=tfid)+ assert "Resource added" in result+ assert captured["path"] == str(target.resolve())+ assert captured["allow_local_path_resolution"] is True+ upload_token_store.clear()async def test_add_resource_watch_requires_to(service):diff --git a/tests/server/test_resources_temp_upload_signed.py b/tests/server/test_resources_temp_upload_signed.pynew file mode 100644index 000000000..f2ce25bba--- /dev/null+++ b/tests/server/test_resources_temp_upload_signed.py@@ -0,0 +1,103 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Tests for POST /api/v1/resources/temp_upload_signed."""++from __future__ import annotations++from pathlib import Path++import httpx+import pytest++from openviking.server.upload_token_store import upload_token_store++[email protected](autouse=True)+def _reset_token_store():+ upload_token_store.clear()+ yield+ upload_token_store.clear()+++def _issue(account_id: str = "acct", user_id: str = "user", agent_id: str = "agent"):+ token, _ = upload_token_store.issue(account_id, user_id, agent_id, ttl_seconds=600)+ return token+++async def test_signed_upload_writes_file_and_returns_minted_tfid(+ client: httpx.AsyncClient, upload_temp_dir: Path+):+ token = _issue()+ resp = await client.post(+ "/api/v1/resources/temp_upload_signed",+ params={"token": token},+ files={"file": ("hello.md", b"hello world", "text/markdown")},+ )+ assert resp.status_code == 200, resp.text+ body = resp.json()+ tfid = body["temp_file_id"]+ # TempUploadStore in local mode mints names like upload_<hex>.<ext>+ assert tfid.startswith("upload_")++ # File lands in the flat-local TempUploadStore layout, not a per-tenant subdir.+ written = upload_temp_dir / tfid+ assert written.is_file()+ assert written.read_bytes() == b"hello world"++ meta_path = upload_temp_dir / f"{tfid}.ov_upload.meta"+ assert meta_path.is_file()+++async def test_signed_upload_burns_token_on_use(client: httpx.AsyncClient, upload_temp_dir: Path):+ token = _issue()+ resp1 = await client.post(+ "/api/v1/resources/temp_upload_signed",+ params={"token": token},+ files={"file": ("a.txt", b"first", "text/plain")},+ )+ assert resp1.status_code == 200++ resp2 = await client.post(+ "/api/v1/resources/temp_upload_signed",+ params={"token": token},+ files={"file": ("a.txt", b"second", "text/plain")},+ )+ assert resp2.status_code == 401+++async def test_signed_upload_unknown_token(client: httpx.AsyncClient, upload_temp_dir: Path):+ resp = await client.post(+ "/api/v1/resources/temp_upload_signed",+ params={"token": "ZZZZZZ"},+ files={"file": ("upload_abc.md", b"x", "text/plain")},+ )+ assert resp.status_code == 401+++async def test_signed_upload_oversize_rejected(+ client: httpx.AsyncClient, upload_temp_dir: Path, app+):+ """Size cap is enforced while streaming by TempUploadStore — same limit as /temp_upload."""+ app.state.config.temp_upload.shared_max_size_bytes = 16++ token = _issue()+ big = b"x" * 64+ resp = await client.post(+ "/api/v1/resources/temp_upload_signed",+ params={"token": token},+ files={"file": ("big.bin", big, "text/plain")},+ )+ assert resp.status_code == 413+++async def test_legacy_temp_upload_still_writes_flat(+ client: httpx.AsyncClient, upload_temp_dir: Path+):+ """The CLI flow at POST /api/v1/resources/temp_upload must keep working unchanged."""+ resp = await client.post(+ "/api/v1/resources/temp_upload",+ files={"file": ("legacy.md", b"legacy", "text/plain")},+ )+ assert resp.status_code == 200+ tfid = resp.json()["result"]["temp_file_id"]+ assert (upload_temp_dir / tfid).is_file()diff --git a/tests/server/test_upload_token_store.py b/tests/server/test_upload_token_store.pynew file mode 100644index 000000000..abf149d3e--- /dev/null+++ b/tests/server/test_upload_token_store.py@@ -0,0 +1,104 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Tests for openviking/server/upload_token_store.py."""++from __future__ import annotations++import pytest++from openviking.server.upload_token_store import (+ _TOKEN_ALPHABET,+ _TOKEN_LENGTH,+ UploadTokenError,+ UploadTokenStore,+)+++def store() -> UploadTokenStore:+ return UploadTokenStore()+++def test_issue_returns_token_of_expected_length(store):+ token, expires_at = store.issue("acct", "user", "agent", ttl_seconds=60)+ assert len(token) == _TOKEN_LENGTH+ assert all(c in _TOKEN_ALPHABET for c in token)+ assert expires_at > 0+++def test_consume_roundtrip(store):+ token, _ = store.issue("acct", "user", "agent", ttl_seconds=60)+ aid, uid, agid = store.consume(token)+ assert (aid, uid, agid) == ("acct", "user", "agent")+++def test_consume_burns_token(store):+ token, _ = store.issue("acct", "user", "agent", ttl_seconds=60)+ store.consume(token)+ with pytest.raises(UploadTokenError, match="unknown or already-consumed"):+ store.consume(token)+++def test_consume_unknown_token(store):+ with pytest.raises(UploadTokenError, match="unknown or already-consumed"):+ store.consume("ZZZZZZ")+++def test_consume_missing_token(store):+ with pytest.raises(UploadTokenError, match="missing"):+ store.consume("")+++def test_consume_expired_token(store, monkeypatch):+ import openviking.server.upload_token_store as mod++ fake_now = [1000.0]+ monkeypatch.setattr(mod.time, "time", lambda: fake_now[0])++ token, _ = store.issue("acct", "user", "agent", ttl_seconds=60)+ fake_now[0] += 61+ with pytest.raises(UploadTokenError, match="expired"):+ store.consume(token)+++def test_purge_expired_drops_stale_tokens(store, monkeypatch):+ import openviking.server.upload_token_store as mod++ fake_now = [1000.0]+ monkeypatch.setattr(mod.time, "time", lambda: fake_now[0])++ t1, _ = store.issue("a", "u", "ag", ttl_seconds=10)+ t2, _ = store.issue("a", "u", "ag", ttl_seconds=600)++ fake_now[0] += 30 # t1 expired, t2 still alive++ # Issuing a new token implicitly purges; t1 should be gone afterward+ store.issue("a", "u", "ag", ttl_seconds=600)+ assert store.peek(t1) is None+ assert store.peek(t2) is not None+++def test_issue_handles_dense_alphabet_collisions(store, monkeypatch):+ """Force collisions to verify the retry loop still terminates."""+ import openviking.server.upload_token_store as mod++ call_count = [0]+ real_choice = mod.secrets.choice++ def fake_choice(seq):+ call_count[0] += 1+ if call_count[0] <= 42:+ return seq[0]+ return real_choice(seq)++ monkeypatch.setattr(mod.secrets, "choice", fake_choice)++ t1, _ = store.issue("a", "u", "ag", ttl_seconds=60)+ t2, _ = store.issue("a", "u", "ag", ttl_seconds=60)+ assert t1 != t2+++def test_clear_resets_state(store):+ store.issue("a", "u", "ag", ttl_seconds=60)+ store.clear()+ assert store._store == {}