handoff-mcp-server 0.4.0 → 0.6.0

package/Cargo.lock

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

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.4.0"
+version = "0.6.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.4.0",
+  "version": "0.6.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/dashboard.rs

@@ -6,7 +6,7 @@ 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::sessions::{read_active_sessions, read_open_sessions};
 use crate::storage::tasks::build_task_index;
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -70,7 +70,9 @@ fn collect_project_info(project_path: &Path) -> Result<Value> {
     let handoff_dir = project_path.join(".handoff");
     let config = read_config(&handoff_dir.join("config.toml"))?;
 
-    let sessions = read_active_sessions(&handoff_dir.join("sessions"))?;
+    let sessions_dir = handoff_dir.join("sessions");
+    let mut sessions = read_open_sessions(&sessions_dir)?;
+    sessions.extend(read_active_sessions(&sessions_dir)?);
 
     let (_, summary) =
         build_task_index(&handoff_dir.join("tasks"), config.settings.done_task_limit)?;

package/src/mcp/handlers/import_context.rs

@@ -7,7 +7,8 @@ use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::git::capture_git_state;
 use crate::storage::sessions::{
-    close_active_sessions, enforce_history_limit, write_active_session, SessionData,
+    close_active_sessions, close_open_sessions, enforce_history_limit, write_open_session,
+    SessionData,
 };
 use crate::storage::tasks::*;
 
@@ -58,7 +59,8 @@ pub fn handle(arguments: &Value) -> Result<String> {
                 anyhow::anyhow!("'session.summary' is required when session is provided")
             })?;
 
-        let closed = close_active_sessions(&sessions_dir)?;
+        close_active_sessions(&sessions_dir)?;
+        let closed = close_open_sessions(&sessions_dir)?;
         let git_state = capture_git_state(&project_dir)?;
         let now = Utc::now().to_rfc3339();
 
@@ -89,6 +91,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
         let data = SessionData {
             version: 2,
+            id: None,
             ended_at: Some(now),
             summary: summary.to_string(),
             branch: Some(git_state.branch),
@@ -103,7 +106,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
             environment: Some(environment),
         };
 
-        write_active_session(&sessions_dir, &data)?;
+        write_open_session(&sessions_dir, &data)?;
 
         let history_limit = if config_path.exists() {
             read_config(&config_path)
@@ -118,12 +121,14 @@ 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() {
-            let closed = close_active_sessions(&sessions_dir)?;
+            close_active_sessions(&sessions_dir)?;
+            let closed = close_open_sessions(&sessions_dir)?;
             let git_state = capture_git_state(&project_dir)?;
             let now = Utc::now().to_rfc3339();
 
             let data = SessionData {
                 version: 2,
+                id: None,
                 ended_at: Some(now),
                 summary: format!("[import] {source_description}"),
                 branch: Some(git_state.branch),
@@ -146,7 +151,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
                 })),
             };
 
-            write_active_session(&sessions_dir, &data)?;
+            write_open_session(&sessions_dir, &data)?;
 
             let history_limit = if config_path.exists() {
                 read_config(&config_path)

package/src/mcp/handlers/load_context.rs

@@ -4,7 +4,9 @@ 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::sessions::{
+    activate_open_sessions, activate_session_by_id, read_open_sessions,
+};
 use crate::storage::tasks::build_task_index;
 use crate::storage::{ensure_handoff_exists, handoff_dir};
 
@@ -34,23 +36,21 @@ pub fn handle(arguments: &Value) -> Result<String> {
         anyhow::bail!("config.toml not found");
     };
 
-    let sessions = read_active_sessions(&sessions_dir)?;
+    let target_session_id = arguments.get("session_id").and_then(|v| v.as_str());
 
-    let (task_tree, task_summary) = build_task_index(&tasks_dir, config.settings.done_task_limit)?;
+    let sessions = read_open_sessions(&sessions_dir)?;
 
-    let last_session = sessions.last().map(|s| {
-        serde_json::json!({
-            "ended_at": s.ended_at,
-            "summary": s.summary,
-            "branch": s.branch,
-            "commit": s.commit,
-        })
-    });
+    let selected_session = if let Some(sid) = target_session_id {
+        activate_session_by_id(&sessions_dir, sid)?;
+        sessions
+            .into_iter()
+            .find(|s| s.id.as_deref().is_some_and(|id| id == sid))
+    } else {
+        activate_open_sessions(&sessions_dir)?;
+        sessions.into_iter().last()
+    };
 
-    let active_sessions: Vec<Value> = sessions
-        .iter()
-        .map(|s| serde_json::to_value(s).unwrap_or_default())
-        .collect();
+    let (task_tree, task_summary) = build_task_index(&tasks_dir, config.settings.done_task_limit)?;
 
     let mut result = serde_json::json!({
         "project": config.project.name,
@@ -58,12 +58,26 @@ pub fn handle(arguments: &Value) -> Result<String> {
         "task_summary": task_summary,
     });
 
-    if let Some(ls) = last_session {
-        result["last_session"] = ls;
+    if selected_session.is_none() {
+        if let Some(sid) = target_session_id {
+            result["warning"] =
+                serde_json::json!(format!("session_id '{sid}' not found among open sessions"));
+        }
     }
 
-    if !active_sessions.is_empty() {
-        let latest = &active_sessions[active_sessions.len() - 1];
+    if let Some(ref session) = selected_session {
+        result["last_session"] = serde_json::json!({
+            "ended_at": session.ended_at,
+            "summary": session.summary,
+            "branch": session.branch,
+            "commit": session.commit,
+        });
+
+        if let Some(ref id) = session.id {
+            result["session_id"] = serde_json::json!(id);
+        }
+
+        let session_val = serde_json::to_value(session).unwrap_or_default();
 
         for key in [
             "decisions",
@@ -73,20 +87,35 @@ pub fn handle(arguments: &Value) -> Result<String> {
             "references",
             "context_pointers",
         ] {
-            if let Some(val) = latest.get(key) {
+            if let Some(val) = session_val.get(key) {
                 if val.as_array().is_some_and(|a| !a.is_empty()) {
                     result[key] = val.clone();
                 }
             }
         }
 
-        if let Some(env) = latest.get("environment") {
+        if let Some(env) = session_val.get("environment") {
             if !env.is_null() {
                 result["environment"] = env.clone();
             }
         }
     }
 
+    if let Some(notes) = result.get("handoff_notes").and_then(|v| v.as_array()) {
+        let suggestions: Vec<&str> = notes
+            .iter()
+            .filter(|n| {
+                n.get("category")
+                    .and_then(|c| c.as_str())
+                    .is_some_and(|c| c == "suggestion")
+            })
+            .filter_map(|n| n.get("note").and_then(|v| v.as_str()))
+            .collect();
+        if !suggestions.is_empty() {
+            result["next_actions"] = serde_json::json!(suggestions);
+        }
+    }
+
     if !config.settings.context_files.is_empty() {
         result["suggested_reads"] = serde_json::to_value(&config.settings.context_files)?;
     }

package/src/mcp/handlers/save_context.rs

@@ -7,7 +7,8 @@ use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::git::capture_git_state;
 use crate::storage::sessions::{
-    close_active_sessions, enforce_history_limit, write_active_session, SessionData,
+    close_active_sessions, close_open_sessions, close_session_by_id, enforce_history_limit,
+    generate_session_id, write_open_session, SessionData,
 };
 
 pub fn handle(arguments: &Value) -> Result<String> {
@@ -22,13 +23,28 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .and_then(|v| v.as_str())
         .ok_or_else(|| anyhow::anyhow!("'summary' is required"))?;
 
-    let closed = close_active_sessions(&sessions_dir)?;
+    let close_id = arguments.get("close_session_id").and_then(|v| v.as_str());
+
+    let total_closed = if let Some(id) = close_id {
+        let closed = close_session_by_id(&sessions_dir, id)?;
+        if closed.is_some() {
+            1
+        } else {
+            0
+        }
+    } else {
+        let closed_active = close_active_sessions(&sessions_dir)?;
+        let closed_open = close_open_sessions(&sessions_dir)?;
+        closed_active.len() + closed_open.len()
+    };
 
     let git_state = capture_git_state(&project_dir)?;
     let now = Utc::now().to_rfc3339();
+    let session_id = generate_session_id();
 
     let data = SessionData {
         version: 2,
+        id: Some(session_id.clone()),
         ended_at: Some(now),
         summary: summary.to_string(),
         branch: Some(git_state.branch),
@@ -43,7 +59,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
         environment: arguments.get("environment").cloned(),
     };
 
-    let path = write_active_session(&sessions_dir, &data)?;
+    let path = write_open_session(&sessions_dir, &data)?;
 
     let history_limit = if config_path.exists() {
         read_config(&config_path)
@@ -55,18 +71,23 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let removed = enforce_history_limit(&sessions_dir, history_limit)?;
 
     let mut msg = format!(
-        "Session saved: {}\nFile: {}",
+        "Session saved: {}\nSession ID: {}\nFile: {}",
         summary,
+        session_id,
         path.file_name()
             .map(|n| n.to_string_lossy().to_string())
             .unwrap_or_default()
     );
 
-    if !closed.is_empty() {
-        msg.push_str(&format!(
-            "\nClosed {} previous active session(s)",
-            closed.len()
-        ));
+    if total_closed > 0 {
+        msg.push_str(&format!("\nClosed {} previous session(s)", total_closed));
+    }
+    if let Some(id) = close_id {
+        if total_closed == 0 {
+            msg.push_str(&format!(
+                "\nWarning: close_session_id '{id}' not found among active/open sessions"
+            ));
+        }
     }
     if removed > 0 {
         msg.push_str(&format!(
@@ -74,9 +95,85 @@ pub fn handle(arguments: &Value) -> Result<String> {
         ));
     }
 
+    for w in collect_save_warnings(&data) {
+        msg.push_str(&format!("\n{w}"));
+    }
+
     Ok(msg)
 }
 
+fn collect_save_warnings(data: &SessionData) -> Vec<String> {
+    let mut warnings = Vec::new();
+
+    if data.checklist.is_empty() {
+        warnings.push(
+            "Warning: No checklist items. Consider adding verification items for the next session."
+                .to_string(),
+        );
+    } else {
+        let unchecked: Vec<&str> = data
+            .checklist
+            .iter()
+            .filter_map(|item| {
+                let checked = item
+                    .get("checked")
+                    .and_then(|v| v.as_bool())
+                    .unwrap_or(false);
+                if !checked {
+                    item.get("item").and_then(|v| v.as_str())
+                } else {
+                    None
+                }
+            })
+            .collect();
+
+        if !unchecked.is_empty() {
+            warnings.push(format!(
+                "Warning: {} unchecked checklist item(s) \u{2014} {}",
+                unchecked.len(),
+                unchecked.join(", ")
+            ));
+        }
+    }
+
+    let has_suggestion = data.handoff_notes.iter().any(|note| {
+        note.get("category")
+            .and_then(|v| v.as_str())
+            .is_some_and(|c| c == "suggestion")
+    });
+    if !has_suggestion {
+        warnings.push(
+            "Warning: No 'suggestion' handoff_notes \u{2014} the next session won't know what to \
+             do first. Add at least one note with category 'suggestion' describing the recommended \
+             next action."
+                .to_string(),
+        );
+    }
+
+    if data.context_pointers.is_empty() {
+        warnings.push(
+            "Warning: No context_pointers. The next session won't know which files to read first."
+                .to_string(),
+        );
+    }
+
+    if data.decisions.is_empty() {
+        warnings.push(
+            "Warning: No decisions recorded. Consider documenting key decisions made during this session."
+                .to_string(),
+        );
+    }
+
+    if data.references.is_empty() {
+        warnings.push(
+            "Warning: No references. Consider adding links to relevant docs, issues, or MRs."
+                .to_string(),
+        );
+    }
+
+    warnings
+}
+
 fn extract_array(val: &Value, key: &str) -> Vec<Value> {
     val.get(key)
         .and_then(|v| v.as_array())

package/src/mcp/resources.rs

@@ -2,7 +2,7 @@ use anyhow::{Context, Result};
 use serde_json::{json, Value};
 
 use crate::storage::config::read_config;
-use crate::storage::sessions::read_active_sessions;
+use crate::storage::sessions::{read_active_sessions, read_open_sessions};
 use crate::storage::{ensure_handoff_exists, handoff_dir};
 
 pub fn handle_resource_read(uri: &str) -> Result<Value> {
@@ -24,7 +24,8 @@ pub fn handle_resource_read(uri: &str) -> Result<Value> {
 
 fn read_sessions_resource(handoff: &std::path::Path) -> Result<Value> {
     let sessions_dir = handoff.join("sessions");
-    let sessions = read_active_sessions(&sessions_dir)?;
+    let mut sessions = read_open_sessions(&sessions_dir)?;
+    sessions.extend(read_active_sessions(&sessions_dir)?);
 
     let contents: Vec<Value> = sessions
         .iter()

package/src/mcp/router.rs

@@ -48,7 +48,7 @@ fn handle_initialize() -> JsonRpcResponse {
              ## Session Start\n\
              1. Call handoff_load_context (no args needed — uses cwd)\n\
              2. If it returns \"not initialized\", call handoff_init with the project name\n\
-             3. Review returned tasks, decisions, blockers, and git state before proceeding\n\n\
+             3. Check the `next_actions` array first — these are the previous session's recommended next steps. Do not re-verify work the previous session already completed\n\n\
              ## Session End\n\
              1. Call handoff_save_context with:\n\
                 - summary: one-line description of what was accomplished\n\

package/src/mcp/tools.rs

@@ -35,6 +35,10 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "project_dir": {
                         "type": "string",
                         "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "session_id": {
+                        "type": "string",
+                        "description": "Session ID to activate and load. If omitted, activates all open sessions and returns the latest."
                     }
                 }
             }),
@@ -53,16 +57,21 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "string",
                         "description": "One-line summary of this session"
                     },
+                    "close_session_id": {
+                        "type": "string",
+                        "description": "Session ID to close. If omitted, all active and open sessions are closed (default behavior)."
+                    },
                     "decisions": {
                         "type": "array",
                         "description": "Decisions made during this session",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "decision": { "type": "string" },
-                                "reason": { "type": "string" },
+                                "decision": { "type": "string", "description": "What was decided" },
+                                "reason": { "type": "string", "description": "Why this decision was made" },
                                 "confidence": {
                                     "type": "string",
+                                    "description": "confirmed = verified by testing/evidence; estimated = reasoned but not verified; unverified = hypothesis needing validation",
                                     "enum": ["confirmed", "estimated", "unverified"]
                                 }
                             },
@@ -71,17 +80,20 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "blockers": {
                         "type": "array",
+                        "description": "Issues preventing progress. The next session should address these before starting new work.",
                         "items": { "type": "string" }
                     },
                     "checklist": {
                         "type": "array",
+                        "description": "Verification items for the next session or user. Mark completed items as checked:true before saving.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "item": { "type": "string" },
-                                "checked": { "type": "boolean" },
+                                "item": { "type": "string", "description": "What to verify or confirm" },
+                                "checked": { "type": "boolean", "description": "true if already verified, false if pending" },
                                 "owner": {
                                     "type": "string",
+                                    "description": "user = requires human action; ai = the next AI session should handle this",
                                     "enum": ["user", "ai"]
                                 }
                             },
@@ -90,12 +102,14 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "handoff_notes": {
                         "type": "array",
+                        "description": "Notes for the next session. Include at least one 'suggestion' with a concrete next action.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "note": { "type": "string" },
+                                "note": { "type": "string", "description": "The note content. For suggestions: state what is ALREADY DONE, then describe the concrete next action." },
                                 "category": {
                                     "type": "string",
+                                    "description": "caution = risks/rules the next session must respect; context = background info for decisions; suggestion = concrete next action the next session should execute first (at least one required)",
                                     "enum": ["caution", "context", "suggestion"]
                                 }
                             },
@@ -104,28 +118,31 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     },
                     "references": {
                         "type": "array",
+                        "description": "Links to related docs, issues, MRs, or external resources for reference (not active work files — use context_pointers for those).",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "label": { "type": "string" },
-                                "uri": { "type": "string" },
+                                "label": { "type": "string", "description": "Human-readable label for this reference" },
+                                "uri": { "type": "string", "description": "Path, URL, or identifier" },
                                 "type": {
                                     "type": "string",
+                                    "description": "file = project file; issue = issue tracker; mr = merge/pull request; wiki = wiki page; doc = design document; url = external URL",
                                     "enum": ["file", "issue", "mr", "wiki", "doc", "url"]
                                 },
-                                "notes": { "type": "string" }
+                                "notes": { "type": "string", "description": "Additional context (e.g. 'see section 3 for root cause analysis')" }
                             },
                             "required": ["label", "uri"]
                         }
                     },
                     "context_pointers": {
                         "type": "array",
+                        "description": "Files the next session should open first to resume work. Point to files that NEED WORK, not completed files. For completed files, use a 'context' handoff_note instead.",
                         "items": {
                             "type": "object",
                             "properties": {
-                                "path": { "type": "string" },
-                                "reason": { "type": "string" },
-                                "lines": { "type": "string" }
+                                "path": { "type": "string", "description": "File path relative to project root" },
+                                "reason": { "type": "string", "description": "Why the next session should read this (e.g. 'resume implementation here', 'needs review')" },
+                                "lines": { "type": "string", "description": "Line range to focus on (e.g. '42-78')" }
                             },
                             "required": ["path"]
                         }
@@ -366,13 +383,15 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             "summary": { "type": "string", "description": "One-line summary (required)" },
                             "decisions": {
                                 "type": "array",
+                                "description": "Decisions made during this session",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "decision": { "type": "string" },
-                                        "reason": { "type": "string" },
+                                        "decision": { "type": "string", "description": "What was decided" },
+                                        "reason": { "type": "string", "description": "Why this decision was made" },
                                         "confidence": {
                                             "type": "string",
+                                            "description": "confirmed = verified; estimated = reasoned but not verified; unverified = hypothesis",
                                             "enum": ["confirmed", "estimated", "unverified"]
                                         }
                                     },
@@ -381,52 +400,57 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                             },
                             "blockers": {
                                 "type": "array",
+                                "description": "Issues preventing progress",
                                 "items": { "type": "string" }
                             },
                             "checklist": {
                                 "type": "array",
+                                "description": "Verification items for the next session or user",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "item": { "type": "string" },
-                                        "checked": { "type": "boolean" },
-                                        "owner": { "type": "string", "enum": ["user", "ai"] }
+                                        "item": { "type": "string", "description": "What to verify" },
+                                        "checked": { "type": "boolean", "description": "true if verified, false if pending" },
+                                        "owner": { "type": "string", "description": "user = human action; ai = next AI session", "enum": ["user", "ai"] }
                                     },
                                     "required": ["item"]
                                 }
                             },
                             "handoff_notes": {
                                 "type": "array",
+                                "description": "Notes for the next session. Include at least one 'suggestion' with a concrete next action.",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "note": { "type": "string" },
-                                        "category": { "type": "string", "enum": ["caution", "context", "suggestion"] }
+                                        "note": { "type": "string", "description": "The note content. For suggestions: state what is done, then the next action." },
+                                        "category": { "type": "string", "description": "caution = risks/rules; context = background; suggestion = concrete next action (at least one required)", "enum": ["caution", "context", "suggestion"] }
                                     },
                                     "required": ["note"]
                                 }
                             },
                             "references": {
                                 "type": "array",
+                                "description": "Links to related docs, issues, MRs (not active work files)",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "label": { "type": "string" },
-                                        "uri": { "type": "string" },
-                                        "type": { "type": "string", "enum": ["file", "issue", "mr", "wiki", "doc", "url"] },
-                                        "notes": { "type": "string" }
+                                        "label": { "type": "string", "description": "Human-readable label" },
+                                        "uri": { "type": "string", "description": "Path, URL, or identifier" },
+                                        "type": { "type": "string", "description": "file/issue/mr/wiki/doc/url", "enum": ["file", "issue", "mr", "wiki", "doc", "url"] },
+                                        "notes": { "type": "string", "description": "Additional context" }
                                     },
                                     "required": ["label", "uri"]
                                 }
                             },
                             "context_pointers": {
                                 "type": "array",
+                                "description": "Files the next session should open first to resume work (not completed files)",
                                 "items": {
                                     "type": "object",
                                     "properties": {
-                                        "path": { "type": "string" },
-                                        "reason": { "type": "string" },
-                                        "lines": { "type": "string" }
+                                        "path": { "type": "string", "description": "File path relative to project root" },
+                                        "reason": { "type": "string", "description": "Why to read this file" },
+                                        "lines": { "type": "string", "description": "Line range (e.g. '42-78')" }
                                     },
                                     "required": ["path"]
                                 }