Files
MoviePilot/app/agent/tools/projection.py
wenking 5ec9516a89 fix(mcp): 支持显式 opt-in 的 tools/list schema 紧凑投影
默认保留 MCP tools/list 的完整 schema;显式携带 X-MCP-Schema-Mode: compact 时,为超限工具提供保留顶层对象和 operation/action 枚举的紧凑投影。REST 合同、tools/call 校验与权限判定沿用完整合同。

合并前修复嵌套定义引用与 patternProperties 投影边界,使用 app.agent.tools.projection 作为纯函数 owner,补充回归和相关 Skill 说明,并同步当前 v3 的架构快照与类型低水位。

验证:113 项相关回归、167 项架构策略测试、45 项架构快照测试通过;Pylint 10/10,类型、复杂度及并发等相关棘轮通过。最终 PR head 6d25e1039d 的全部 10 项必需 GitHub 检查通过;待合并树与 CI 测试树一致。

投影是 best-effort,不承诺压入 5000 字节以内;未进行生产实例或镜像发布验证。

Co-authored-by: clone <clone_fan@foxmail.com>
2026-10-16 19:52:57 +08:00

193 lines
9.1 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""外部 MCP ``tools/list`` 的 schema 预算投影(显式 opt-in)。
主流 MCP 客户端会对工具 schema 做有损压缩。以 Codex 为例,规范化后超过 5000 字节的
schema 会依次执行「删除 description → 丢弃 ``$defs`` → 折叠深层复杂对象 → 移除组合
关键字」,其中 ``oneOf``/``anyOf``/``allOf`` 所在的节点会被整段替换为 ``{}``。
``moviepilot_api`` 等工具的完整合同远超该预算,且组合分支位于根节点,压缩后客户端
只会拿到一个没有 ``type`` 的空对象;严格校验的上游随后以
``schema must be a JSON Schema of 'type: "object"', got 'type: null'`` 拒绝整个请求,
使一次会话里所有工具调用都失败。
本模块提供显式 opt-in 的紧凑投影(``X-MCP-Schema-Mode: compact``):把序列化后超过
客户端压缩阈值的工具 schema 投影为顶层对象合同——保留 ``type``/``required`` 与顶层
属性(含 operation/action 枚举),去掉各级组合关键字、``$defs`` 与指向它们的失效
本地引用,并把引用已删除分支的说明改写为不依赖分支的直接描述(无法改写的整条移除)。
投影是 best-effort:它不承诺把结果压到阈值以内(``moviepilot_api`` 保留全部 231 个
operation 的枚举本身就约占 5 KB),而是保证根节点不再是组合节点,客户端的后续压缩
不会再把整份 schema 替换为空对象。逐 operation 的完整合同继续由
``GET /api/v1/mcp/tools/{tool_name}/schema`` 与调用失败回执提供,调用侧校验行为不变;
默认(``full``)模式不投影,保持既有完整合同。
"""
from __future__ import annotations
import json
from copy import deepcopy
from typing import Any, Mapping, Optional
from urllib.parse import unquote
# Codex 等客户端对工具 schema 触发逐级压缩的字节阈值;超过时 compact 模式才会投影。
MCP_CLIENT_SCHEMA_COMPACTION_BYTES = 5000
# 客户端压缩会把这些组合关键字所在节点整段替换为空对象,投影时提前删除。
COMPOSITION_KEYWORDS = ("oneOf", "anyOf", "allOf")
# 定义表在客户端压缩中会被丢弃,投影时不再保留无法解析的本地引用。
DEFINITION_KEYWORDS = ("$defs", "definitions")
# 投影会删除的关键字:指向它们的本地引用在投影后无法解析,必须一并去掉。
PROJECTED_KEYWORDS = (*COMPOSITION_KEYWORDS, *DEFINITION_KEYWORDS)
# 本地引用关键字;与 PROJECTED_KEYWORDS 组合判断指针是否已经失效。
REFERENCE_KEYWORDS = ("$ref", "$dynamicRef")
# 只遍历 schema 位置,避免把属性名、默认值或枚举中的同名业务字段当作关键字。
SCHEMA_MAPPING_KEYWORDS = {"properties", "patternProperties", "dependentSchemas", "dependencies"}
SCHEMA_VALUE_KEYWORDS = {
"items", "prefixItems", "additionalItems", "additionalProperties",
}
# 投影标记:客户端与测试据此识别本次返回的是紧凑投影而非完整合同。
PROJECTION_MARKER = "x-moviepilot-schema-projection"
# 投影会删除根级组合分支,引用这些分支的说明必须同步改写为直接描述。
DESCRIPTION_REWRITES = {
"Select the oneOf branch matching operation_id and send exactly its documented fields. "
"Collection branches also describe their additive output metadata in x-moviepilot-collection.": (
"Select the operation_id and send exactly that operation's documented fields. "
"Collection operations also describe their additive output metadata in "
"x-moviepilot-collection."
),
"Exact allowlisted MoviePilot operation ID selecting this oneOf branch.": (
"Exact allowlisted MoviePilot operation ID."
),
"Resource identities inserted only into the selected operation's fixed route placeholders. "
"Use the exact names and types in its oneOf branch.": (
"Resource identities inserted only into the selected operation's fixed route placeholders; "
"exact names and types are defined by the selected operation."
),
"Filters and control values sent in the query string. "
"Use the exact names, types, defaults, and enums in the selected operation's oneOf branch.": (
"Filters and control values sent in the query string; exact names, types, defaults and "
"enums are defined by the selected operation."
),
"Request value for the selected operation. Match the exact operation oneOf branch; "
"scalar and object request bodies are not interchangeable.": (
"Request value for the selected operation; scalar and object request bodies are not "
"interchangeable."
),
}
def serialized_schema_bytes(schema: Any) -> int:
"""返回 schema 紧凑序列化后的字节数;无法序列化时按超出阈值处理。"""
try:
payload = json.dumps(schema, ensure_ascii=False, separators=(",", ":"), sort_keys=True)
except (TypeError, ValueError):
return MCP_CLIENT_SCHEMA_COMPACTION_BYTES + 1
return len(payload.encode("utf-8"))
def schema_within_client_budget(schema: Any) -> bool:
"""判断 schema 是否在客户端压缩阈值以内。"""
return serialized_schema_bytes(schema) <= MCP_CLIENT_SCHEMA_COMPACTION_BYTES
def _rewrite_description(description: str) -> Optional[str]:
"""改写引用已删除组合分支的说明;无法改写的引用直接移除。"""
rewrite = DESCRIPTION_REWRITES.get(description)
if rewrite is not None:
return rewrite
if any(keyword in description for keyword in COMPOSITION_KEYWORDS):
return None
return description
def _targets_projected_keyword(pointer: Any, removed_paths: set[tuple[str, ...]]) -> bool:
"""按实际删除位置识别失效 JSON Pointer,同时保留名称恰好为关键字的属性引用。"""
if not isinstance(pointer, str) or not pointer.startswith("#/"):
return False
parts = tuple(part.replace("~1", "/").replace("~0", "~") for part in unquote(pointer[2:]).split("/"))
return any(parts[:length] in removed_paths for length in range(1, len(parts) + 1))
def _project_schema_node(
node: Any,
path: tuple[str, ...],
removed_paths: set[tuple[str, ...]],
references: list[tuple[dict[str, Any], str, Any]],
) -> Any:
"""只递归 schema 位置,并记录删除位置及引用,供整棵投影完成后清理前向引用。"""
if isinstance(node, list):
return [
_project_schema_node(item, (*path, str(index)), removed_paths, references)
for index, item in enumerate(node)
]
if not isinstance(node, Mapping):
return deepcopy(node)
projected: dict[str, Any] = {}
for key, value in node.items():
if not isinstance(key, str):
continue
child_path = (*path, key)
if key in PROJECTED_KEYWORDS:
removed_paths.add(child_path)
continue
if key == "description" and isinstance(value, str):
rewritten = _rewrite_description(value)
if rewritten is not None:
projected[key] = rewritten
continue
if key in REFERENCE_KEYWORDS:
references.append((projected, key, value))
if key in SCHEMA_MAPPING_KEYWORDS and isinstance(value, Mapping):
projected[key] = {
name: _project_schema_node(prop, (*child_path, name), removed_paths, references)
for name, prop in value.items()
if isinstance(name, str)
}
elif key in SCHEMA_VALUE_KEYWORDS:
projected[key] = _project_schema_node(value, child_path, removed_paths, references)
else:
projected[key] = deepcopy(value)
return projected
def project_schema_for_budget(schema: Mapping[str, Any]) -> dict[str, Any]:
"""把超出客户端阈值的 schema 投影为顶层对象合同。"""
removed_paths: set[tuple[str, ...]] = {(key,) for key in PROJECTED_KEYWORDS}
references: list[tuple[dict[str, Any], str, Any]] = []
projected = _project_schema_node(schema, (), removed_paths, references)
for node, key, pointer in references:
if _targets_projected_keyword(pointer, removed_paths):
del node[key]
if not isinstance(projected, dict): # pragma: no cover - 调用方已保证是对象
projected = {}
projected.setdefault("type", "object")
projected[PROJECTION_MARKER] = {
"mode": "compact",
"reason": "client schema compaction replaces composition keywords with an empty schema",
"full_schema_endpoint": "/api/v1/mcp/tools/{tool_name}/schema",
}
return projected
def project_tool_schema(schema: Any) -> tuple[Any, bool]:
"""按客户端压缩阈值返回 ``(schema, 是否投影)``;阈值内 schema 原样返回。"""
if not isinstance(schema, Mapping) or schema_within_client_budget(schema):
return schema, False
return project_schema_for_budget(schema), True
__all__ = [
"COMPOSITION_KEYWORDS",
"DEFINITION_KEYWORDS",
"DESCRIPTION_REWRITES",
"MCP_CLIENT_SCHEMA_COMPACTION_BYTES",
"PROJECTION_MARKER",
"project_schema_for_budget",
"project_tool_schema",
"schema_within_client_budget",
"serialized_schema_bytes",
]