vigil_types/
tool.rs

1//! ToolDescriptor：MCP `tools/list` 得到的工具描述。
2//!
3//! 注意：**descriptor 内容默认不可信**。`description` / `annotations` 仅作为输入参考，
4//! 实际风险由 firewall 的 `EffectExtractor` 在 args 上重新推断（AGENTS.md §5）。
5
6use serde::{Deserialize, Serialize};
7
8/// MCP 工具描述符快照。
9#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
10pub struct ToolDescriptor {
11    /// 该工具所属 server。
12    pub server_id: String,
13    /// 工具名（upstream 原始名，未 namespaced）。
14    pub tool_name: String,
15    /// MCP 提供的 JSON schema。
16    pub schema_json: serde_json::Value,
17    /// 工具描述文本。
18    pub description: Option<String>,
19    /// MCP 规范中的 annotations（readOnlyHint 等）。
20    pub annotations: serde_json::Value,
21    /// descriptor 的规范化哈希（sha256(hex)）；I05 descriptor pinning 的唯一信任锚。
22    ///
23    /// 下游消费者应以此字段为权威,**不要**把其它字段(`description` / `annotations`)
24    /// 当作已审批的可信输入 —— 它们的内容只要发生任何变化,`descriptor_hash`
25    /// 就会改变,进而触发再审批。
26    pub descriptor_hash: String,
27    /// 首次见到的时间（Unix epoch 秒）。
28    pub first_seen_at: i64,
29    /// 若已审批：**对当前 `descriptor_hash` 的**审批时间（Unix epoch 秒）。
30    ///
31    /// 语义澄清(AGENTS.md §5):被审批的是"这一份 hash 所代表的 descriptor 快照",
32    /// 而非"本 server 提供的该工具永久可信"。descriptor 内容的任何漂移会让 hash 改变,
33    /// 下游必须把 `Some(_) && descriptor_hash == current` 作为唯一可信判据。
34    pub approved_at: Option<i64>,
35}
vigil_types/tool.rs

vigil_types/
tool.rs
