handoff-mcp-server 0.2.0 → 0.4.0

package/Cargo.lock

@@ -144,7 +144,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.2.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.2.0"
+version = "0.4.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/src/mcp/handlers/check_criterion.rs

@@ -0,0 +1,68 @@
+use anyhow::Result;
+use chrono::Utc;
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::tasks::{find_task_dir_by_id, find_task_file, read_task, write_task};
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let tasks_dir = handoff.join("tasks");
+
+    let task_id = arguments
+        .get("task_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'task_id' parameter is required"))?;
+
+    let criterion_index = arguments
+        .get("criterion_index")
+        .and_then(|v| v.as_u64())
+        .ok_or_else(|| anyhow::anyhow!("'criterion_index' parameter is required"))?
+        as usize;
+
+    let checked = arguments
+        .get("checked")
+        .and_then(|v| v.as_bool())
+        .ok_or_else(|| anyhow::anyhow!("'checked' parameter is required (boolean)"))?;
+
+    let task_dir = find_task_dir_by_id(&tasks_dir, task_id)?
+        .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
+
+    let (mut data, status) = read_task(&task_dir)?
+        .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
+
+    if criterion_index >= data.done_criteria.len() {
+        anyhow::bail!(
+            "criterion_index {criterion_index} is out of range (task has {} criteria)",
+            data.done_criteria.len()
+        );
+    }
+
+    data.done_criteria[criterion_index].checked = checked;
+    data.updated_at = Some(Utc::now().to_rfc3339());
+
+    if let Some((old_path, _)) = find_task_file(&task_dir)? {
+        std::fs::remove_file(&old_path)?;
+    }
+
+    write_task(&task_dir, &status, &data)?;
+
+    let checked_count = data.done_criteria.iter().filter(|c| c.checked).count();
+    let total = data.done_criteria.len();
+
+    let result = serde_json::json!({
+        "task_id": data.id,
+        "criterion_index": criterion_index,
+        "item": data.done_criteria[criterion_index].item,
+        "checked": checked,
+        "done_criteria_summary": {
+            "total": total,
+            "checked": checked_count,
+        }
+    });
+
+    serde_json::to_string_pretty(&result).map_err(Into::into)
+}

package/src/mcp/handlers/dashboard.rs

@@ -4,6 +4,8 @@ use anyhow::{Context, Result};
 use serde_json::Value;
 
 use crate::storage::config::read_config;
+use crate::storage::expand_tilde;
+use crate::storage::referrals::read_referral_summaries;
 use crate::storage::sessions::read_active_sessions;
 use crate::storage::tasks::build_task_index;
 
@@ -88,6 +90,10 @@ fn collect_project_info(project_path: &Path) -> Result<Value> {
         .flat_map(|s| s.blockers.iter().cloned())
         .collect();
 
+    let unread_referrals = read_referral_summaries(&handoff_dir.join("referrals"), Some("open"))
+        .map(|r| r.len() as u32)
+        .unwrap_or(0);
+
     Ok(serde_json::json!({
         "name": config.project.name,
         "path": project_path.to_string_lossy(),
@@ -96,14 +102,6 @@ fn collect_project_info(project_path: &Path) -> Result<Value> {
         "active_tasks": active_tasks,
         "blocked_tasks": blocked_tasks,
         "blockers": blockers,
+        "unread_referrals": unread_referrals,
     }))
 }
-
-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()
-}

package/src/mcp/handlers/get_task.rs

@@ -0,0 +1,43 @@
+use anyhow::Result;
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::ensure_handoff_exists;
+use crate::storage::tasks::{find_task_dir_by_id, read_task};
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let tasks_dir = handoff.join("tasks");
+
+    let task_id = arguments
+        .get("task_id")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("'task_id' parameter is required"))?;
+
+    let task_dir = find_task_dir_by_id(&tasks_dir, task_id)?
+        .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
+
+    let (data, status) = read_task(&task_dir)?
+        .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;
+
+    let result = serde_json::json!({
+        "id": data.id,
+        "title": data.title,
+        "status": status,
+        "notes": data.notes,
+        "priority": data.priority,
+        "created_at": data.created_at,
+        "updated_at": data.updated_at,
+        "completed_at": data.completed_at,
+        "labels": data.labels,
+        "links": data.links,
+        "done_criteria": data.done_criteria,
+        "schedule": data.schedule,
+        "dependencies": data.dependencies,
+        "order": data.order,
+    });
+
+    serde_json::to_string_pretty(&result).map_err(Into::into)
+}

package/src/mcp/handlers/import_context.rs

@@ -212,6 +212,9 @@ fn create_task_recursive(
         anyhow::bail!("Invalid status: {status}");
     }
 
+    let priority = task_val.get("priority").and_then(|v| v.as_str());
+    validate_priority(priority)?;
+
     let completed_at = if is_terminal_status(status) {
         Some(now.clone())
     } else {
@@ -225,16 +228,19 @@ fn create_task_recursive(
             .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,
         labels: extract_string_array_from(task_val, "labels"),
         links: extract_string_array_from(task_val, "links"),
         done_criteria: extract_done_criteria(task_val),
+        schedule: extract_schedule(task_val),
+        dependencies: extract_string_array_from(task_val, "dependencies"),
+        order: task_val
+            .get("order")
+            .and_then(|v| v.as_u64())
+            .map(|v| v as u32),
     };
 
     write_task(&task_dir, status, &data)?;
@@ -308,3 +314,26 @@ fn extract_done_criteria(val: &Value) -> Vec<DoneCriterion> {
         })
         .unwrap_or_default()
 }
+
+fn extract_schedule(val: &Value) -> Option<Schedule> {
+    let sched = val.get("schedule")?;
+    if sched.is_null() {
+        return None;
+    }
+    Some(Schedule {
+        start_date: sched
+            .get("start_date")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        due_date: sched
+            .get("due_date")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        estimate_hours: sched.get("estimate_hours").and_then(|v| v.as_f64()),
+        actual_hours: sched.get("actual_hours").and_then(|v| v.as_f64()),
+        milestone: sched
+            .get("milestone")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+    })
+}

package/src/mcp/handlers/list_tasks.rs

@@ -51,6 +51,9 @@ fn filter_tree(
                     id: node.id.clone(),
                     title: node.title.clone(),
                     status: node.status.clone(),
+                    schedule: node.schedule.clone(),
+                    dependencies: node.dependencies.clone(),
+                    order: node.order,
                     children,
                 })
             } else {

package/src/mcp/handlers/load_context.rs

@@ -3,6 +3,7 @@ use serde_json::Value;
 
 use super::resolve_project_dir;
 use crate::storage::config::read_config;
+use crate::storage::referrals::read_referral_summaries;
 use crate::storage::sessions::read_active_sessions;
 use crate::storage::tasks::build_task_index;
 use crate::storage::{ensure_handoff_exists, handoff_dir};
@@ -90,5 +91,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         result["suggested_reads"] = serde_json::to_value(&config.settings.context_files)?;
     }
 
+    let referrals_dir = handoff.join("referrals");
+    let open_referrals = read_referral_summaries(&referrals_dir, Some("open"))?;
+    if !open_referrals.is_empty() {
+        result["referrals"] = serde_json::to_value(&open_referrals)?;
+    }
+
     serde_json::to_string_pretty(&result).context("Failed to serialize context")
 }

package/src/mcp/handlers/mod.rs

@@ -1,9 +1,13 @@
+pub mod check_criterion;
 pub mod config;
 pub mod dashboard;
+pub mod get_task;
 pub mod import_context;
 pub mod init;
 pub mod list_tasks;
 pub mod load_context;
+pub mod refer;
+pub mod referrals;
 pub mod save_context;
 pub mod update_task;
 
@@ -32,7 +36,12 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_dashboard" => dashboard::handle(arguments),
         "handoff_get_config" => config::handle_get(arguments),
         "handoff_update_config" => config::handle_update(arguments),
+        "handoff_get_task" => get_task::handle(arguments),
+        "handoff_check_criterion" => check_criterion::handle(arguments),
         "handoff_import_context" => import_context::handle(arguments),
+        "handoff_refer" => refer::handle(arguments),
+        "handoff_list_referrals" => referrals::handle_list(arguments),
+        "handoff_update_referral" => referrals::handle_update(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

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,14 @@ fn handle_create(
         anyhow::bail!("Invalid status: {status}");
     }
 
+    let priority = task_val.get("priority").and_then(|v| v.as_str());
+    validate_priority(priority)?;
+
+    let dependencies = extract_string_array(task_val, "dependencies");
+    if !dependencies.is_empty() {
+        validate_dependencies(tasks_dir, &new_id, &dependencies)?;
+    }
+
     let data = TaskData {
         id: new_id.clone(),
         title: title.to_string(),
@@ -78,16 +86,19 @@ 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,
         labels: extract_string_array(task_val, "labels"),
         links: extract_string_array(task_val, "links"),
         done_criteria: extract_done_criteria(task_val),
+        schedule: extract_schedule(task_val),
+        dependencies,
+        order: task_val
+            .get("order")
+            .and_then(|v| v.as_u64())
+            .map(|v| v as u32),
     };
 
     write_task(&task_dir, status, &data)?;
@@ -109,6 +120,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() {
@@ -120,6 +132,19 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
     if task_val.get("done_criteria").is_some() {
         data.done_criteria = extract_done_criteria(task_val);
     }
+    if task_val.get("schedule").is_some() {
+        data.schedule = extract_schedule(task_val);
+    }
+    if task_val.get("dependencies").is_some() {
+        let new_deps = extract_string_array(task_val, "dependencies");
+        if !new_deps.is_empty() {
+            validate_dependencies(tasks_dir, task_id, &new_deps)?;
+        }
+        data.dependencies = new_deps;
+    }
+    if let Some(order) = task_val.get("order").and_then(|v| v.as_u64()) {
+        data.order = Some(order as u32);
+    }
 
     let new_status = task_val
         .get("status")
@@ -205,3 +230,26 @@ fn extract_done_criteria(val: &Value) -> Vec<DoneCriterion> {
         })
         .unwrap_or_default()
 }
+
+fn extract_schedule(val: &Value) -> Option<Schedule> {
+    let sched = val.get("schedule")?;
+    if sched.is_null() {
+        return None;
+    }
+    Some(Schedule {
+        start_date: sched
+            .get("start_date")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        due_date: sched
+            .get("due_date")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+        estimate_hours: sched.get("estimate_hours").and_then(|v| v.as_f64()),
+        actual_hours: sched.get("actual_hours").and_then(|v| v.as_f64()),
+        milestone: sched
+            .get("milestone")
+            .and_then(|v| v.as_str())
+            .map(String::from),
+    })
+}