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/// Parameters for deleting a graph.
73#[derive(Debug, Deserialize, JsonSchema)]
74pub struct GraphDeleteParams {
75    /// The graph ID (name) to delete.
76    pub graph_id: String,
77}
78
79// ─── Execution ────────────────────────────────────────────────────────
80
81/// Parameters for executing a graph.
82#[derive(Debug, Deserialize, JsonSchema)]
83pub struct GraphExecuteParams {
84    /// The graph ID (name) to execute.
85    pub graph_id: String,
86    /// Input value to pass to the graph's entry node.
87    #[serde(default)]
88    pub input: Option<Value>,
89    /// Optional pinned graph version hash.
90    #[serde(default)]
91    pub graph_version: Option<String>,
92    /// Optional thread ID for checkpointing (future use).
93    #[serde(default)]
94    pub thread_id: Option<String>,
95    /// Execution mode: 'sync' blocks until completion, 'async' returns immediately.
96    #[serde(default)]
97    pub mode: Option<String>,
98    /// Optional idempotency key. Reusing a key returns the existing run result.
99    #[serde(default)]
100    pub idempotency_key: Option<String>,
101}
102
103// ─── Status ───────────────────────────────────────────────────────────
104
105/// Parameters for querying server or execution status.
106#[derive(Debug, Deserialize, JsonSchema)]
107pub struct GraphStatusParams {
108    /// Resource type: 'server', 'graph', 'run', 'events', 'receipt', 'templates'.
109    /// Omit for server-level summary.
110    #[serde(default)]
111    pub resource: Option<String>,
112    /// Graph ID (required when resource='graph').
113    #[serde(default)]
114    pub graph_id: Option<String>,
115    /// Run ID (required when resource='run', 'events', or 'receipt').
116    #[serde(default)]
117    pub run_id: Option<String>,
118    /// Event cursor (for resource='events', start from this sequence number).
119    #[serde(default)]
120    pub cursor: Option<u64>,
121    /// Maximum events to return (for resource='events', default 100).
122    #[serde(default)]
123    pub limit: Option<u64>,
124}
125
126// ─── Structured output ────────────────────────────────────────────────
127
128/// Standard response envelope for all tools.
129#[derive(Debug, Serialize, Deserialize, JsonSchema)]
130pub struct StructuredOutput {
131    /// Whether the operation succeeded.
132    pub ok: bool,
133    /// Human-readable status.
134    #[serde(default)]
135    pub status: Option<String>,
136    /// Primary response data.
137    #[serde(default)]
138    pub data: Option<Value>,
139    /// Error message (only present when ok=false).
140    #[serde(default)]
141    pub error: Option<String>,
142    /// Stable error code (when applicable).
143    #[serde(default)]
144    pub error_code: Option<String>,
145    /// Graph ID (when applicable).
146    #[serde(default)]
147    pub graph_id: Option<String>,
148    /// Graph version / digest.
149    #[serde(default)]
150    pub graph_version: Option<String>,
151    /// Run ID (when applicable).
152    #[serde(default)]
153    pub run_id: Option<String>,
154}
155
156// ─── Approval lifecycle ────────────────────────────────────────────────
157
158#[derive(Debug, Deserialize, JsonSchema)]
159#[serde(deny_unknown_fields)]
160pub struct ApprovalRequestParams {
161    /// The immutable deterministic-local checkpoint to which this approval is bound.
162    pub checkpoint_id: String,
163    /// Human audience label; this is metadata and grants no execution authority.
164    pub audience: String,
165    /// Approval prompt. It is stored only as a digest and is never returned by approval reads.
166    pub prompt: String,
167    /// Non-empty subset of `approve` and `reject`.
168    pub allowed_decisions: Vec<String>,
169    /// RFC3339 expiration timestamp.
170    pub expiration: String,
171}
172
173#[derive(Debug, Deserialize, JsonSchema)]
174pub struct ApprovalListParams {
175    #[serde(default)]
176    pub run_id: Option<String>,
177    #[serde(default)]
178    pub status: Option<String>,
179    #[serde(default)]
180    pub limit: Option<u32>,
181}
182
183#[derive(Debug, Deserialize, JsonSchema)]
184pub struct ApprovalGetParams {
185    pub approval_id: String,
186}
187
188#[derive(Debug, Deserialize, JsonSchema)]
189pub struct ApprovalDecideParams {
190    pub approval_id: String,
191    pub decision: String,
192    /// Caller-provided label is metadata only; it is never an authority identity.
193    #[serde(alias = "actor")]
194    pub claimed_actor_label: String,
195}
196
197// ─── Async run lifecycle ───────────────────────────────────────────────
198
199#[derive(Debug, Deserialize, JsonSchema)]
200pub struct RunStartParams {
201    pub graph_id: String,
202    #[serde(default)]
203    pub input: Option<Value>,
204    #[serde(default)]
205    pub graph_version: Option<String>,
206    #[serde(default)]
207    pub thread_id: Option<String>,
208    #[serde(default)]
209    pub idempotency_key: Option<String>,
210    #[serde(default)]
211    pub budgets: Option<Value>,
212    /// When true, persist an intentional deterministic pre-execution checkpoint
213    /// and leave the run paused until graph_run_resume consumes it.
214    #[serde(default)]
215    pub checkpoint: Option<bool>,
216}
217
218#[derive(Debug, Deserialize, JsonSchema)]
219pub struct RunWaitParams {
220    pub run_id: String,
221    #[serde(default)]
222    pub timeout_ms: Option<u64>,
223}
224
225#[derive(Debug, Deserialize, JsonSchema)]
226pub struct RunCancelParams {
227    pub run_id: String,
228    #[serde(default)]
229    pub reason: Option<String>,
230}
231
232#[derive(Debug, Deserialize, JsonSchema)]
233pub struct RunGetParams {
234    pub run_id: String,
235}
236
237#[derive(Debug, Deserialize, JsonSchema)]
238pub struct RunStateParams {
239    pub run_id: String,
240    #[serde(default)]
241    pub checkpoint_id: Option<String>,
242    #[serde(default)]
243    pub json_pointer: Option<String>,
244}
245
246#[derive(Debug, Deserialize, JsonSchema)]
247pub struct RunEventsParams {
248    pub run_id: String,
249    #[serde(default)]
250    pub cursor: Option<u64>,
251    #[serde(default)]
252    pub limit: Option<u64>,
253}
254
255#[derive(Debug, Deserialize, JsonSchema)]
256pub struct RunReceiptParams {
257    pub run_id: String,
258}
259
260#[derive(Debug, Deserialize, JsonSchema)]
261pub struct RunCheckpointParams {
262    #[serde(default)]
263    pub run_id: Option<String>,
264    #[serde(default)]
265    pub checkpoint_id: Option<String>,
266}
267
268#[derive(Debug, Deserialize, JsonSchema)]
269pub struct RunResumeParams {
270    #[serde(default)]
271    pub checkpoint_id: Option<String>,
272    #[serde(default)]
273    pub run_id: Option<String>,
274}
275
276// ─── Local source witnesses ──────────────────────────────────────────
277
278/// Caller-supplied local capture. This endpoint never dereferences the locator.
279#[derive(Debug, Deserialize, JsonSchema)]
280#[serde(deny_unknown_fields)]
281pub struct WitnessCaptureParams {
282    pub locator: String,
283    pub content: String,
284    pub media_type: String,
285    pub authority_class: String,
286    #[serde(default)]
287    pub retrieved_at: Option<String>,
288}
289
290#[derive(Debug, Deserialize, JsonSchema)]
291#[serde(deny_unknown_fields)]
292pub struct WitnessGetParams {
293    pub witness_id: String,
294}
295
296// ─── Policy + render ───────────────────────────────────────────────────
297
298#[derive(Debug, Deserialize, JsonSchema)]
299pub struct PolicyCheckParams {
300    pub graph_id: String,
301    #[serde(default)]
302    pub input: Option<Value>,
303}
304
305#[derive(Debug, Deserialize, JsonSchema)]
306pub struct RenderParams {
307    pub graph_id: String,
308    #[serde(default)]
309    pub format: Option<String>,
310}
311
312// ─── Templates ─────────────────────────────────────────────────────────
313
314#[derive(Debug, Deserialize, JsonSchema)]
315pub struct TemplateListParams {
316    #[serde(default)]
317    pub query: Option<String>,
318}
319
320#[derive(Debug, Deserialize, JsonSchema)]
321pub struct TemplateInstantiateParams {
322    pub template_id: String,
323    pub name: String,
324}
325
326#[derive(Debug, Deserialize, JsonSchema)]
327pub struct TemplateCandidatesParams {
328    #[serde(default)]
329    pub state: Option<String>,
330}
331
332#[derive(Debug, Deserialize, JsonSchema)]
333pub struct TemplateOutcomesParams {
334    pub template_id: String,
335}
agent_graph_mcp/tools.rs

agent_graph_mcp/
tools.rs
