agent_graph_mcp/
tools.rs

1//! Tool parameter structs for agent-graph MCP tools.
2//! Each struct derives schemars::JsonSchema so rmcp auto-generates
3//! the JSON Schema for the tool's inputSchema.
4
5use schemars::JsonSchema;
6use serde::{Deserialize, Serialize};
7use serde_json::Value;
8
9// ─── Shared typed enums ────────────────────────────────────────────────
10
11/// Valid approval decisions.
12#[derive(Debug, Clone, Deserialize, JsonSchema)]
13#[serde(rename_all = "snake_case")]
14pub enum ApprovalDecision {
15    Approve,
16    Reject,
17    RequestChanges,
18    Escalate,
19}
20
21/// Valid render formats for graph visualization.
22#[derive(Debug, Clone, Deserialize, JsonSchema)]
23#[serde(rename_all = "snake_case")]
24pub enum RenderFormat {
25    Mermaid,
26    Json,
27}
28
29// ─── Graph lifecycle ──────────────────────────────────────────────────
30
31/// Parameters for creating, validating, or deleting a graph.
32#[derive(Debug, Deserialize, JsonSchema)]
33pub struct GraphCreateParams {
34    /// JSON graph specification. Required for 'create' and 'validate' actions.
35    #[serde(default)]
36    pub spec: Option<Value>,
37    /// Action: 'create' (register graph), 'validate' (validate without registering), 'delete' (remove graph).
38    #[serde(default)]
39    pub action: Option<String>,
40    /// Graph ID (name) — used for delete action.
41    #[serde(default)]
42    pub graph_id: Option<String>,
43    /// Optional idempotency key. Reusing a key returns the existing result.
44    #[serde(default)]
45    pub idempotency_key: Option<String>,
46    /// Template instantiation: { "id": "council", "name": "my-council" }
47    #[serde(default)]
48    pub template: Option<Value>,
49    /// When true, overwrite an existing graph with the same name.
50    #[serde(default)]
51    pub overwrite: Option<bool>,
52}
53
54/// Parameters for listing registered graphs.
55#[derive(Debug, Deserialize, JsonSchema)]
56pub struct GraphListParams {
57    /// Optional filter: only show graphs whose name contains this string.
58    #[serde(default)]
59    pub query: Option<String>,
60    /// Maximum number of graphs to return (default 50).
61    #[serde(default)]
62    pub limit: Option<u32>,
63}
64
65/// Parameters for getting a specific graph's details.
66#[derive(Debug, Deserialize, JsonSchema)]
67pub struct GraphInspectParams {
68    /// The graph ID (name) to inspect.
69    pub graph_id: String,
70}
71
72/// Read-only durable lifecycle inventory. Existing graphs without a record appear as `unclassified`.
73#[derive(Debug, Deserialize, JsonSchema)]
74pub struct GraphRetentionReviewParams {
75    /// Restrict the report to a specific graph ID.
76    #[serde(default)]
77    pub graph_id: Option<String>,
78    /// Optional lifecycle-state filter.
79    #[serde(default)]
80    pub state: Option<String>,
81    /// Maximum report entries (default 100, maximum 256).
82    #[serde(default)]
83    pub limit: Option<u32>,
84}
85
86/// Set one explicit lifecycle state. Deletion requires delete_candidate followed by delete_approved.
87#[derive(Debug, Deserialize, JsonSchema)]
88pub struct GraphRetentionSetParams {
89    /// Graph ID to classify.
90    pub graph_id: String,
91    /// One of active, pinned, archived, delete_candidate, or delete_approved.
92    pub state: String,
93    /// Why this lifecycle transition is appropriate.
94    pub reason: String,
95    /// Operator or service principal recording the decision.
96    pub actor: String,
97    /// Optional ISO-8601 review deadline.
98    #[serde(default)]
99    pub review_after: Option<String>,
100}
101
102/// Parameters for deleting a graph.
103#[derive(Debug, Deserialize, JsonSchema)]
104pub struct GraphDeleteParams {
105    /// The graph ID (name) to delete.
106    pub graph_id: String,
107}
108
109// ─── Execution ────────────────────────────────────────────────────────
110
111/// Parameters for executing a graph.
112#[derive(Debug, Deserialize, JsonSchema)]
113pub struct GraphExecuteParams {
114    /// The graph ID (name) to execute.
115    pub graph_id: String,
116    /// Input value to pass to the graph's entry node.
117    #[serde(default)]
118    pub input: Option<Value>,
119    /// Optional pinned graph version hash.
120    #[serde(default)]
121    pub graph_version: Option<String>,
122    /// Optional thread ID for checkpointing (future use).
123    #[serde(default)]
124    pub thread_id: Option<String>,
125    /// Execution mode: 'sync' blocks until completion, 'async' returns immediately.
126    #[serde(default)]
127    pub mode: Option<String>,
128    /// Optional idempotency key. Reusing a key returns the existing run result.
129    #[serde(default)]
130    pub idempotency_key: Option<String>,
131}
132
133// ─── Status ───────────────────────────────────────────────────────────
134
135/// Parameters for querying server or execution status.
136#[derive(Debug, Deserialize, JsonSchema)]
137pub struct GraphStatusParams {
138    /// Resource type: 'server', 'graph', 'run', 'events', 'receipt', 'templates'.
139    /// Omit for server-level summary.
140    #[serde(default)]
141    pub resource: Option<String>,
142    /// Graph ID (required when resource='graph').
143    #[serde(default)]
144    pub graph_id: Option<String>,
145    /// Run ID (required when resource='run', 'events', or 'receipt').
146    #[serde(default)]
147    pub run_id: Option<String>,
148    /// Event cursor (for resource='events', start from this sequence number).
149    #[serde(default)]
150    pub cursor: Option<u64>,
151    /// Maximum events to return (for resource='events', default 100).
152    #[serde(default)]
153    pub limit: Option<u64>,
154}
155
156// ─── Structured output ────────────────────────────────────────────────
157
158/// Standard response envelope for all tools.
159#[derive(Debug, Serialize, Deserialize, JsonSchema)]
160pub struct StructuredOutput {
161    /// Whether the operation succeeded.
162    pub ok: bool,
163    /// Human-readable status.
164    #[serde(default)]
165    pub status: Option<String>,
166    /// Primary response data.
167    #[serde(default)]
168    pub data: Option<Value>,
169    /// Error message (only present when ok=false).
170    #[serde(default)]
171    pub error: Option<String>,
172    /// Stable error code (when applicable).
173    #[serde(default)]
174    pub error_code: Option<String>,
175    /// Graph ID (when applicable).
176    #[serde(default)]
177    pub graph_id: Option<String>,
178    /// Graph version / digest.
179    #[serde(default)]
180    pub graph_version: Option<String>,
181    /// Run ID (when applicable).
182    #[serde(default)]
183    pub run_id: Option<String>,
184}
185
186// ─── Approval lifecycle ────────────────────────────────────────────────
187
188#[derive(Debug, Deserialize, JsonSchema)]
189#[serde(deny_unknown_fields)]
190pub struct ApprovalRequestParams {
191    /// The immutable deterministic-local checkpoint to which this approval is bound.
192    pub checkpoint_id: String,
193    /// Human audience label; this is metadata and grants no execution authority.
194    pub audience: String,
195    /// Approval prompt. It is stored only as a digest and is never returned by approval reads.
196    pub prompt: String,
197    /// Non-empty subset of `approve` and `reject`.
198    pub allowed_decisions: Vec<String>,
199    /// RFC3339 expiration timestamp.
200    pub expiration: String,
201}
202
203#[derive(Debug, Deserialize, JsonSchema)]
204pub struct ApprovalListParams {
205    #[serde(default)]
206    pub run_id: Option<String>,
207    #[serde(default)]
208    pub status: Option<String>,
209    #[serde(default)]
210    pub limit: Option<u32>,
211}
212
213#[derive(Debug, Deserialize, JsonSchema)]
214pub struct ApprovalGetParams {
215    pub approval_id: String,
216}
217
218#[derive(Debug, Deserialize, JsonSchema)]
219pub struct ApprovalDecideParams {
220    pub approval_id: String,
221    pub decision: String,
222    /// Caller-provided label is metadata only; it is never an authority identity.
223    #[serde(alias = "actor")]
224    pub claimed_actor_label: String,
225}
226
227// ─── Async run lifecycle ───────────────────────────────────────────────
228
229#[derive(Debug, Deserialize, JsonSchema)]
230pub struct RunStartParams {
231    pub graph_id: String,
232    #[serde(default)]
233    pub input: Option<Value>,
234    #[serde(default)]
235    pub graph_version: Option<String>,
236    #[serde(default)]
237    pub thread_id: Option<String>,
238    #[serde(default)]
239    pub idempotency_key: Option<String>,
240    #[serde(default)]
241    pub budgets: Option<Value>,
242    /// When true, persist an intentional deterministic pre-execution checkpoint
243    /// and leave the run paused until graph_run_resume consumes it.
244    #[serde(default)]
245    pub checkpoint: Option<bool>,
246}
247
248#[derive(Debug, Deserialize, JsonSchema)]
249pub struct RunWaitParams {
250    pub run_id: String,
251    #[serde(default)]
252    pub timeout_ms: Option<u64>,
253}
254
255#[derive(Debug, Deserialize, JsonSchema)]
256pub struct RunCancelParams {
257    pub run_id: String,
258    #[serde(default)]
259    pub reason: Option<String>,
260}
261
262#[derive(Debug, Deserialize, JsonSchema)]
263pub struct RunGetParams {
264    pub run_id: String,
265}
266
267#[derive(Debug, Deserialize, JsonSchema)]
268pub struct RunStateParams {
269    pub run_id: String,
270    #[serde(default)]
271    pub checkpoint_id: Option<String>,
272    #[serde(default)]
273    pub json_pointer: Option<String>,
274}
275
276#[derive(Debug, Deserialize, JsonSchema)]
277pub struct RunEventsParams {
278    pub run_id: String,
279    #[serde(default)]
280    pub cursor: Option<u64>,
281    #[serde(default)]
282    pub limit: Option<u64>,
283}
284
285#[derive(Debug, Deserialize, JsonSchema)]
286pub struct RunReceiptParams {
287    pub run_id: String,
288}
289
290#[derive(Debug, Deserialize, JsonSchema)]
291pub struct RunCheckpointParams {
292    #[serde(default)]
293    pub run_id: Option<String>,
294    #[serde(default)]
295    pub checkpoint_id: Option<String>,
296}
297
298#[derive(Debug, Deserialize, JsonSchema)]
299pub struct RunResumeParams {
300    #[serde(default)]
301    pub checkpoint_id: Option<String>,
302    #[serde(default)]
303    pub run_id: Option<String>,
304}
305
306// ─── Local source witnesses ──────────────────────────────────────────
307
308/// Caller-supplied local capture. This endpoint never dereferences the locator.
309#[derive(Debug, Deserialize, JsonSchema)]
310#[serde(deny_unknown_fields)]
311pub struct WitnessCaptureParams {
312    pub locator: String,
313    pub content: String,
314    pub media_type: String,
315    pub authority_class: String,
316    #[serde(default)]
317    pub retrieved_at: Option<String>,
318}
319
320#[derive(Debug, Deserialize, JsonSchema)]
321#[serde(deny_unknown_fields)]
322pub struct WitnessGetParams {
323    pub witness_id: String,
324}
325
326// ─── Policy + render ───────────────────────────────────────────────────
327
328#[derive(Debug, Deserialize, JsonSchema)]
329pub struct PolicyCheckParams {
330    pub graph_id: String,
331    #[serde(default)]
332    pub input: Option<Value>,
333}
334
335#[derive(Debug, Deserialize, JsonSchema)]
336pub struct RenderParams {
337    pub graph_id: String,
338    #[serde(default)]
339    pub format: Option<String>,
340}
341
342// ─── Templates ─────────────────────────────────────────────────────────
343
344#[derive(Debug, Deserialize, JsonSchema)]
345pub struct TemplateListParams {
346    #[serde(default)]
347    pub query: Option<String>,
348}
349
350#[derive(Debug, Deserialize, JsonSchema)]
351pub struct TemplateInstantiateParams {
352    pub template_id: String,
353    pub name: String,
354}
355
356#[derive(Debug, Deserialize, JsonSchema)]
357pub struct TemplateCandidatesParams {
358    #[serde(default)]
359    pub state: Option<String>,
360}
361
362#[derive(Debug, Deserialize, JsonSchema)]
363pub struct TemplateOutcomesParams {
364    pub template_id: String,
365}
agent_graph_mcp/tools.rs

agent_graph_mcp/
tools.rs
