@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.
- package/README.md +3 -3
- package/package.json +2 -1
- package/pyproject.toml +2 -1
- package/skills/qingflow-cli/SKILL.md +8 -2
- package/src/qingflow_mcp/cli/formatters.py +11 -0
- package/src/qingflow_mcp/cli/main.py +90 -2
- package/src/qingflow_mcp/cli/permission_gate.py +59 -0
- package/src/qingflow_mcp/cloud_context.py +16 -1
- package/src/qingflow_mcp/entity_permissions.py +10 -0
- package/src/qingflow_mcp/permission_catalog.json +1210 -0
- package/src/qingflow_mcp/public_surface.py +67 -8
- package/src/qingflow_mcp/server.py +12 -6
- package/src/qingflow_mcp/server_app_builder.py +9 -5
- package/src/qingflow_mcp/server_app_user.py +9 -5
- package/src/qingflow_mcp/server_cloud.py +43 -7
- package/src/qingflow_mcp/tool_catalog.py +388 -0
- package/src/qingflow_mcp/tool_catalog_i18n.py +184 -0
- package/src/qingflow_mcp/tool_policy.py +191 -0
|
@@ -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
|