handoff-mcp-server 0.1.0 → 0.3.0

package/src/mcp/handlers/refer.rs

@@ -0,0 +1,152 @@
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use chrono::Utc;
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::config::read_config;
+use crate::storage::expand_tilde;
+use crate::storage::referrals::{is_valid_referral_type, write_referral, ReferralData};
+use crate::storage::tasks::validate_priority;
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let source_project_dir = resolve_project_dir(arguments)?;
+
+    let source_handoff = source_project_dir.join(".handoff");
+    if !source_handoff.join("config.toml").exists() {
+        anyhow::bail!(
+            "Source project is not initialized: {}",
+            source_project_dir.display()
+        );
+    }
+
+    let source_config = read_config(&source_handoff.join("config.toml"))?;
+
+    let target_dir = resolve_target(arguments, &source_config.dashboard.scan_dirs)?;
+
+    let target_handoff = target_dir.join(".handoff");
+    if !target_handoff.exists() {
+        anyhow::bail!(
+            "Target project is not initialized (no .handoff/): {}",
+            target_dir.display()
+        );
+    }
+
+    let summary = arguments
+        .get("summary")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'summary' is required"))?;
+
+    let referral_type = arguments
+        .get("referral_type")
+        .and_then(|v| v.as_str())
+        .unwrap_or("request");
+
+    if !is_valid_referral_type(referral_type) {
+        anyhow::bail!(
+            "Invalid referral_type: '{referral_type}'. Must be one of: improvement, bug, request, info"
+        );
+    }
+
+    let priority = arguments.get("priority").and_then(|v| v.as_str());
+    validate_priority(priority)?;
+
+    let details = arguments
+        .get("details")
+        .and_then(|v| v.as_str())
+        .map(String::from);
+
+    let tasks: Vec<Value> = arguments
+        .get("tasks")
+        .and_then(|v| v.as_array())
+        .cloned()
+        .unwrap_or_default();
+
+    let context = arguments.get("context").cloned();
+
+    let now_dt = Utc::now();
+    let now = now_dt.to_rfc3339();
+    let id = format!("ref-{}", now_dt.format("%Y%m%d-%H%M%S-%f"));
+
+    let data = ReferralData {
+        id: id.clone(),
+        source_project: source_config.project.name.clone(),
+        source_project_dir: source_project_dir.to_string_lossy().to_string(),
+        created_at: now,
+        referral_type: referral_type.to_string(),
+        summary: summary.to_string(),
+        details,
+        priority: priority.map(String::from),
+        tasks,
+        context,
+    };
+
+    let referrals_dir = target_handoff.join("referrals");
+    write_referral(&referrals_dir, &data)?;
+
+    let target_name = if target_handoff.join("config.toml").exists() {
+        read_config(&target_handoff.join("config.toml"))
+            .map(|c| c.project.name)
+            .unwrap_or_else(|_| target_dir.to_string_lossy().to_string())
+    } else {
+        target_dir.to_string_lossy().to_string()
+    };
+
+    Ok(format!(
+        "Referral sent: {id}\n  From: {}\n  To: {target_name}\n  Type: {referral_type}\n  Summary: {summary}",
+        source_config.project.name
+    ))
+}
+
+fn resolve_target(arguments: &Value, scan_dirs: &[String]) -> Result<PathBuf> {
+    if let Some(dir) = arguments.get("target_project_dir").and_then(|v| v.as_str()) {
+        let path = PathBuf::from(dir);
+        return std::fs::canonicalize(&path)
+            .with_context(|| format!("Invalid target project path: {}", path.display()));
+    }
+
+    if let Some(name) = arguments.get("target_project").and_then(|v| v.as_str()) {
+        return resolve_by_name(name, scan_dirs);
+    }
+
+    anyhow::bail!("Either 'target_project' or 'target_project_dir' is required")
+}
+
+fn resolve_by_name(name: &str, scan_dirs: &[String]) -> Result<PathBuf> {
+    for scan_dir in scan_dirs {
+        let expanded = expand_tilde(scan_dir);
+        let expanded_path = Path::new(&expanded);
+
+        if !expanded_path.exists() {
+            continue;
+        }
+
+        let entries = match std::fs::read_dir(expanded_path) {
+            Ok(e) => e,
+            Err(_) => continue,
+        };
+
+        for entry in entries.flatten() {
+            if !entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+                continue;
+            }
+
+            let config_path = entry.path().join(".handoff/config.toml");
+            if !config_path.exists() {
+                continue;
+            }
+
+            if let Ok(config) = read_config(&config_path) {
+                if config.project.name == name {
+                    return Ok(entry.path());
+                }
+            }
+        }
+    }
+
+    anyhow::bail!(
+        "Target project '{name}' not found in scan_dirs. \
+         Use 'target_project_dir' with an absolute path instead."
+    )
+}

package/src/mcp/handlers/referrals.rs

@@ -0,0 +1,55 @@
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::referrals::{
+    change_referral_status, is_valid_referral_status, read_referral_summaries,
+};
+
+pub fn handle_list(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let referrals_dir = handoff.join("referrals");
+
+    let status_filter = arguments.get("status_filter").and_then(|v| v.as_str());
+
+    if let Some(filter) = status_filter {
+        if !is_valid_referral_status(filter) {
+            anyhow::bail!(
+                "Invalid status_filter: '{filter}'. Must be one of: open, acknowledged, resolved"
+            );
+        }
+    }
+
+    let summaries = read_referral_summaries(&referrals_dir, status_filter)?;
+
+    let result = serde_json::json!({
+        "referrals": summaries,
+        "total": summaries.len(),
+    });
+
+    serde_json::to_string_pretty(&result).context("Failed to serialize referrals")
+}
+
+pub fn handle_update(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let referrals_dir = handoff.join("referrals");
+
+    let referral_id = arguments
+        .get("referral_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'referral_id' is required"))?;
+
+    let status = arguments
+        .get("status")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'status' is required"))?;
+
+    change_referral_status(&referrals_dir, referral_id, status)?;
+
+    Ok(format!(
+        "Updated referral {referral_id}: status -> {status}"
+    ))
+}

package/src/mcp/handlers/update_task.rs

@@ -16,11 +16,6 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .get("task")
         .ok_or_else(|| anyhow::anyhow!("'task' parameter is required"))?;
 
-    let title = task_val
-        .get("title")
-        .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow::anyhow!("'task.title' is required"))?;
-
     let task_id = task_val.get("id").and_then(|v| v.as_str());
     let move_to = arguments.get("move_to").and_then(|v| v.as_str());
 
@@ -31,6 +26,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         return handle_update(&tasks_dir, existing_id, task_val);
     }
 
+    let title = task_val
+        .get("title")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'task.title' is required for new tasks"))?;
+
     handle_create(&tasks_dir, title, task_val, arguments)
 }
 
@@ -71,6 +71,9 @@ fn handle_create(
         anyhow::bail!("Invalid status: {status}");
     }
 
+    let priority = task_val.get("priority").and_then(|v| v.as_str());
+    validate_priority(priority)?;
+
     let data = TaskData {
         id: new_id.clone(),
         title: title.to_string(),
@@ -78,10 +81,7 @@ fn handle_create(
             .get("notes")
             .and_then(|v| v.as_str())
             .map(String::from),
-        priority: task_val
-            .get("priority")
-            .and_then(|v| v.as_str())
-            .map(String::from),
+        priority: priority.map(String::from),
         created_at: Some(now.clone()),
         updated_at: Some(now),
         completed_at: None,
@@ -109,6 +109,7 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
         data.notes = Some(notes.to_string());
     }
     if let Some(priority) = task_val.get("priority").and_then(|v| v.as_str()) {
+        validate_priority(Some(priority))?;
         data.priority = Some(priority.to_string());
     }
     if task_val.get("labels").is_some() {

package/src/mcp/tools.rs

@@ -156,6 +156,50 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_get_task".to_string(),
+            description: "Get full task details (notes, done_criteria, labels, links) by task ID. Use when list_tasks summary is not enough.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "task_id": {
+                        "type": "string",
+                        "description": "Task ID to retrieve (e.g. 't1', 't1.2')."
+                    }
+                },
+                "required": ["task_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_check_criterion".to_string(),
+            description: "Toggle a single done_criteria item by index. No need to resend the entire criteria list.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "task_id": {
+                        "type": "string",
+                        "description": "Task ID containing the criterion."
+                    },
+                    "criterion_index": {
+                        "type": "integer",
+                        "description": "0-based index of the done_criteria item to toggle."
+                    },
+                    "checked": {
+                        "type": "boolean",
+                        "description": "true to mark as checked, false to uncheck."
+                    }
+                },
+                "required": ["task_id", "criterion_index", "checked"]
+            }),
+        },
         ToolDefinition {
             name: "handoff_update_task".to_string(),
             description: "Add, update, or move a task. Manages the tasks/ directory structure.".to_string(),
@@ -170,7 +214,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "object",
                         "properties": {
                             "id": { "type": "string", "description": "Task ID. Omit for new task (auto-generated)." },
-                            "title": { "type": "string" },
+                            "title": { "type": "string", "description": "Required for new tasks. Optional when updating (id present)." },
                             "status": {
                                 "type": "string",
                                 "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
@@ -200,7 +244,6 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                                 }
                             }
                         },
-                        "required": ["title"]
                     },
                     "parent_id": {
                         "type": "string",
@@ -263,6 +306,278 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_import_context".to_string(),
+            description: "Import existing handoff documents into .handoff/ management. AI reads the source material, structures it, and submits everything in one call. Supports nested task hierarchies via children field.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "source": {
+                        "type": "object",
+                        "description": "Metadata about the original document being imported",
+                        "properties": {
+                            "description": {
+                                "type": "string",
+                                "description": "What is being imported (e.g. 'Migration from tmp/260601-sprint-handoff.md')"
+                            },
+                            "format": {
+                                "type": "string",
+                                "enum": ["markdown", "json", "text", "other"],
+                                "description": "Format of the source material. Defaults to 'other'."
+                            }
+                        },
+                        "required": ["description"]
+                    },
+                    "tasks": {
+                        "type": "array",
+                        "description": "Tasks to import. Supports nested hierarchies via children field.",
+                        "items": {
+                            "$ref": "#/$defs/importTask"
+                        }
+                    },
+                    "session": {
+                        "type": "object",
+                        "description": "Session context to save. Same fields as handoff_save_context.",
+                        "properties": {
+                            "summary": { "type": "string", "description": "One-line summary (required)" },
+                            "decisions": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "decision": { "type": "string" },
+                                        "reason": { "type": "string" },
+                                        "confidence": {
+                                            "type": "string",
+                                            "enum": ["confirmed", "estimated", "unverified"]
+                                        }
+                                    },
+                                    "required": ["decision"]
+                                }
+                            },
+                            "blockers": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "checklist": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "item": { "type": "string" },
+                                        "checked": { "type": "boolean" },
+                                        "owner": { "type": "string", "enum": ["user", "ai"] }
+                                    },
+                                    "required": ["item"]
+                                }
+                            },
+                            "handoff_notes": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "note": { "type": "string" },
+                                        "category": { "type": "string", "enum": ["caution", "context", "suggestion"] }
+                                    },
+                                    "required": ["note"]
+                                }
+                            },
+                            "references": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "label": { "type": "string" },
+                                        "uri": { "type": "string" },
+                                        "type": { "type": "string", "enum": ["file", "issue", "mr", "wiki", "doc", "url"] },
+                                        "notes": { "type": "string" }
+                                    },
+                                    "required": ["label", "uri"]
+                                }
+                            },
+                            "context_pointers": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "path": { "type": "string" },
+                                        "reason": { "type": "string" },
+                                        "lines": { "type": "string" }
+                                    },
+                                    "required": ["path"]
+                                }
+                            },
+                            "environment": {
+                                "type": "object",
+                                "description": "Free-form environment state"
+                            }
+                        },
+                        "required": ["summary"]
+                    },
+                    "raw_notes": {
+                        "type": "string",
+                        "description": "Free-form text that couldn't be structured. Saved as a handoff_note with category 'context'."
+                    }
+                },
+                "required": ["source"],
+                "$defs": {
+                    "importTask": {
+                        "type": "object",
+                        "properties": {
+                            "title": { "type": "string" },
+                            "status": {
+                                "type": "string",
+                                "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
+                            },
+                            "notes": { "type": "string" },
+                            "priority": {
+                                "type": "string",
+                                "enum": ["low", "medium", "high"]
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "links": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "done_criteria": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "item": { "type": "string" },
+                                        "checked": { "type": "boolean" }
+                                    },
+                                    "required": ["item"]
+                                }
+                            },
+                            "children": {
+                                "type": "array",
+                                "description": "Nested child tasks. Recursively supports the same structure.",
+                                "items": {
+                                    "$ref": "#/$defs/importTask"
+                                }
+                            }
+                        },
+                        "required": ["title"]
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_refer".to_string(),
+            description: "Send a cross-project referral (improvement request, bug report, work request) to another project's .handoff/. The target project sees it on load_context.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Source project directory (sender). Defaults to current working directory."
+                    },
+                    "target_project": {
+                        "type": "string",
+                        "description": "Target project name (resolved via scan_dirs). Use this OR target_project_dir."
+                    },
+                    "target_project_dir": {
+                        "type": "string",
+                        "description": "Target project directory path (absolute). Takes precedence over target_project."
+                    },
+                    "referral_type": {
+                        "type": "string",
+                        "enum": ["improvement", "bug", "request", "info"],
+                        "description": "Type of referral. Defaults to 'request'."
+                    },
+                    "summary": {
+                        "type": "string",
+                        "description": "One-line summary of the referral."
+                    },
+                    "details": {
+                        "type": "string",
+                        "description": "Detailed description of the referral."
+                    },
+                    "priority": {
+                        "type": "string",
+                        "enum": ["low", "medium", "high"],
+                        "description": "Priority of the referral."
+                    },
+                    "tasks": {
+                        "type": "array",
+                        "description": "Suggested tasks for the target project.",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "title": { "type": "string" },
+                                "priority": { "type": "string", "enum": ["low", "medium", "high"] },
+                                "done_criteria": {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "object",
+                                        "properties": {
+                                            "item": { "type": "string" },
+                                            "checked": { "type": "boolean" }
+                                        },
+                                        "required": ["item"]
+                                    }
+                                }
+                            },
+                            "required": ["title"]
+                        }
+                    },
+                    "context": {
+                        "type": "object",
+                        "description": "Additional context (branch, commit, references)."
+                    }
+                },
+                "required": ["summary"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_list_referrals".to_string(),
+            description: "List incoming referrals from other projects with optional status filter.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "status_filter": {
+                        "type": "string",
+                        "enum": ["open", "acknowledged", "resolved"],
+                        "description": "Filter by referral status."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_update_referral".to_string(),
+            description: "Update the status of an incoming referral (open -> acknowledged -> resolved).".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "referral_id": {
+                        "type": "string",
+                        "description": "ID of the referral to update."
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["open", "acknowledged", "resolved"],
+                        "description": "New status for the referral."
+                    }
+                },
+                "required": ["referral_id", "status"]
+            }),
+        },
     ]
 }
 

package/src/storage/mod.rs

@@ -1,5 +1,6 @@
 pub mod config;
 pub mod git;
+pub mod referrals;
 pub mod sessions;
 pub mod tasks;
 
@@ -7,6 +8,15 @@ use std::path::{Path, PathBuf};
 
 use anyhow::{Context, Result};
 
+pub fn expand_tilde(path: &str) -> String {
+    if let Some(rest) = path.strip_prefix("~/") {
+        if let Ok(home) = std::env::var("HOME") {
+            return format!("{home}/{rest}");
+        }
+    }
+    path.to_string()
+}
+
 pub fn handoff_dir(project_dir: &Path) -> PathBuf {
     project_dir.join(".handoff")
 }