handoff-mcp-server 0.13.1 → 0.15.0

package/src/cli.rs

@@ -0,0 +1,551 @@
+//! CLI subcommand routing layer.
+//!
+//! Translates `handoff-mcp <group> <action> [--key value ...]` into a
+//! `serde_json::Value` and delegates to the existing MCP handler. All output
+//! goes to stdout as JSON for programmatic consumption.
+
+use serde_json::{json, Value};
+
+use crate::mcp::handlers;
+
+/// Entry point called from `main()` when `args[1]` matches a known CLI group.
+/// Returns the exit code (0 = success, 1 = error).
+pub fn run(args: &[String]) -> i32 {
+    let result = dispatch(args);
+    match result {
+        Ok(output) => {
+            println!("{output}");
+            0
+        }
+        Err(e) => {
+            let err = json!({ "error": format!("{e:#}") });
+            println!(
+                "{}",
+                serde_json::to_string_pretty(&err).unwrap_or_else(|_| err.to_string())
+            );
+            1
+        }
+    }
+}
+
+fn dispatch(args: &[String]) -> anyhow::Result<String> {
+    let group = args.first().map(String::as_str).unwrap_or("");
+    let second = args.get(1).map(String::as_str).unwrap_or("");
+
+    // If the second arg is a flag (starts with --), treat it as no action.
+    let (action, flag_args) = if second.starts_with("--") || second.is_empty() {
+        ("", if args.len() > 1 { &args[1..] } else { &[][..] })
+    } else {
+        (second, if args.len() > 2 { &args[2..] } else { &[][..] })
+    };
+
+    // --help anywhere in the flags → show group help.
+    if flag_args.iter().any(|a| a == "--help" || a == "-h") {
+        print_group_help(group);
+        std::process::exit(0);
+    }
+
+    let tool_name = resolve_tool_name(group, action)?;
+    let arguments = parse_flags(flag_args, &tool_name)?;
+
+    // Delegate to the single dispatch table in handlers::handle_tool_call.
+    // It returns a JsonRpcResponse wrapping the result; we extract the text.
+    let response = handlers::handle_tool_call(&tool_name, &arguments);
+    extract_tool_result(response)
+}
+
+/// Extract the content text from a JsonRpcResponse returned by the MCP handler
+/// dispatch. Surfaces handler-level errors as `Err` so the CLI prints them with
+/// exit code 1.
+fn extract_tool_result(response: crate::mcp::types::JsonRpcResponse) -> anyhow::Result<String> {
+    let result = response.result.ok_or_else(|| {
+        let msg = response
+            .error
+            .map(|e| e.message)
+            .unwrap_or_else(|| "Unknown error".to_string());
+        anyhow::anyhow!("{msg}")
+    })?;
+
+    if result
+        .get("isError")
+        .and_then(|v| v.as_bool())
+        .unwrap_or(false)
+    {
+        let text = result
+            .get("content")
+            .and_then(|c| c.as_array())
+            .and_then(|arr| arr.first())
+            .and_then(|item| item.get("text"))
+            .and_then(|t| t.as_str())
+            .unwrap_or("Unknown error");
+        anyhow::bail!("{text}");
+    }
+
+    let text = result
+        .get("content")
+        .and_then(|c| c.as_array())
+        .and_then(|arr| arr.first())
+        .and_then(|item| item.get("text"))
+        .and_then(|t| t.as_str())
+        .unwrap_or("")
+        .to_string();
+
+    Ok(text)
+}
+
+/// Map `(group, action)` to the internal MCP tool name.
+fn resolve_tool_name(group: &str, action: &str) -> anyhow::Result<String> {
+    let name = match (group, action) {
+        // init (no action needed)
+        ("init", "") => "handoff_init",
+
+        // task
+        ("task", "list") => "handoff_list_tasks",
+        ("task", "get") => "handoff_get_task",
+        ("task", "update" | "create") => "handoff_update_task",
+        ("task", "check") => "handoff_check_criterion",
+        ("task", "bulk-update") => "handoff_bulk_update_tasks",
+        ("task", "log-time") => "handoff_log_time",
+        ("task", "import") => "handoff_import_context",
+
+        // session
+        ("session", "load") => "handoff_load_context",
+        ("session", "save") => "handoff_save_context",
+        ("session", "list") => "handoff_list_sessions",
+        ("session", "get") => "handoff_get_session",
+        ("session", "update") => "handoff_update_session",
+
+        // config
+        ("config", "get") => "handoff_get_config",
+        ("config", "update") => "handoff_update_config",
+
+        // memory
+        ("memory", "save") => "handoff_memory_save",
+        ("memory", "query") => "handoff_memory_query",
+        ("memory", "delete") => "handoff_memory_delete",
+        ("memory", "cleanup") => "handoff_memory_cleanup",
+
+        // referral
+        ("referral", "send" | "refer") => "handoff_refer",
+        ("referral", "list") => "handoff_list_referrals",
+        ("referral", "get") => "handoff_get_referral",
+        ("referral", "update") => "handoff_update_referral",
+
+        // assignee
+        ("assignee", "list") => "handoff_list_assignees",
+        ("assignee", "add") => "handoff_add_assignee",
+        ("assignee", "update") => "handoff_update_assignee",
+        ("assignee", "remove") => "handoff_remove_assignee",
+
+        // milestone
+        ("milestone", "list") => "handoff_list_milestones",
+        ("milestone", "add") => "handoff_add_milestone",
+        ("milestone", "update") => "handoff_update_milestone",
+        ("milestone", "remove") => "handoff_remove_milestone",
+
+        // calendar / labels / project
+        ("calendar", "update") => "handoff_update_calendar",
+        ("labels", "update") => "handoff_update_labels",
+        ("project", "start") => "handoff_start_project",
+
+        // metrics / capacity / schedule
+        ("metrics", "" | "get") => "handoff_get_metrics",
+        ("capacity", "" | "get") => "handoff_get_capacity",
+        ("schedule", "" | "auto") => "handoff_auto_schedule",
+
+        // dashboard
+        ("dashboard", "") => "handoff_dashboard",
+
+        // timer
+        ("timer", "start") => "handoff_timer_start",
+        ("timer", "stop") => "handoff_timer_stop",
+        ("timer", "get") => "handoff_timer_get_time",
+
+        _ => {
+            if action.is_empty() {
+                anyhow::bail!(
+                    "Unknown command: {group}\n\nRun `handoff-mcp --help` for available commands."
+                );
+            } else {
+                anyhow::bail!(
+                    "Unknown command: {group} {action}\n\nRun `handoff-mcp {group} --help` for available actions."
+                );
+            }
+        }
+    };
+    Ok(name.to_string())
+}
+
+/// Parse `--key value` flags into a JSON object.
+///
+/// Conventions:
+/// - `--key value` → `{"key": "value"}` (string)
+/// - `--key 42` → `{"key": 42}` (number if parseable)
+/// - `--key true/false` → `{"key": true}` (bool)
+/// - `--key a,b,c` → `{"key": ["a","b","c"]}` (comma-separated → array)
+/// - `--json-key '{"a":1}'` → parsed as JSON value (for nested objects)
+/// - `--flag` (no value or next arg starts with `--`) → `{"flag": true}`
+///
+/// Dashes in key names are converted to underscores (e.g. `--project-dir` →
+/// `project_dir`) to match the MCP parameter naming.
+fn parse_flags(args: &[String], tool_name: &str) -> anyhow::Result<Value> {
+    let mut map = serde_json::Map::new();
+    let mut i = 0;
+
+    while i < args.len() {
+        let arg = &args[i];
+        if !arg.starts_with("--") {
+            anyhow::bail!("Unexpected positional argument: {arg}");
+        }
+        let key = arg[2..].replace('-', "_");
+
+        let value = if i + 1 < args.len() && !args[i + 1].starts_with("--") {
+            i += 1;
+            parse_value(&args[i], &key)
+        } else {
+            Value::Bool(true)
+        };
+
+        // Nest into a `task` or `updates` object for tools that expect it.
+        insert_value(&mut map, &key, value, tool_name);
+        i += 1;
+    }
+
+    Ok(Value::Object(map))
+}
+
+/// Insert a value into the correct position in the JSON object.
+///
+/// Some MCP tools expect nested objects (e.g. `handoff_update_task` wants
+/// `{"task": {"id": ..., "title": ...}}`). This function routes known fields
+/// into the right nesting level so the CLI user writes flat flags:
+/// `--id t1 --title "foo"` instead of `--task '{"id":"t1","title":"foo"}'`.
+fn insert_value(
+    map: &mut serde_json::Map<String, Value>,
+    key: &str,
+    value: Value,
+    tool_name: &str,
+) {
+    match tool_name {
+        "handoff_update_task" => {
+            // Fields that go into the top-level `task` object.
+            let task_fields = [
+                "id",
+                "title",
+                "status",
+                "notes",
+                "priority",
+                "labels",
+                "links",
+                "done_criteria",
+                "assignee",
+                "dependencies",
+                "order",
+            ];
+            // Fields that go into `task.schedule`.
+            let schedule_fields = [
+                "start_date",
+                "due_date",
+                "estimate_hours",
+                "actual_hours",
+                "remaining_hours",
+                "milestone",
+                "pinned",
+            ];
+
+            if task_fields.contains(&key) {
+                let task = map
+                    .entry("task")
+                    .or_insert_with(|| json!({}))
+                    .as_object_mut()
+                    .expect("task must be object");
+                task.insert(key.to_string(), value);
+            } else if schedule_fields.contains(&key) {
+                let task = map
+                    .entry("task")
+                    .or_insert_with(|| json!({}))
+                    .as_object_mut()
+                    .expect("task must be object");
+                let schedule = task
+                    .entry("schedule")
+                    .or_insert_with(|| json!({}))
+                    .as_object_mut()
+                    .expect("schedule must be object");
+                schedule.insert(key.to_string(), value);
+            } else {
+                map.insert(key.to_string(), value);
+            }
+        }
+        _ => {
+            map.insert(key.to_string(), value);
+        }
+    }
+}
+
+/// Fields that are always strings even when they look like numbers. Handlers
+/// call `.as_str()` on these, so coercing "42" to `Number(42)` would silently
+/// break them.
+const STRING_FIELDS: &[&str] = &[
+    "task_id",
+    "id",
+    "session_id",
+    "referral_id",
+    "key",
+    "name",
+    "text",
+    "kind",
+    "summary",
+    "status",
+    "status_filter",
+    "assignee_filter",
+    "milestone_filter",
+    "priority_filter",
+    "label_filter",
+    "assignee",
+    "priority",
+    "project_dir",
+    "project_name",
+    "description",
+    "notes",
+    "title",
+    "display_name",
+    "color",
+    "target_project",
+    "target_project_dir",
+    "referral_type",
+    "details",
+    "merge_into",
+    "tool_name",
+    "start_date",
+    "due_date",
+    "date",
+    "end_date",
+    "schedule_mode",
+    "session_status",
+    "close_session_id",
+    "pause_session_id",
+    "move_to",
+    "parent_id",
+    "milestone",
+];
+
+/// Fields that are always numeric. Only these are coerced from string to number.
+const NUMERIC_FIELDS: &[&str] = &[
+    "hours",
+    "estimate_hours",
+    "actual_hours",
+    "remaining_hours",
+    "limit",
+    "criterion_index",
+    "order",
+    "work_hours_per_day",
+    "overwork_limit_percent",
+    "max_utilization",
+    "stale_days",
+    "checklist_index",
+];
+
+/// Parse a CLI flag value into a JSON type, using the field name to decide
+/// whether numeric coercion is appropriate.
+fn parse_value(s: &str, key: &str) -> Value {
+    // Try JSON parse first (handles objects, arrays, quoted strings).
+    if let Ok(v) = serde_json::from_str::<Value>(s) {
+        if v.is_object() || v.is_array() {
+            return v;
+        }
+    }
+
+    // Known string fields — never coerce to number/bool.
+    if STRING_FIELDS.contains(&key) {
+        return Value::String(s.to_string());
+    }
+
+    // Boolean.
+    if s == "true" {
+        return Value::Bool(true);
+    }
+    if s == "false" {
+        return Value::Bool(false);
+    }
+
+    // Numeric coercion — only for known numeric fields.
+    if NUMERIC_FIELDS.contains(&key) {
+        if let Ok(n) = s.parse::<i64>() {
+            return Value::Number(n.into());
+        }
+        if let Ok(f) = s.parse::<f64>() {
+            if let Some(n) = serde_json::Number::from_f64(f) {
+                return Value::Number(n);
+            }
+        }
+    }
+
+    // Comma-separated array (only if no spaces and contains comma).
+    if s.contains(',') && !s.contains(' ') {
+        let arr: Vec<Value> = s.split(',').map(|p| Value::String(p.to_string())).collect();
+        return Value::Array(arr);
+    }
+
+    Value::String(s.to_string())
+}
+
+/// All known CLI groups (for help display).
+pub const GROUPS: &[(&str, &str)] = &[
+    ("init", "Initialize handoff tracking for a project"),
+    (
+        "task",
+        "Task management (list, get, update, check, bulk-update, log-time, import)",
+    ),
+    (
+        "session",
+        "Session management (load, save, list, get, update)",
+    ),
+    ("config", "Configuration (get, update)"),
+    ("memory", "Project memory (save, query, delete, cleanup)"),
+    (
+        "referral",
+        "Cross-project referrals (send, list, get, update)",
+    ),
+    ("assignee", "Team members (list, add, update, remove)"),
+    ("milestone", "Milestones (list, add, update, remove)"),
+    ("calendar", "Calendar settings (update)"),
+    ("labels", "Project labels (update)"),
+    ("project", "Project lifecycle (start)"),
+    ("metrics", "Project metrics"),
+    ("capacity", "Work capacity"),
+    ("schedule", "Auto-scheduler"),
+    ("dashboard", "Cross-project dashboard"),
+    ("timer", "Timer coordination (start, stop, get)"),
+];
+
+pub fn print_cli_help() {
+    println!(
+        "handoff-mcp v{version} — CLI API
+
+USAGE:
+    handoff-mcp <command> <action> [--key value ...]
+
+COMMANDS:",
+        version = env!("CARGO_PKG_VERSION")
+    );
+    for (name, desc) in GROUPS {
+        println!("    {name:<16}{desc}");
+    }
+    println!(
+        "
+GLOBAL OPTIONS:
+    --project-dir <path>    Project directory (default: current directory)
+    --help                  Show help for a command
+
+EXAMPLES:
+    handoff-mcp memory save --text \"Always use atomic_write\" --kind lesson
+    handoff-mcp memory query --text \"atomic\" --limit 5
+    handoff-mcp task list --status-filter todo
+    handoff-mcp session load
+    handoff-mcp metrics"
+    );
+}
+
+pub fn print_group_help(group: &str) {
+    let actions: &[(&str, &str)] = match group {
+        "init" => &[("", "Initialize handoff tracking (--project-name <name>)")],
+        "task" => &[
+            ("list", "List tasks (--status-filter, --assignee-filter, --milestone-filter, --priority-filter, --label-filter)"),
+            ("get", "Get task detail (--task-id <id>)"),
+            ("update", "Create or update a task (--id, --title, --status, --priority, --assignee, ...)"),
+            ("check", "Toggle done_criteria item (--task-id, --criterion-index, --checked)"),
+            ("bulk-update", "Bulk update tasks (--updates '[{...}]')"),
+            ("log-time", "Log hours worked (--task-id, --hours)"),
+            ("import", "Import context from document (--source '{...}')"),
+        ],
+        "session" => &[
+            ("load", "Load context at session start (--session-id)"),
+            ("save", "Save context at session end (--summary, --session-status, ...)"),
+            ("list", "List sessions (--status-filter, --limit)"),
+            ("get", "Get session detail (--session-id)"),
+            ("update", "Update active session (--add-decision '{...}', ...)"),
+        ],
+        "config" => &[
+            ("get", "Read project config"),
+            ("update", "Update config (--updates '{...}')"),
+        ],
+        "memory" => &[
+            ("save", "Save a memory (--text, --kind, --tags, --scope-paths, --force)"),
+            ("query", "Query memories (--text, --limit, --session-id)"),
+            ("delete", "Delete a memory (--id)"),
+            ("cleanup", "Housekeep memory store (--apply-exact-merges, --stale-days)"),
+        ],
+        "referral" => &[
+            ("send", "Send a referral to another project (--summary, --target-project, ...)"),
+            ("list", "List incoming referrals (--status-filter)"),
+            ("get", "Get referral detail (--referral-id)"),
+            ("update", "Update referral status (--referral-id, --status)"),
+        ],
+        "assignee" => &[
+            ("list", "List team members"),
+            ("add", "Add assignee (--key, --display-name, ...)"),
+            ("update", "Update assignee (--key, --display-name, ...)"),
+            ("remove", "Remove assignee (--key)"),
+        ],
+        "milestone" => &[
+            ("list", "List milestones"),
+            ("add", "Add milestone (--name, --date, --description)"),
+            ("update", "Update milestone (--name, --date, --description)"),
+            ("remove", "Remove milestone (--name)"),
+        ],
+        "calendar" => &[
+            ("update", "Update calendar settings (--work-hours-per-day, --closed-weekdays, ...)"),
+        ],
+        "labels" => &[
+            ("update", "Set project labels (--labels a,b,c)"),
+        ],
+        "project" => &[
+            ("start", "Set project start date (--start-date, --shift-dates)"),
+        ],
+        "metrics" => &[
+            ("", "Get project metrics (--assignee)"),
+        ],
+        "capacity" => &[
+            ("", "Get work capacity (--start-date, --end-date, --assignee)"),
+        ],
+        "schedule" => &[
+            ("", "Run auto-scheduler (--dry-run, --assignee-filter, --start-date)"),
+        ],
+        "dashboard" => &[
+            ("", "Show cross-project dashboard (--scan-dirs, --include-completed)"),
+        ],
+        "timer" => &[
+            ("start", "Start timer for task (--task-id)"),
+            ("stop", "Stop timer for task (--task-id)"),
+            ("get", "Get timer state (--task-id)"),
+        ],
+        _ => {
+            eprintln!("Unknown command group: {group}");
+            eprintln!("Run `handoff-mcp --help` for available commands.");
+            return;
+        }
+    };
+
+    let desc = GROUPS
+        .iter()
+        .find(|(n, _)| *n == group)
+        .map(|(_, d)| *d)
+        .unwrap_or("");
+    println!("handoff-mcp {group} — {desc}\n");
+    println!("ACTIONS:");
+    for (action, help) in actions {
+        if action.is_empty() {
+            println!("    (default)       {help}");
+        } else {
+            println!("    {action:<16}{help}");
+        }
+    }
+    println!(
+        "\nGLOBAL OPTIONS:\n    --project-dir <path>    Project directory (default: current directory)"
+    );
+}
+
+/// Check if this group/action is a known CLI command.
+pub fn is_cli_command(first_arg: &str) -> bool {
+    GROUPS.iter().any(|(name, _)| *name == first_arg)
+}

package/src/lib.rs

@@ -1,3 +1,4 @@
+pub mod cli;
 pub mod mcp;
 pub mod setup;
 pub mod storage;

package/src/main.rs

@@ -25,6 +25,16 @@ fn main() {
                 return;
             }
             other => {
+                if handoff_mcp::cli::is_cli_command(other) {
+                    let cli_args: Vec<String> = args[1..].to_vec();
+                    // Handle --help for group
+                    if cli_args.len() >= 2 && (cli_args[1] == "--help" || cli_args[1] == "-h") {
+                        handoff_mcp::cli::print_group_help(&cli_args[0]);
+                        return;
+                    }
+                    let code = handoff_mcp::cli::run(&cli_args);
+                    std::process::exit(code);
+                }
                 eprintln!("Unknown command: {other}");
                 eprintln!("Run `handoff-mcp --help` for usage.");
                 std::process::exit(1);
@@ -58,19 +68,19 @@ fn main() {
 }
 
 fn print_help() {
+    handoff_mcp::cli::print_cli_help();
     println!(
-        "handoff-mcp v{version}
-MCP server for AI session handoff
-
-USAGE:
+        "
+SERVER MODE:
     handoff-mcp              Start the MCP server (stdio transport)
+
+SETUP:
     handoff-mcp setup        Install memory auto-injection hooks into Claude Code
     handoff-mcp setup --check    Check if hooks are installed
     handoff-mcp setup --uninstall    Remove handoff hooks from Claude Code
 
 OPTIONS:
     -h, --help       Print this help message
-    -V, --version    Print version",
-        version = env!("CARGO_PKG_VERSION")
+    -V, --version    Print version"
     );
 }

package/src/mcp/handlers/bulk_update.rs

@@ -45,7 +45,7 @@ pub fn handle(arguments: &Value) -> Result<String> {
 
 fn apply_single_update(tasks_dir: &std::path::Path, task_id: &str, update: &Value) -> Result<()> {
     let task_dir = find_task_dir_by_id(tasks_dir, task_id)?
-        .ok_or_else(|| anyhow::anyhow!("Task not found: {task_id}"))?;
+        .ok_or_else(|| anyhow::anyhow!("{}", suggest_task_id(tasks_dir, task_id)))?;
 
     let (mut data, current_status) = read_task(&task_dir)?
         .ok_or_else(|| anyhow::anyhow!("Task file not found for {task_id}"))?;

package/src/mcp/handlers/check_criterion.rs

@@ -4,7 +4,9 @@ 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};
+use crate::storage::tasks::{
+    find_task_dir_by_id, find_task_file, read_task, suggest_task_id, write_task,
+};
 
 pub fn handle(arguments: &Value) -> Result<String> {
     let project_dir = resolve_project_dir(arguments)?;
@@ -28,11 +30,8 @@ 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}. Use handoff_list_tasks to see available task IDs."
-        )
-    })?;
+    let task_dir = find_task_dir_by_id(&tasks_dir, task_id)?
+        .ok_or_else(|| anyhow::anyhow!("{}", suggest_task_id(&tasks_dir, task_id)))?;
 
     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/config.rs

@@ -53,6 +53,9 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
         "settings.memory_query_limit",
         "settings.memory_stale_days",
         "settings.memory_injected_gc_days",
+        "settings.timer_provider",
+        "settings.timer_authority_ttl_secs",
+        "settings.timer_idle_timeout_minutes",
         "dashboard.scan_dirs",
         "dashboard.exclude_patterns",
         "project.name",
@@ -179,6 +182,41 @@ pub fn handle_update(arguments: &Value) -> Result<String> {
                     config.settings.memory_injected_gc_days = n;
                     applied.push(format!("settings.memory_injected_gc_days = {n}"));
                 }
+                "settings.timer_provider" => {
+                    let Some(s) = value.as_str() else {
+                        anyhow::bail!("settings.timer_provider must be a string");
+                    };
+                    let valid = ["auto", "vscode", "mcp", "off"];
+                    if !valid.contains(&s) {
+                        anyhow::bail!(
+                            "settings.timer_provider must be one of: {}",
+                            valid.join(", ")
+                        );
+                    }
+                    config.settings.timer_provider = s.to_string();
+                    applied.push(format!("settings.timer_provider = {s}"));
+                }
+                "settings.timer_authority_ttl_secs" => {
+                    let Some(n) = value.as_u64() else {
+                        anyhow::bail!(
+                            "settings.timer_authority_ttl_secs must be a positive integer"
+                        );
+                    };
+                    if n == 0 {
+                        anyhow::bail!("settings.timer_authority_ttl_secs must be >= 1");
+                    }
+                    config.settings.timer_authority_ttl_secs = n;
+                    applied.push(format!("settings.timer_authority_ttl_secs = {n}"));
+                }
+                "settings.timer_idle_timeout_minutes" => {
+                    let Some(n) = value.as_u64() else {
+                        anyhow::bail!(
+                            "settings.timer_idle_timeout_minutes must be a non-negative integer"
+                        );
+                    };
+                    config.settings.timer_idle_timeout_minutes = n;
+                    applied.push(format!("settings.timer_idle_timeout_minutes = {n}"));
+                }
                 "dashboard.scan_dirs" => {
                     if let Some(arr) = value.as_array() {
                         config.dashboard.scan_dirs = arr