@qingflow-tech/qingflow-cli 1.1.62 → 1.1.63

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,191 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import os
5
+ from dataclasses import dataclass
6
+ from typing import Any, Literal, Mapping, Sequence
7
+ from urllib.parse import parse_qs
8
+
9
+ from mcp.server.fastmcp import FastMCP
10
+ from mcp.server.fastmcp.exceptions import ToolError
11
+
12
+ from .cloud_context import current_http_tool_policy, current_tool_policy_header
13
+ from .tool_catalog import TOOL_ID_PATTERN, require_registered_tool_id, tool_is_exempt
14
+
15
+
16
+ TOOL_POLICY_ENV = "QINGFLOW_TOOL_POLICY"
17
+ TOOL_POLICY_HEADER = "X-Qingflow-Tool-Policy"
18
+ TOOL_POLICY_INVALID = "TOOL_POLICY_INVALID"
19
+ TOOL_POLICY_DENIED = "TOOL_POLICY_DENIED"
20
+
21
+
22
+ @dataclass(frozen=True, slots=True)
23
+ class ToolPolicySnapshot:
24
+ mode: Literal["unrestricted", "restricted"]
25
+ allowed_tools: tuple[str, ...] = ()
26
+
27
+ def violation_for(self, stable_id: str) -> "ToolPolicyViolation | None":
28
+ # 基础恢复能力不受业务工具开关限制。
29
+ if tool_is_exempt(stable_id):
30
+ return None
31
+ if self.mode == "unrestricted":
32
+ return None
33
+ if stable_id in self.allowed_tools:
34
+ return None
35
+ return ToolPolicyViolation(TOOL_POLICY_DENIED, stable_id, "当前策略未允许该工具")
36
+
37
+
38
+ class ToolPolicyViolation(Exception):
39
+ def __init__(self, code: str, tool_id_value: str, message: str) -> None:
40
+ super().__init__(message)
41
+ self.code = code
42
+ self.tool_id = tool_id_value
43
+ self.message = message
44
+
45
+ def payload(self, *, camel_case: bool = False) -> dict[str, Any]:
46
+ if camel_case:
47
+ return {
48
+ "status": "failed",
49
+ "errorCode": self.code,
50
+ "message": self.message,
51
+ "toolId": self.tool_id,
52
+ }
53
+ return {
54
+ "status": "failed",
55
+ "error_code": self.code,
56
+ "message": self.message,
57
+ "toolId": self.tool_id,
58
+ }
59
+
60
+
61
+ def parse_tool_policy(value: str | Mapping[str, Any] | None) -> ToolPolicySnapshot:
62
+ """只解析工具开关;非法输入等同未配置,合法空数组仍为受限空清单。"""
63
+ if value is None:
64
+ return ToolPolicySnapshot("unrestricted")
65
+ payload: Any = value
66
+ if isinstance(value, str):
67
+ if value == "":
68
+ return ToolPolicySnapshot("unrestricted")
69
+ try:
70
+ payload = json.loads(value)
71
+ except json.JSONDecodeError:
72
+ return ToolPolicySnapshot("unrestricted")
73
+ if not isinstance(payload, Mapping):
74
+ return ToolPolicySnapshot("unrestricted")
75
+ if set(payload) != {"version", "allowed_tools"}:
76
+ return ToolPolicySnapshot("unrestricted")
77
+ if type(payload.get("version")) is not int or payload.get("version") != 1: # noqa: E721
78
+ return ToolPolicySnapshot("unrestricted")
79
+ allowed = payload.get("allowed_tools")
80
+ if not isinstance(allowed, list):
81
+ return ToolPolicySnapshot("unrestricted")
82
+ normalized: set[str] = set()
83
+ for stable_id in allowed:
84
+ if not isinstance(stable_id, str) or TOOL_ID_PATTERN.fullmatch(stable_id) is None:
85
+ return ToolPolicySnapshot("unrestricted")
86
+ normalized.add(stable_id)
87
+ return ToolPolicySnapshot("restricted", tuple(sorted(normalized)))
88
+
89
+
90
+ def parse_http_tool_policy(header: str | None, query_string: bytes) -> ToolPolicySnapshot:
91
+ # 请求头是显式配置,覆盖 URL 默认配置;非法显式配置也按未配置处理,不回落旧限制。
92
+ if header is not None:
93
+ return parse_tool_policy(header)
94
+ # 保留空值并在 URL 解码后检查重复,tools= 与缺省不能合并为同一种状态。
95
+ values = parse_qs(query_string.decode("latin1"), keep_blank_values=True).get("tools", [])
96
+ if len(values) > 1:
97
+ return ToolPolicySnapshot("unrestricted")
98
+ return parse_tool_policy(
99
+ {"version": 1, "allowed_tools": values[0].split(",") if values[0] else []}
100
+ if values else None
101
+ )
102
+
103
+
104
+ def read_current_tool_policy() -> ToolPolicySnapshot:
105
+ """只读取调用方传入的环境策略,不查询外部服务。"""
106
+ return parse_tool_policy(os.getenv(TOOL_POLICY_ENV))
107
+
108
+
109
+ class PolicyAwareFastMCP(FastMCP):
110
+ """MCP 列表与调用在 handler 边界分别读取当前工具开关。"""
111
+
112
+ def __init__(self, *args: Any, **kwargs: Any) -> None:
113
+ self._tool_policy_bindings: dict[str, str] | None = None
114
+ self._tool_policy_source: Literal["environment", "request"] = "environment"
115
+ super().__init__(*args, **kwargs)
116
+
117
+ def configure_tool_policy(
118
+ self,
119
+ bindings: Mapping[str, str],
120
+ *,
121
+ source: Literal["environment", "request"],
122
+ ) -> None:
123
+ registered = set(self._tool_manager._tools)
124
+ bound = set(bindings)
125
+ if registered != bound:
126
+ missing = sorted(registered - bound)
127
+ extra = sorted(bound - registered)
128
+ raise ValueError(f"工具策略绑定不完整: missing={missing}, extra={extra}")
129
+ for stable_id in bindings.values():
130
+ # 登记校验只依赖提供方稳定 ID,不依赖 Wingent-X 的产品分类。
131
+ require_registered_tool_id(stable_id)
132
+ self._tool_policy_bindings = dict(bindings)
133
+ self._tool_policy_source = source
134
+
135
+ @property
136
+ def tool_policy_bindings(self) -> dict[str, str]:
137
+ return dict(self._tool_policy_bindings or {})
138
+
139
+ async def list_tools(self): # type: ignore[no-untyped-def]
140
+ tools = await super().list_tools()
141
+ bindings = self._require_bindings()
142
+ snapshot = self._current_snapshot()
143
+ return [
144
+ tool
145
+ for tool in tools
146
+ if snapshot.violation_for(bindings[tool.name]) is None
147
+ ]
148
+
149
+ async def call_tool(self, name: str, arguments: dict[str, Any]) -> Sequence[Any] | dict[str, Any]:
150
+ bindings = self._require_bindings()
151
+ stable_id = bindings.get(name)
152
+ if stable_id is None:
153
+ raise ToolError(json.dumps(
154
+ {
155
+ "status": "failed",
156
+ "errorCode": TOOL_POLICY_INVALID,
157
+ "message": "工具未登记稳定 ID",
158
+ },
159
+ ensure_ascii=False,
160
+ ))
161
+ if tool_is_exempt(stable_id):
162
+ return await super().call_tool(name, arguments)
163
+ violation = self._current_snapshot().violation_for(stable_id)
164
+ if violation is not None:
165
+ raise ToolError(json.dumps(violation.payload(camel_case=True), ensure_ascii=False))
166
+ return await super().call_tool(name, arguments)
167
+
168
+ def _require_bindings(self) -> dict[str, str]:
169
+ if self._tool_policy_bindings is None:
170
+ raise RuntimeError("MCP 工具策略绑定尚未配置")
171
+ return self._tool_policy_bindings
172
+
173
+ def _current_snapshot(self) -> ToolPolicySnapshot:
174
+ if self._tool_policy_source == "request":
175
+ snapshot = current_http_tool_policy.get()
176
+ if snapshot is not None:
177
+ return snapshot
178
+ # 保留未经过 HTTP 入口的请求头上下文用法,绝不回退共享 env。
179
+ return parse_tool_policy(current_tool_policy_header.get())
180
+ # 长连接不冻结启动时的工具开关,每次列表或调用都读取当前配置。
181
+ return read_current_tool_policy()
182
+
183
+
184
+ def configure_tool_policy(
185
+ server: PolicyAwareFastMCP,
186
+ bindings: Mapping[str, str],
187
+ *,
188
+ source: Literal["environment", "request"],
189
+ ) -> PolicyAwareFastMCP:
190
+ server.configure_tool_policy(bindings, source=source)
191
+ return server