handoff-mcp-server 0.2.0 → 0.3.0

package/src/mcp/tools.rs

@@ -156,6 +156,50 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_get_task".to_string(),
+            description: "Get full task details (notes, done_criteria, labels, links) by task ID. Use when list_tasks summary is not enough.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "task_id": {
+                        "type": "string",
+                        "description": "Task ID to retrieve (e.g. 't1', 't1.2')."
+                    }
+                },
+                "required": ["task_id"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_check_criterion".to_string(),
+            description: "Toggle a single done_criteria item by index. No need to resend the entire criteria list.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "task_id": {
+                        "type": "string",
+                        "description": "Task ID containing the criterion."
+                    },
+                    "criterion_index": {
+                        "type": "integer",
+                        "description": "0-based index of the done_criteria item to toggle."
+                    },
+                    "checked": {
+                        "type": "boolean",
+                        "description": "true to mark as checked, false to uncheck."
+                    }
+                },
+                "required": ["task_id", "criterion_index", "checked"]
+            }),
+        },
         ToolDefinition {
             name: "handoff_update_task".to_string(),
             description: "Add, update, or move a task. Manages the tasks/ directory structure.".to_string(),
@@ -170,7 +214,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "type": "object",
                         "properties": {
                             "id": { "type": "string", "description": "Task ID. Omit for new task (auto-generated)." },
-                            "title": { "type": "string" },
+                            "title": { "type": "string", "description": "Required for new tasks. Optional when updating (id present)." },
                             "status": {
                                 "type": "string",
                                 "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
@@ -200,7 +244,6 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                                 }
                             }
                         },
-                        "required": ["title"]
                     },
                     "parent_id": {
                         "type": "string",
@@ -279,7 +322,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                         "properties": {
                             "description": {
                                 "type": "string",
-                                "description": "What is being imported (e.g. 'tmp/260601-sprint-handoff.md からの移行')"
+                                "description": "What is being imported (e.g. 'Migration from tmp/260601-sprint-handoff.md')"
                             },
                             "format": {
                                 "type": "string",
@@ -427,6 +470,114 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                 }
             }),
         },
+        ToolDefinition {
+            name: "handoff_refer".to_string(),
+            description: "Send a cross-project referral (improvement request, bug report, work request) to another project's .handoff/. The target project sees it on load_context.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Source project directory (sender). Defaults to current working directory."
+                    },
+                    "target_project": {
+                        "type": "string",
+                        "description": "Target project name (resolved via scan_dirs). Use this OR target_project_dir."
+                    },
+                    "target_project_dir": {
+                        "type": "string",
+                        "description": "Target project directory path (absolute). Takes precedence over target_project."
+                    },
+                    "referral_type": {
+                        "type": "string",
+                        "enum": ["improvement", "bug", "request", "info"],
+                        "description": "Type of referral. Defaults to 'request'."
+                    },
+                    "summary": {
+                        "type": "string",
+                        "description": "One-line summary of the referral."
+                    },
+                    "details": {
+                        "type": "string",
+                        "description": "Detailed description of the referral."
+                    },
+                    "priority": {
+                        "type": "string",
+                        "enum": ["low", "medium", "high"],
+                        "description": "Priority of the referral."
+                    },
+                    "tasks": {
+                        "type": "array",
+                        "description": "Suggested tasks for the target project.",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "title": { "type": "string" },
+                                "priority": { "type": "string", "enum": ["low", "medium", "high"] },
+                                "done_criteria": {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "object",
+                                        "properties": {
+                                            "item": { "type": "string" },
+                                            "checked": { "type": "boolean" }
+                                        },
+                                        "required": ["item"]
+                                    }
+                                }
+                            },
+                            "required": ["title"]
+                        }
+                    },
+                    "context": {
+                        "type": "object",
+                        "description": "Additional context (branch, commit, references)."
+                    }
+                },
+                "required": ["summary"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_list_referrals".to_string(),
+            description: "List incoming referrals from other projects with optional status filter.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "status_filter": {
+                        "type": "string",
+                        "enum": ["open", "acknowledged", "resolved"],
+                        "description": "Filter by referral status."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_update_referral".to_string(),
+            description: "Update the status of an incoming referral (open -> acknowledged -> resolved).".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 update."
+                    },
+                    "status": {
+                        "type": "string",
+                        "enum": ["open", "acknowledged", "resolved"],
+                        "description": "New status for the referral."
+                    }
+                },
+                "required": ["referral_id", "status"]
+            }),
+        },
     ]
 }
 

package/src/storage/mod.rs

@@ -1,5 +1,6 @@
 pub mod config;
 pub mod git;
+pub mod referrals;
 pub mod sessions;
 pub mod tasks;
 
@@ -7,6 +8,15 @@ use std::path::{Path, PathBuf};
 
 use anyhow::{Context, Result};
 
+pub 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()
+}
+
 pub fn handoff_dir(project_dir: &Path) -> PathBuf {
     project_dir.join(".handoff")
 }

package/src/storage/referrals.rs

@@ -0,0 +1,210 @@
+use std::path::{Path, PathBuf};
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+const VALID_REFERRAL_TYPES: &[&str] = &["improvement", "bug", "request", "info"];
+const VALID_REFERRAL_STATUSES: &[&str] = &["open", "acknowledged", "resolved"];
+
+pub fn is_valid_referral_type(t: &str) -> bool {
+    VALID_REFERRAL_TYPES.contains(&t)
+}
+
+pub fn is_valid_referral_status(s: &str) -> bool {
+    VALID_REFERRAL_STATUSES.contains(&s)
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReferralData {
+    pub id: String,
+    pub source_project: String,
+    pub source_project_dir: String,
+    pub created_at: String,
+    pub referral_type: String,
+    pub summary: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub details: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub priority: Option<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub tasks: Vec<Value>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub context: Option<Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReferralSummary {
+    pub id: String,
+    pub source_project: String,
+    pub referral_type: String,
+    pub summary: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub priority: Option<String>,
+    pub status: String,
+    pub created_at: String,
+}
+
+pub fn write_referral(referrals_dir: &Path, data: &ReferralData) -> Result<PathBuf> {
+    std::fs::create_dir_all(referrals_dir).with_context(|| {
+        format!(
+            "Failed to create referrals dir: {}",
+            referrals_dir.display()
+        )
+    })?;
+
+    let slug = source_to_slug(&data.source_project);
+    let id_suffix = data.id.replace("ref-", "");
+    let filename = format!("{id_suffix}-{slug}.open.json");
+    let file_path = referrals_dir.join(&filename);
+
+    let content = serde_json::to_string_pretty(data).context("Failed to serialize referral")?;
+    std::fs::write(&file_path, content)
+        .with_context(|| format!("Failed to write referral: {}", file_path.display()))?;
+
+    Ok(file_path)
+}
+
+pub fn read_referrals(
+    referrals_dir: &Path,
+    status_filter: Option<&str>,
+) -> Result<Vec<(ReferralData, String)>> {
+    let mut results = Vec::new();
+
+    if !referrals_dir.exists() {
+        return Ok(results);
+    }
+
+    let mut entries: Vec<_> = std::fs::read_dir(referrals_dir)?
+        .filter_map(|e| e.ok())
+        .collect();
+    entries.sort_by_key(|e| e.file_name());
+
+    for entry in entries {
+        let name = entry.file_name().to_string_lossy().to_string();
+        if let Some(status) = parse_referral_status(&name) {
+            if let Some(filter) = status_filter {
+                if status != filter {
+                    continue;
+                }
+            }
+            let content = std::fs::read_to_string(entry.path())
+                .with_context(|| format!("Failed to read referral: {}", entry.path().display()))?;
+            let data: ReferralData = serde_json::from_str(&content)
+                .with_context(|| format!("Failed to parse referral: {}", entry.path().display()))?;
+            results.push((data, status));
+        }
+    }
+
+    Ok(results)
+}
+
+pub fn read_referral_summaries(
+    referrals_dir: &Path,
+    status_filter: Option<&str>,
+) -> Result<Vec<ReferralSummary>> {
+    let referrals = read_referrals(referrals_dir, status_filter)?;
+    Ok(referrals
+        .into_iter()
+        .map(|(data, status)| ReferralSummary {
+            id: data.id,
+            source_project: data.source_project,
+            referral_type: data.referral_type,
+            summary: data.summary,
+            priority: data.priority,
+            status,
+            created_at: data.created_at,
+        })
+        .collect())
+}
+
+pub fn change_referral_status(
+    referrals_dir: &Path,
+    referral_id: &str,
+    new_status: &str,
+) -> Result<()> {
+    if !is_valid_referral_status(new_status) {
+        anyhow::bail!(
+            "Invalid referral status: '{new_status}'. Must be one of: {}",
+            VALID_REFERRAL_STATUSES.join(", ")
+        );
+    }
+
+    let (old_path, old_status) = find_referral_file(referrals_dir, referral_id)?
+        .ok_or_else(|| anyhow::anyhow!("Referral not found: {referral_id}"))?;
+
+    if old_status == new_status {
+        return Ok(());
+    }
+
+    let old_name = old_path
+        .file_name()
+        .ok_or_else(|| anyhow::anyhow!("Invalid referral path"))?
+        .to_string_lossy()
+        .to_string();
+
+    let new_name = old_name.replace(
+        &format!(".{old_status}.json"),
+        &format!(".{new_status}.json"),
+    );
+    let new_path = referrals_dir.join(&new_name);
+
+    std::fs::rename(&old_path, &new_path).with_context(|| {
+        format!(
+            "Failed to rename {} -> {}",
+            old_path.display(),
+            new_path.display()
+        )
+    })?;
+
+    Ok(())
+}
+
+pub fn find_referral_file(
+    referrals_dir: &Path,
+    referral_id: &str,
+) -> Result<Option<(PathBuf, String)>> {
+    if !referrals_dir.exists() {
+        return Ok(None);
+    }
+
+    for entry in std::fs::read_dir(referrals_dir)? {
+        let entry = entry?;
+        let name = entry.file_name().to_string_lossy().to_string();
+        if let Some(status) = parse_referral_status(&name) {
+            let content = std::fs::read_to_string(entry.path())?;
+            if let Ok(data) = serde_json::from_str::<ReferralData>(&content) {
+                if data.id == referral_id {
+                    return Ok(Some((entry.path(), status)));
+                }
+            }
+        }
+    }
+
+    Ok(None)
+}
+
+fn parse_referral_status(filename: &str) -> Option<String> {
+    let name = filename.strip_suffix(".json")?;
+    for status in VALID_REFERRAL_STATUSES {
+        if name.ends_with(&format!(".{status}")) {
+            return Some(status.to_string());
+        }
+    }
+    None
+}
+
+fn source_to_slug(source: &str) -> String {
+    let slug: String = source
+        .chars()
+        .take(30)
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c.to_ascii_lowercase()
+            } else {
+                '-'
+            }
+        })
+        .collect();
+    slug.trim_matches('-').to_string()
+}

package/src/storage/tasks.rs

@@ -56,10 +56,28 @@ const VALID_STATUSES: &[&str] = &[
     "skipped",
 ];
 
+const VALID_PRIORITIES: &[&str] = &["low", "medium", "high"];
+
 pub fn is_valid_status(status: &str) -> bool {
     VALID_STATUSES.contains(&status)
 }
 
+pub fn is_valid_priority(priority: &str) -> bool {
+    VALID_PRIORITIES.contains(&priority)
+}
+
+pub fn validate_priority(priority: Option<&str>) -> Result<()> {
+    if let Some(p) = priority {
+        if !is_valid_priority(p) {
+            anyhow::bail!(
+                "Invalid priority: '{p}'. Must be one of: {}",
+                VALID_PRIORITIES.join(", ")
+            );
+        }
+    }
+    Ok(())
+}
+
 pub fn is_terminal_status(status: &str) -> bool {
     status == "done" || status == "skipped"
 }

package/tests/mcp_protocol.rs

@@ -55,6 +55,10 @@ fn tools_list_returns_all_tools() {
         "handoff_get_config",
         "handoff_update_config",
         "handoff_dashboard",
+        "handoff_import_context",
+        "handoff_refer",
+        "handoff_list_referrals",
+        "handoff_update_referral",
     ];
 
     let tool_names: Vec<&str> = tools

package/tests/storage_tasks.rs

@@ -300,3 +300,37 @@ fn validate_skipped_child_not_terminal_fails() {
     let data = make_task("t1", "Parent");
     assert!(validate_skipped_transition(&task_dir, &data).is_err());
 }
+
+#[test]
+fn is_valid_priority_accepts_valid() {
+    assert!(is_valid_priority("low"));
+    assert!(is_valid_priority("medium"));
+    assert!(is_valid_priority("high"));
+}
+
+#[test]
+fn is_valid_priority_rejects_invalid() {
+    assert!(!is_valid_priority("critical"));
+    assert!(!is_valid_priority("urgent"));
+    assert!(!is_valid_priority(""));
+    assert!(!is_valid_priority("HIGH"));
+}
+
+#[test]
+fn validate_priority_none_is_ok() {
+    assert!(validate_priority(None).is_ok());
+}
+
+#[test]
+fn validate_priority_valid_is_ok() {
+    assert!(validate_priority(Some("low")).is_ok());
+    assert!(validate_priority(Some("medium")).is_ok());
+    assert!(validate_priority(Some("high")).is_ok());
+}
+
+#[test]
+fn validate_priority_invalid_is_err() {
+    let err = validate_priority(Some("critical")).unwrap_err();
+    assert!(err.to_string().contains("Invalid priority"));
+    assert!(err.to_string().contains("critical"));
+}

package/tests/tool_import_context.rs

@@ -375,3 +375,69 @@ fn import_source_recorded_in_environment() {
         "markdown"
     );
 }
+
+fn is_error(resp: &Value) -> bool {
+    resp["result"]["isError"].as_bool().unwrap_or(false)
+}
+
+#[test]
+fn import_invalid_priority_rejected() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "bad priority import" },
+            "tasks": [
+                { "title": "Task", "priority": "urgent" }
+            ]
+        }),
+    );
+    assert!(is_error(&resp));
+    let text = get_text(&resp);
+    assert!(text.contains("Invalid priority"));
+}
+
+#[test]
+fn import_valid_priorities_accepted() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "valid priorities" },
+            "tasks": [
+                { "title": "Low", "priority": "low" },
+                { "title": "Medium", "priority": "medium" },
+                { "title": "High", "priority": "high" }
+            ]
+        }),
+    );
+    assert!(!is_error(&resp), "error: {}", get_text(&resp));
+    let text = get_text(&resp);
+    assert!(text.contains("Tasks created: 3"));
+}
+
+#[test]
+fn import_invalid_priority_in_child_rejected() {
+    let dir = setup_project();
+    let resp = call_tool(
+        "handoff_import_context",
+        json!({
+            "project_dir": dir.path().to_string_lossy(),
+            "source": { "description": "bad child priority" },
+            "tasks": [
+                {
+                    "title": "Parent",
+                    "priority": "high",
+                    "children": [
+                        { "title": "Child", "priority": "ASAP" }
+                    ]
+                }
+            ]
+        }),
+    );
+    assert!(is_error(&resp));
+    let text = get_text(&resp);
+    assert!(text.contains("Invalid priority"));
+}