refactor: Enforce strict typed JsonSchema for all MCP tools

server/src/tools.rs

@@ -1,276 +1,516 @@
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+/// Create new entities in the knowledge graph.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CreateEntitiesTool {
-    pub entities: Vec<serde_json::Value>,
+    /// Array of entities to create.
+    pub entities: Vec<crate::models::Entity>,
 }
+
+/// Create new relations between entities in the knowledge graph.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct CreateRelationsTool {
-    pub relations: Vec<serde_json::Value>,
+    /// Array of relations to create.
+    pub relations: Vec<crate::models::Relation>,
 }
+
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ObservationInput {
+    #[serde(rename = "entityName")]
+    pub entity_name: String,
+    pub contents: Vec<String>,
+}
+
+/// Add new observations to existing entities in the knowledge graph.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddObservationsTool {
-    pub observations: Vec<serde_json::Value>,
+    /// Array of observations to add.
+    pub observations: Vec<ObservationInput>,
 }
+
+/// Delete entities from the knowledge graph.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct DeleteEntitiesTool {
+    /// Array of entity names to delete.
     #[serde(rename = "entityNames")]
     pub entity_names: Vec<String>,
 }
+
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct DeleteObservationsTool {
-    pub deletions: Vec<serde_json::Value>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct DeleteRelationsTool {
-    pub relations: Vec<serde_json::Value>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct ReadGraphTool {
-    pub namespace: Option<String>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct SearchNodesTool {
-    pub query: String,
-    pub namespace: Option<String>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct OpenNodesTool {
-    pub names: Vec<String>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct LogCodeChangeTool {
-    #[serde(rename = "filePath")]
-    pub file_path: String,
-    pub description: String,
-    pub git_commit: Option<String>,
-    pub git_branch: Option<String>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct QueryRecentChangesTool {}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct VisualizeGraphTool {
-    pub query: Option<String>,
-    pub namespace: Option<String>,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct AddStickyNoteTool {
-    pub content: String,
-}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct ReadStickyNotesTool {}
-#[derive(Debug, Deserialize, Serialize, JsonSchema)]
-pub struct CondenseEntityTool {
+pub struct DeleteObservationInput {
     #[serde(rename = "entityName")]
     pub entity_name: String,
+    pub observations: Vec<String>,
+}
+
+/// Delete observations from existing entities.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct DeleteObservationsTool {
+    /// Array of observation deletions.
+    pub deletions: Vec<DeleteObservationInput>,
+}
+
+/// Delete relations between entities.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct DeleteRelationsTool {
+    /// Array of relations to delete.
+    pub relations: Vec<crate::models::Relation>,
+}
+
+/// Read the entire knowledge graph.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ReadGraphTool {
+    /// Optional namespace to restrict the read to.
+    pub namespace: Option<String>,
+}
+
+/// Search for entities in the knowledge graph by name or type.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct SearchNodesTool {
+    /// The search query.
+    pub query: String,
+    /// Optional namespace to restrict the search to.
+    pub namespace: Option<String>,
+}
+
+/// Open and retrieve full details of specific nodes in the knowledge graph.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct OpenNodesTool {
+    /// Array of entity names to open.
+    pub names: Vec<String>,
+}
+
+/// Log a significant code change or refactor in the memory system.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct LogCodeChangeTool {
+    /// The path of the file that was changed.
+    #[serde(rename = "filePath")]
+    pub file_path: String,
+    /// A description of the change.
+    pub description: String,
+    /// The associated git commit hash, if any.
+    pub git_commit: Option<String>,
+    /// The associated git branch, if any.
+    pub git_branch: Option<String>,
+}
+
+/// Query recently logged code changes.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct QueryRecentChangesTool {}
+
+/// Generate a visual representation of the knowledge graph.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct VisualizeGraphTool {
+    /// Optional search query to filter the graph before visualization.
+    pub query: Option<String>,
+    /// Optional namespace to restrict the visualization to.
+    pub namespace: Option<String>,
+}
+
+/// Add a sticky note for unstructured thoughts or reminders.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct AddStickyNoteTool {
+    /// The content of the sticky note.
+    pub content: String,
+}
+
+/// Read all active sticky notes.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct ReadStickyNotesTool {}
+
+/// Condense or summarize an entity's observations to reduce size.
+#[derive(Debug, Deserialize, Serialize, JsonSchema)]
+pub struct CondenseEntityTool {
+    /// The name of the entity to condense.
+    #[serde(rename = "entityName")]
+    pub entity_name: String,
+    /// The condensed observations that will replace the existing ones.
     pub summarized_observations: Vec<String>,
 }
+
+/// Add a new task to the task tracker.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddTaskTool {
+    /// The title of the task.
     pub title: String,
+    /// A detailed description of the task.
     pub description: String,
+    /// The associated git branch, if any.
     pub git_branch: Option<String>,
 }
+
+/// Update the status of an existing task.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct UpdateTaskStatusTool {
+    /// The ID of the task to update.
     pub id: String,
+    /// The new status of the task (e.g., 'pending' or 'completed').
+    #[schemars(description = "Must be 'pending' or 'completed'")]
     pub status: String,
 }
+
+/// List all currently active tasks.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ListActiveTasksTool {
+    /// Optional git branch to filter tasks by.
     pub git_branch: Option<String>,
 }
+
+/// Store a reusable code snippet.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct StoreSnippetTool {
+    /// The name of the snippet.
     pub name: String,
+    /// The programming language of the snippet.
     pub language: String,
+    /// The code snippet content.
     pub code: String,
+    /// A description of what the snippet does.
     pub description: String,
 }
+
+/// Search through stored code snippets.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SearchSnippetsTool {
+    /// The search query.
     pub query: String,
 }
+
+/// Delete a stored code snippet.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct DeleteSnippetTool {
+    /// The name of the snippet to delete.
     pub name: String,
 }
+
+/// Log an architectural decision record (ADR).
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LogDecisionTool {
+    /// The title of the decision.
     pub title: String,
+    /// The context or problem requiring a decision.
     pub context: String,
+    /// The decision made.
     pub decision: String,
+    /// The consequence of the decision.
     pub consequence: String,
 }
+
+/// Query architectural decision records.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct QueryDecisionsTool {
+    /// Optional search query.
     pub query: Option<String>,
 }
+
+/// Merge two entities in the knowledge graph into one.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct MergeEntitiesTool {
+    /// The name of the entity to merge from (will be deleted).
     #[serde(rename = "sourceEntity")]
     pub source_entity: String,
+    /// The name of the entity to merge into.
     #[serde(rename = "targetEntity")]
     pub target_entity: String,
 }
+
+/// Find orphaned entities (entities without any relations) in the graph.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct FindOrphansTool {}
+
+/// Record a user preference or behavior to adapt future interactions.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LearnPreferenceTool {
+    /// The key for the preference.
     pub key: String,
+    /// The value of the preference.
     pub value: String,
 }
+
+/// Read all learned user preferences.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ReadPreferencesTool {}
+
+/// Log a complex error and its fix for future reference.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LogErrorFixTool {
+    /// The error signature or stack trace.
     pub signature: String,
+    /// The solution applied to fix the error.
     pub solution: String,
+    /// The associated git commit hash, if any.
     pub git_commit: Option<String>,
+    /// The associated git branch, if any.
     pub git_branch: Option<String>,
 }
+
+/// Search through previously logged error fixes.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SearchErrorFixesTool {
+    /// The search query.
     pub query: String,
 }
+
+/// Pin a file to keep it explicitly in the context workspace.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct PinFileTool {
+    /// The namespace to pin the file in.
     pub namespace: String,
+    /// The absolute path of the file to pin.
     pub file_path: String,
+    /// The associated git branch, if any.
     pub git_branch: Option<String>,
 }
+
+/// Unpin a file from the context workspace.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct UnpinFileTool {
+    /// The namespace the file is pinned in.
     pub namespace: String,
+    /// The absolute path of the file to unpin.
     pub file_path: String,
 }
+
+/// List all currently pinned files.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ListPinnedFilesTool {
+    /// Optional namespace to filter by.
     pub namespace: Option<String>,
+    /// Optional git branch to filter by.
     pub git_branch: Option<String>,
 }
+
+/// Add a summary of the current session.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddSessionSummaryTool {
+    /// The summary content.
     pub summary: String,
+    /// The namespace to add the summary to.
     pub namespace: String,
 }
+
+/// Get a timeline of major project events.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct GetProjectTimelineTool {
+    /// Optional namespace to restrict the timeline to.
     pub namespace: Option<String>,
 }
+
+/// Leave a memo for the next session or agent.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LeaveHandoffMemoTool {
+    /// The content of the memo.
     pub content: String,
+    /// The namespace to leave the memo in.
     pub namespace: String,
 }
+
+/// Read pending handoff memos.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ReadHandoffMemosTool {
+    /// Optional namespace to restrict the read to.
     pub namespace: Option<String>,
 }
+
+/// Clear handoff memos after reading.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ClearHandoffMemosTool {
+    /// Array of memo IDs to clear.
     pub ids: Vec<String>,
 }
+
+/// Update the environment fingerprint (e.g., OS, tool versions).
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct UpdateEnvFingerprintTool {
+    /// The namespace to update the fingerprint for.
     pub namespace: String,
+    /// A map of tool names to their versions.
     pub tool_versions: std::collections::HashMap<String, String>,
 }
+
+/// Read the environment fingerprint.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ReadEnvFingerprintTool {
+    /// The namespace to read the fingerprint for.
     pub namespace: String,
 }
+
+/// Log a required environment variable or configuration.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LogEnvRequirementTool {
+    /// The namespace.
     pub namespace: String,
+    /// The environment variable key (e.g., DATABASE_URL).
     pub key: String,
+    /// A description of what the variable is used for.
     pub description: String,
+    /// Whether the variable contains a secret.
     pub is_secret: bool,
 }
+
+/// Add a new milestone.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddMilestoneTool {
+    /// The title of the milestone.
     pub title: String,
+    /// The namespace for the milestone.
     pub namespace: String,
 }
+
+/// Update the status of a milestone.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct UpdateMilestoneTool {
+    /// The ID of the milestone to update.
     pub id: String,
+    /// The new status (e.g., 'active', 'completed').
     pub status: String,
 }
+
+/// List all milestones.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ListMilestonesTool {
+    /// Optional namespace to restrict the list to.
     pub namespace: Option<String>,
 }
+
+/// Generate a standup report for a specific time window.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct GenerateStandupReportTool {
+    /// The namespace to generate the report for.
     pub namespace: String,
+    /// The number of hours to look back for activity.
     pub hours_lookback: u64,
 }
+
+/// Register a new infrastructure environment.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct RegisterEnvironmentTool {
+    /// The namespace.
     pub namespace: String,
+    /// The name of the environment (e.g., 'staging', 'prod').
     pub name: String,
+    /// The URL or connection string for the environment.
     pub url: String,
+    /// A description of the environment.
     pub description: String,
+    /// Whether a VPN is required to access the environment.
     pub requires_vpn: bool,
 }
+
+/// Get details about a registered environment.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct GetEnvironmentDetailsTool {
+    /// The namespace to retrieve details for.
     pub namespace: String,
 }
+
+/// Add an item to the PR checklist.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct AddPrChecklistItemTool {
+    /// The namespace.
     pub namespace: String,
+    /// The description of the checklist item.
     pub description: String,
 }
+
+/// Get the PR checklist.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct GetPrChecklistTool {
+    /// The namespace.
     pub namespace: String,
 }
+
+/// Clear the PR checklist.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ClearPrChecklistTool {
+    /// The namespace.
     pub namespace: String,
 }
+
+/// Log a technical debt record.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LogTechDebtTool {
+    /// The namespace.
     pub namespace: String,
+    /// A description of the technical debt.
     pub description: String,
+    /// The ideal solution to resolve the debt.
     pub ideal_solution: String,
+    /// The associated git commit hash, if any.
     pub git_commit: Option<String>,
+    /// The associated git branch, if any.
     pub git_branch: Option<String>,
 }
+
+/// Resolve a technical debt record.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ResolveTechDebtTool {
+    /// The ID of the technical debt record to resolve.
     pub id: String,
 }
+
+/// List technical debt records.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ListTechDebtTool {
+    /// The namespace.
     pub namespace: String,
+    /// Whether to include resolved technical debt in the results.
     pub include_resolved: bool,
 }
+
+/// Save the current context workspace.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct SaveContextWorkspaceTool {
+    /// The namespace for the workspace.
     pub namespace: String,
+    /// The name to save the workspace as.
     pub name: String,
+    /// Array of pinned file paths.
     pub pinned_files: Vec<String>,
+    /// Array of active task IDs.
     pub active_task_ids: Vec<String>,
 }
+
+/// Load a saved context workspace.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct LoadContextWorkspaceTool {
+    /// The namespace of the workspace.
     pub namespace: String,
+    /// The name of the workspace to load.
     pub name: String,
 }
+
+/// List all saved context workspaces.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct ListContextWorkspacesTool {
+    /// The namespace to list workspaces for.
     pub namespace: String,
 }
+
+/// Search across all memory stores (Graph, Tasks, Snippets, ADRs, etc.).
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct OmniSearchTool {
+    /// The search query.
     pub query: String,
+    /// Optional namespace to restrict the search to.
     pub namespace: Option<String>,
 }
+
+/// Get a health digest of the project.
 #[derive(Debug, Deserialize, Serialize, JsonSchema)]
 pub struct GetProjectHealthTool {
+    /// The namespace to get health for.
     pub namespace: String,
 }
+
+/// Traverse the knowledge graph to find a path between two entities.
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+pub struct QueryGraphPathTool {
+    /// The starting entity name.
+    pub start_node: String,
+    /// The ending entity name.
+    pub end_node: String,
+    /// Optional maximum depth to search.
+    pub max_depth: Option<u32>,
+}