handoff-mcp-server 0.11.0 → 0.13.0

package/src/mcp/handlers/metrics.rs

@@ -5,6 +5,7 @@ use chrono::Utc;
 use serde_json::{json, Value};
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::{build_task_index, is_terminal_status, TaskIndex};
 
@@ -50,6 +51,13 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
     let budget = read_budget(&handoff);
 
+    // AI-effort multiplier: the raw estimate is the human-effort estimate;
+    // multiplying by ai_estimate_multiplier yields the expected AI-effort hours.
+    // Raw estimates are preserved; only the adjusted view is derived here.
+    let multiplier = read_config(&handoff.join("config.toml"))
+        .map(|c| c.settings.ai_estimate_multiplier)
+        .unwrap_or(0.2);
+
     let milestone_list: Vec<Value> = milestones
         .into_iter()
         .map(|(name, (done, ms_total, est, act))| {
@@ -58,6 +66,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
                 "done": done,
                 "total": ms_total,
                 "estimate_hours": est,
+                "adjusted_estimate_hours": est * multiplier,
                 "actual_hours": act,
             })
         })
@@ -68,6 +77,8 @@ pub fn handle(arguments: &Value) -> Result<String> {
         "by_status": by_status,
         "completion_percent": (completion_percent * 10.0).round() / 10.0,
         "total_estimate_hours": estimate_sum,
+        "ai_estimate_multiplier": multiplier,
+        "total_adjusted_estimate_hours": estimate_sum * multiplier,
         "total_actual_hours": actual_sum,
         "total_remaining_hours": remaining_sum,
         "overdue_count": overdue_tasks.len(),

package/src/mcp/handlers/mod.rs

@@ -15,6 +15,7 @@ pub mod list_sessions;
 pub mod list_tasks;
 pub mod load_context;
 pub mod log_time;
+pub mod memory;
 pub mod metrics;
 pub mod milestones;
 pub mod refer;
@@ -53,6 +54,7 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_import_context" => import_context::handle(arguments),
         "handoff_refer" => refer::handle(arguments),
         "handoff_list_referrals" => referrals::handle_list(arguments),
+        "handoff_get_referral" => referrals::handle_get(arguments),
         "handoff_update_referral" => referrals::handle_update(arguments),
         "handoff_update_session" => update_session::handle(arguments),
         "handoff_log_time" => log_time::handle(arguments),
@@ -73,6 +75,10 @@ pub fn handle_tool_call(name: &str, arguments: &Value) -> JsonRpcResponse {
         "handoff_update_calendar" => calendar::handle_update_calendar(arguments),
         "handoff_update_labels" => calendar::handle_update_labels(arguments),
         "handoff_start_project" => calendar::handle_start_project(arguments),
+        "memory_save" => memory::handle_save(arguments),
+        "memory_query" => memory::handle_query(arguments),
+        "memory_delete" => memory::handle_delete(arguments),
+        "memory_cleanup" => memory::handle_cleanup(arguments),
         _ => Err(anyhow::anyhow!("Tool not implemented: {name}")),
     };
 

package/src/mcp/handlers/referrals.rs

@@ -4,7 +4,7 @@ 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,
+    change_referral_status, is_valid_referral_status, read_referral_by_id, read_referral_summaries,
 };
 
 pub fn handle_list(arguments: &Value) -> Result<String> {
@@ -32,6 +32,25 @@ pub fn handle_list(arguments: &Value) -> Result<String> {
     serde_json::to_string_pretty(&result).context("Failed to serialize referrals")
 }
 
+pub fn handle_get(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 (data, status) = read_referral_by_id(&referrals_dir, referral_id)?
+        .ok_or_else(|| anyhow::anyhow!("Referral not found: {referral_id}"))?;
+
+    let mut result = serde_json::to_value(&data).context("Failed to serialize referral")?;
+    result["status"] = Value::String(status);
+
+    serde_json::to_string_pretty(&result).context("Failed to serialize referral")
+}
+
 pub fn handle_update(arguments: &Value) -> Result<String> {
     let project_dir = resolve_project_dir(arguments)?;
     let handoff = ensure_handoff_exists(&project_dir)?;

package/src/mcp/handlers/update_task.rs

@@ -5,6 +5,7 @@ use chrono::Utc;
 use serde_json::Value;
 
 use super::resolve_project_dir;
+use crate::storage::config::read_config;
 use crate::storage::ensure_handoff_exists;
 use crate::storage::tasks::*;
 
@@ -14,6 +15,10 @@ pub fn handle(arguments: &Value) -> Result<String> {
     let handoff = ensure_handoff_exists(&project_dir)?;
     let tasks_dir = handoff.join("tasks");
 
+    let require_estimate_hours = read_config(&handoff.join("config.toml"))
+        .map(|c| c.settings.require_estimate_hours)
+        .unwrap_or(true);
+
     let task_val = arguments
         .get("task")
         .ok_or_else(|| anyhow::anyhow!("'task' parameter is required"))?;
@@ -27,9 +32,15 @@ pub fn handle(arguments: &Value) -> Result<String> {
         }
         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_update(&tasks_dir, existing_id, task_val, require_estimate_hours);
         }
-        return handle_upsert_create(&tasks_dir, existing_id, task_val, arguments);
+        return handle_upsert_create(
+            &tasks_dir,
+            existing_id,
+            task_val,
+            arguments,
+            require_estimate_hours,
+        );
     }
 
     let title = task_val
@@ -37,7 +48,13 @@ pub fn handle(arguments: &Value) -> Result<String> {
         .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)
+    handle_create(
+        &tasks_dir,
+        title,
+        task_val,
+        arguments,
+        require_estimate_hours,
+    )
 }
 
 fn handle_create(
@@ -45,6 +62,7 @@ fn handle_create(
     title: &str,
     task_val: &Value,
     arguments: &Value,
+    require_estimate_hours: bool,
 ) -> Result<String> {
     let parent_id = arguments.get("parent_id").and_then(|v| v.as_str());
 
@@ -112,6 +130,14 @@ fn handle_create(
         extra: HashMap::new(),
     };
 
+    // A newly created task is always a leaf (no children yet).
+    validate_estimate_required(
+        require_estimate_hours,
+        status,
+        false,
+        data.schedule.as_ref(),
+    )?;
+
     write_task(&task_dir, status, &data)?;
 
     Ok(format!("Created task {new_id}: {title} [{status}]"))
@@ -122,6 +148,7 @@ fn handle_upsert_create(
     task_id: &str,
     task_val: &Value,
     arguments: &Value,
+    require_estimate_hours: bool,
 ) -> Result<String> {
     let title = task_val
         .get("title")
@@ -195,12 +222,25 @@ fn handle_upsert_create(
         extra: HashMap::new(),
     };
 
+    // Upsert-create: a brand-new task is a leaf.
+    validate_estimate_required(
+        require_estimate_hours,
+        status,
+        false,
+        data.schedule.as_ref(),
+    )?;
+
     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> {
+fn handle_update(
+    tasks_dir: &std::path::Path,
+    task_id: &str,
+    task_val: &Value,
+    require_estimate_hours: bool,
+) -> Result<String> {
     let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
         .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
 
@@ -288,6 +328,15 @@ fn handle_update(tasks_dir: &std::path::Path, task_id: &str, task_val: &Value) -
         validate_skipped_transition(&task_dir, &data)?;
     }
 
+    // Parent tasks (with children) are exempt; only leaf tasks need an estimate.
+    let has_children = task_has_children(&task_dir)?;
+    validate_estimate_required(
+        require_estimate_hours,
+        new_status,
+        has_children,
+        data.schedule.as_ref(),
+    )?;
+
     data.updated_at = Some(Utc::now().to_rfc3339());
 
     if let Some((old_path, _)) = find_task_file(&task_dir)? {

package/src/mcp/tools.rs

@@ -644,6 +644,24 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_get_referral".to_string(),
+            description: "Get the full details of a single incoming referral by ID (summary, details, tasks with done_criteria, priority, context, status). Use this instead of reading .handoff/referrals/*.json directly.".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 retrieve (full id or a unique prefix)."
+                    }
+                },
+                "required": ["referral_id"]
+            }),
+        },
         ToolDefinition {
             name: "handoff_update_referral".to_string(),
             description: "Update the status of an incoming referral (open -> acknowledged -> resolved).".to_string(),
@@ -1005,6 +1023,65 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "memory_save".to_string(),
+            description: "Save a long-lived project memory (lesson/rule/convention/gotcha) that future sessions should respect. Detects exact and near-duplicate memories: an exact match is reported (not rewritten), a near-duplicate is returned as a 'conflict' with both bodies for you to merge (call again with merge_into=<id> and absorb_ids=[…]) or save separately with force=true. Returns a JSON string.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "text": { "type": "string", "description": "The memory body (any language). Required, non-empty." },
+                    "kind": { "type": "string", "description": "Memory kind.", "enum": ["lesson", "rule", "convention", "gotcha"], "default": "lesson" },
+                    "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional tags; also indexed for similarity." },
+                    "scope_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes this memory applies to (e.g. 'src/storage/'). Boosts relevance when a query touches a matching file." },
+                    "merge_into": { "type": "string", "description": "Commit an AI merge: overwrite this memory id with `text` and absorb `absorb_ids`." },
+                    "absorb_ids": { "type": "array", "items": { "type": "string" }, "description": "Memory ids to delete and record as superseded when merging." },
+                    "force": { "type": "boolean", "description": "Save even if a near-duplicate exists (skip the conflict response).", "default": false }
+                },
+                "required": ["text"]
+            }),
+        },
+        ToolDefinition {
+            name: "memory_query".to_string(),
+            description: "Return the project memories most relevant to the given text/file (BM25 + scope-path boosting). Intended for automatic injection via hooks, but callable directly. Returns a JSON string {\"memories\":[{id,text,kind,score}],\"injected_count\"}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "session_id": { "type": "string", "description": "Hook session id. When given, memories already injected this session (same content hash) are filtered out; an edited memory is re-injected." },
+                    "text": { "type": "string", "description": "The current prompt or context text to match against." },
+                    "tool_name": { "type": "string", "description": "Name of the tool about to run (e.g. 'Edit'); added to the query." },
+                    "file_paths": { "type": "array", "items": { "type": "string" }, "description": "File paths in play; basenames are added to the query and scope_paths are matched against these." },
+                    "limit": { "type": "integer", "description": "Maximum memories to return.", "default": 5 },
+                    "mark_injected": { "type": "boolean", "description": "Record returned memories in the session sidecar and bump their hit_count/last_referenced_at. Requires session_id.", "default": true }
+                },
+                "required": ["text"]
+            }),
+        },
+        ToolDefinition {
+            name: "memory_delete".to_string(),
+            description: "Delete a project memory by id (full id or unique prefix). Use for AI-driven cleanup of stale memories. Returns a JSON string {\"status\":\"deleted\",\"id\"}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "id": { "type": "string", "description": "Memory id to delete (full id or unique prefix)." }
+                },
+                "required": ["id"]
+            }),
+        },
+        ToolDefinition {
+            name: "memory_cleanup".to_string(),
+            description: "Housekeep the project memory store (intended for SessionStart). Silently merges exact duplicates (lossless), then returns recommendations the AI should act on: near-duplicate clusters (merge with memory_save merge_into=…) and stale memories (consider memory_delete). Also garbage-collects old per-session injection sidecars. Returns a JSON string {\"auto_merged_exact\":n,\"cleanup_recommendations\":{\"similar_clusters\":[…],\"stale\":[…]},\"injected_sidecars_removed\":k}.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
+                    "apply_exact_merges": { "type": "boolean", "description": "Auto-merge exact-duplicate memories (same content hash). Lossless and safe.", "default": true },
+                    "stale_days": { "type": "integer", "description": "Flag memories not referenced for this many days as stale recommendations.", "default": 60 }
+                }
+            }),
+        },
     ]
 }
 

package/src/storage/config.rs

@@ -49,8 +49,37 @@ pub struct SettingsConfig {
     pub done_task_limit: u32,
     #[serde(default = "default_auto_git_summary")]
     pub auto_git_summary: bool,
+    /// Require `estimate_hours` when creating/updating leaf tasks. Default true.
+    #[serde(default = "default_require_estimate_hours")]
+    pub require_estimate_hours: bool,
+    /// Multiplier applied to AI-entered `estimate_hours` to derive the
+    /// adjusted (AI-effort) estimate at aggregation time. Default 0.2.
+    #[serde(default = "default_ai_estimate_multiplier")]
+    pub ai_estimate_multiplier: f64,
     #[serde(default)]
     pub context_files: Vec<String>,
+    /// Master switch for the memory feature (save/query/cleanup). Default true.
+    #[serde(default = "default_memory_enabled")]
+    pub memory_enabled: bool,
+    /// Jaccard threshold above which `memory_save` treats a save as a
+    /// near-duplicate `conflict` for the AI to merge. Default 0.72.
+    #[serde(default = "default_memory_dup_threshold")]
+    pub memory_dup_threshold: f64,
+    /// BM25 relevance floor for `memory_query`; scores below are not returned.
+    /// Default 0.5.
+    #[serde(default = "default_memory_query_min_score")]
+    pub memory_query_min_score: f64,
+    /// Maximum number of memories `memory_query` returns per call. Default 5.
+    #[serde(default = "default_memory_query_limit")]
+    pub memory_query_limit: u32,
+    /// Days after which an un(re)referenced memory is flagged `stale` by
+    /// `memory_cleanup`. Default 60.
+    #[serde(default = "default_memory_stale_days")]
+    pub memory_stale_days: i64,
+    /// Age (days) past which `memory_cleanup` garbage-collects a per-session
+    /// `injected/` sidecar. Default 14.
+    #[serde(default = "default_memory_injected_gc_days")]
+    pub memory_injected_gc_days: i64,
     #[serde(default)]
     pub custom_fields: HashMap<String, toml::Value>,
 }
@@ -190,6 +219,38 @@ fn default_auto_git_summary() -> bool {
     true
 }
 
+fn default_require_estimate_hours() -> bool {
+    true
+}
+
+fn default_ai_estimate_multiplier() -> f64 {
+    0.2
+}
+
+fn default_memory_enabled() -> bool {
+    true
+}
+
+fn default_memory_dup_threshold() -> f64 {
+    0.72
+}
+
+fn default_memory_query_min_score() -> f64 {
+    0.5
+}
+
+fn default_memory_query_limit() -> u32 {
+    5
+}
+
+fn default_memory_stale_days() -> i64 {
+    60
+}
+
+fn default_memory_injected_gc_days() -> i64 {
+    14
+}
+
 fn default_scan_dirs() -> Vec<String> {
     vec!["~/pro/".to_string()]
 }
@@ -200,7 +261,15 @@ impl Default for SettingsConfig {
             history_limit: default_history_limit(),
             done_task_limit: default_done_task_limit(),
             auto_git_summary: default_auto_git_summary(),
+            require_estimate_hours: default_require_estimate_hours(),
+            ai_estimate_multiplier: default_ai_estimate_multiplier(),
             context_files: Vec::new(),
+            memory_enabled: default_memory_enabled(),
+            memory_dup_threshold: default_memory_dup_threshold(),
+            memory_query_min_score: default_memory_query_min_score(),
+            memory_query_limit: default_memory_query_limit(),
+            memory_stale_days: default_memory_stale_days(),
+            memory_injected_gc_days: default_memory_injected_gc_days(),
             custom_fields: HashMap::new(),
         }
     }