Skip to content

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

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.md
index 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 refused
diff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.md
index 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.py
index 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_service
from openviking.server.error_mapping import map_exception
from openviking.server.identity import AuthMode, Role
from 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 middleware
app.add_middleware(
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 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 enabled
api_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 = 600
temp_upload: TempUploadConfig = Field(default_factory=TempUploadConfig)
model_config = {"extra": "forbid"}
diff --git a/openviking/server/dependencies.py b/openviking/server/dependencies.py
index 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, Optional
from openviking.service.core import OpenVikingService
+if TYPE_CHECKING:
+ from openviking.server.config import ServerConfig
+
_service: Optional[OpenVikingService] = None
+_server_config: Optional["ServerConfig"] = None
def 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 = config
diff --git a/openviking/server/local_input_guard.py b/openviking/server/local_input_guard.py
index 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.py
index 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 annotations
import contextvars
+import os
from contextlib import asynccontextmanager
+from datetime import datetime, timezone
from typing import List, Literal, Optional
+from urllib.parse import quote
from mcp.server.fastmcp import FastMCP
from mcp.server.transport_security import TransportSecuritySettings
@@ -27,8 +30,14 @@ from starlette.responses import JSONResponse
from starlette.types import ASGIApp, Receive, Scope, Send
from openviking.server.auth import resolve_identity
-from openviking.server.dependencies import get_service
+from openviking.server.dependencies import get_server_config, get_service
from 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_store
from 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_source
service = 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_uri
else 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.py
index 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, UploadFile
from pydantic import BaseModel, ConfigDict, model_validator
from openviking.core.path_variables import resolve_path_variables
from openviking.server.auth import get_request_context
from 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_source
from openviking.server.responses import response_from_result
from openviking.server.telemetry import run_operation
from openviking.server.temp_upload_store import TempUploadStore
+from openviking.server.upload_token_store import UploadTokenError, upload_token_store
from openviking.telemetry import TelemetryRequest
from openviking_cli.exceptions import InvalidArgumentError
+from openviking_cli.session.user_id import UserIdentifier
router = 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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 == {}