handoff-mcp-server 0.7.3 → 0.8.1

package/Cargo.lock

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

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.7.3"
+version = "0.8.1"
 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.7.3",
+  "version": "0.8.1",
   "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

@@ -28,8 +28,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .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 task_dir = find_task_dir_by_id(&tasks_dir, task_id)?.ok_or_else(|| {
+        anyhow::anyhow!(
+            "Task not found: {task_id}. Use handoff_list_tasks to see available task IDs."
+        )
+    })?;
 
     let (mut data, status) = read_task(&task_dir)?
         .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;

package/src/mcp/handlers/get_task.rs

@@ -16,8 +16,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .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 task_dir = find_task_dir_by_id(&tasks_dir, task_id)?.ok_or_else(|| {
+        anyhow::anyhow!(
+            "Task not found: {task_id}. Use handoff_list_tasks to see available task IDs."
+        )
+    })?;
 
     let (data, status) = read_task(&task_dir)?
         .ok_or_else(|| anyhow::anyhow!("Task file not found in {}", task_dir.display()))?;

package/src/mcp/handlers/import_context.rs

@@ -49,6 +49,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         }
     }
 
+    let skip_session_close = arguments
+        .get("skip_session_close")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
     let mut session_saved = false;
     if let Some(session) = arguments.get("session") {
         let summary = session
@@ -58,7 +63,9 @@ pub fn handle(arguments: &Value) -> Result<String> {
                 anyhow::anyhow!("'session.summary' is required when session is provided")
             })?;
 
-        close_active_sessions(&sessions_dir)?;
+        if !skip_session_close {
+            close_active_sessions(&sessions_dir)?;
+        }
         let git_state = capture_git_state(&project_dir)?;
         let now = Utc::now().to_rfc3339();
 
@@ -118,7 +125,9 @@ pub fn handle(arguments: &Value) -> Result<String> {
         session_saved = true;
     } else if let Some(raw_notes) = arguments.get("raw_notes").and_then(|v| v.as_str()) {
         if !raw_notes.is_empty() {
-            close_active_sessions(&sessions_dir)?;
+            if !skip_session_close {
+                close_active_sessions(&sessions_dir)?;
+            }
             let git_state = capture_git_state(&project_dir)?;
             let now = Utc::now().to_rfc3339();
 

package/src/mcp/handlers/save_context.rs

@@ -21,11 +21,6 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let sessions_dir = handoff.join("sessions");
     let config_path = handoff.join("config.toml");
 
-    let summary = arguments
-        .get("summary")
-        .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow::anyhow!("'summary' is required"))?;
-
     let close_id = arguments.get("close_session_id").and_then(|v| v.as_str());
     let pause_id = arguments.get("pause_session_id").and_then(|v| v.as_str());
     let pause_all = arguments
@@ -37,6 +32,19 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .and_then(|v| v.as_str())
         .unwrap_or("open");
 
+    let is_pause_only = arguments
+        .get("pause_only")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false);
+
+    let summary_opt = arguments.get("summary").and_then(|v| v.as_str());
+
+    if !is_pause_only && summary_opt.is_none() {
+        anyhow::bail!("'summary' is required (unless pause_only=true)");
+    }
+
+    let summary = summary_opt.unwrap_or("");
+
     if session_status != "open" && session_status != "active" {
         anyhow::bail!(
             "Invalid session_status '{}': must be 'open' or 'active'",
@@ -53,6 +61,27 @@ pub fn handle(arguments: &Value) -> Result<String> {
         total_paused = pause_active_sessions(&sessions_dir)?.len();
     }
 
+    if is_pause_only {
+        let mut msg = String::new();
+        if total_paused > 0 {
+            msg.push_str(&format!("Paused {} session(s)", total_paused));
+        }
+        if let Some(id) = pause_id {
+            if total_paused == 0 {
+                msg.push_str(&format!(
+                    "Warning: pause_session_id '{id}' not found among active/open sessions"
+                ));
+            }
+        }
+        if !pause_all && pause_id.is_none() {
+            msg.push_str("Warning: pause_only=true requires pause_session_id or pause_active=true");
+        }
+        if msg.is_empty() {
+            msg.push_str("No sessions were paused (none active)");
+        }
+        return Ok(msg);
+    }
+
     let total_closed = if let Some(id) = close_id {
         let closed = close_session_by_id(&sessions_dir, id)?;
         if closed.is_some() {
@@ -124,7 +153,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
     if let Some(id) = pause_id {
         if total_paused == 0 {
             msg.push_str(&format!(
-                "\nWarning: pause_session_id '{id}' not found among active sessions"
+                "\nWarning: pause_session_id '{id}' not found among active/open sessions"
             ));
         }
     }

package/src/mcp/handlers/update_task.rs

@@ -23,7 +23,11 @@ pub fn handle(arguments: &Value) -> Result<String> {
         if let Some(new_parent_id) = move_to {
             return handle_move(&tasks_dir, existing_id, new_parent_id);
         }
-        return handle_update(&tasks_dir, existing_id, task_val);
+        let task_exists = find_task_dir_by_id(&tasks_dir, existing_id)?.is_some();
+        if task_exists {
+            return handle_update(&tasks_dir, existing_id, task_val);
+        }
+        return handle_upsert_create(&tasks_dir, existing_id, task_val, arguments);
     }
 
     let title = task_val
@@ -106,6 +110,84 @@ fn handle_create(
     Ok(format!("Created task {new_id}: {title} [{status}]"))
 }
 
+fn handle_upsert_create(
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+    task_val: &Value,
+    arguments: &Value,
+) -> Result<String> {
+    let title = task_val
+        .get("title")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| {
+            anyhow::anyhow!(
+                "Task '{task_id}' does not exist and cannot be created without a title. \
+                 Provide 'title' to create a new task with this ID, or use handoff_list_tasks to find existing task IDs."
+            )
+        })?;
+
+    let parent_id = arguments.get("parent_id").and_then(|v| v.as_str());
+
+    let parent_dir = match parent_id {
+        Some(pid) => find_task_dir_by_id(tasks_dir, pid)?.ok_or_else(|| {
+            anyhow::anyhow!(
+                "Parent task not found: {pid}. Use handoff_list_tasks to see available task IDs."
+            )
+        })?,
+        None => tasks_dir.to_path_buf(),
+    };
+
+    let slug = title_to_slug(title);
+    let dir_name = format!("{task_id}-{slug}");
+    let task_dir = parent_dir.join(&dir_name);
+    std::fs::create_dir_all(&task_dir)
+        .with_context(|| format!("Failed to create task dir: {}", task_dir.display()))?;
+
+    let now = Utc::now().to_rfc3339();
+    let status = task_val
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("todo");
+
+    if !is_valid_status(status) {
+        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, task_id, &dependencies)?;
+    }
+
+    let data = TaskData {
+        id: task_id.to_string(),
+        title: title.to_string(),
+        notes: task_val
+            .get("notes")
+            .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)?;
+
+    Ok(format!("Created task {task_id}: {title} [{status}]"))
+}
+
 fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -> Result<String> {
     let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
         .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
@@ -179,11 +261,17 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
 }
 
 fn handle_move(tasks_dir: &std::path::Path, task_id: &str, new_parent_id: &str) -> Result<String> {
-    let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
-        .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
+    let task_dir = find_task_dir_by_id(tasks_dir, task_id)?.ok_or_else(|| {
+        anyhow::anyhow!(
+            "Task not found: {task_id}. Use handoff_list_tasks to see available task IDs."
+        )
+    })?;
 
-    let new_parent_dir = find_task_dir_by_id(tasks_dir, new_parent_id)?
-        .ok_or_else(|| anyhow::anyhow!("New parent task not found: {new_parent_id}"))?;
+    let new_parent_dir = find_task_dir_by_id(tasks_dir, new_parent_id)?.ok_or_else(|| {
+        anyhow::anyhow!(
+            "New parent task not found: {new_parent_id}. Use handoff_list_tasks to see available task IDs."
+        )
+    })?;
 
     let dir_name = task_dir
         .file_name()

package/src/mcp/tools.rs

@@ -75,6 +75,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "boolean",
                         "description": "If true, pause all active sessions instead of closing them. Cannot be combined with close_session_id."
                     },
+                    "pause_only": {
+                        "type": "boolean",
+                        "description": "If true, only pause sessions (via pause_session_id or pause_active) without creating a new session. Useful for session switching. When true, summary is optional."
+                    },
                     "decisions": {
                         "type": "array",
                         "description": "Decisions made during this session",
@@ -244,7 +248,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "task": {
                         "type": "object",
                         "properties": {
-                            "id": { "type": "string", "description": "Task ID. Omit for new task (auto-generated)." },
+                            "id": { "type": "string", "description": "Task ID. Omit for auto-generated ID. If provided and task exists, updates it. If provided and task does not exist, creates a new task with that ID (upsert)." },
                             "title": { "type": "string", "description": "Required for new tasks. Optional when updating (id present)." },
                             "status": {
                                 "type": "string",
@@ -479,6 +483,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "raw_notes": {
                         "type": "string",
                         "description": "Free-form text that couldn't be structured. Saved as a handoff_note with category 'context'."
+                    },
+                    "skip_session_close": {
+                        "type": "boolean",
+                        "description": "If true, do not close active sessions before creating the import session. Default false."
                     }
                 },
                 "required": ["source"],

package/src/storage/sessions.rs

@@ -273,7 +273,10 @@ pub fn pause_active_sessions(sessions_dir: &Path) -> Result<Vec<PathBuf>> {
 }
 
 pub fn pause_session_by_id(sessions_dir: &Path, session_id: &str) -> Result<Option<PathBuf>> {
-    transition_session_by_id(sessions_dir, session_id, "active", "paused")
+    if let Some(path) = transition_session_by_id(sessions_dir, session_id, "active", "paused")? {
+        return Ok(Some(path));
+    }
+    transition_session_by_id(sessions_dir, session_id, "open", "paused")
 }
 
 pub fn resume_paused_session_by_id(