handoff-mcp-server 0.1.0

package/src/mcp/router.rs

@@ -0,0 +1,150 @@
+use serde_json::{json, Value};
+
+use super::handlers::handle_tool_call;
+use super::tools::{all_resource_definitions, all_tool_definitions};
+use super::types::{
+    InitializeResult, JsonRpcResponse, ResourcesCapability, ServerCapabilities, ServerInfo,
+    ToolsCapability, ToolsListResult, INTERNAL_ERROR, METHOD_NOT_FOUND, PROTOCOL_VERSION,
+};
+
+pub fn handle_request(method: &str, params: Option<&Value>) -> JsonRpcResponse {
+    match method {
+        "initialize" => handle_initialize(),
+        "notifications/initialized" => JsonRpcResponse {
+            jsonrpc: "2.0".to_string(),
+            id: None,
+            result: None,
+            error: None,
+        },
+        "tools/list" => handle_tools_list(),
+        "tools/call" => handle_tools_call(params),
+        "resources/list" => handle_resources_list(),
+        "resources/read" => handle_resources_read(params),
+        _ => JsonRpcResponse::error(
+            None,
+            METHOD_NOT_FOUND,
+            format!("Method not found: {method}"),
+        ),
+    }
+}
+
+fn handle_initialize() -> JsonRpcResponse {
+    let result = InitializeResult {
+        protocol_version: PROTOCOL_VERSION.to_string(),
+        capabilities: ServerCapabilities {
+            tools: Some(ToolsCapability {
+                list_changed: false,
+            }),
+            resources: Some(ResourcesCapability {}),
+        },
+        server_info: ServerInfo {
+            name: "handoff-mcp".to_string(),
+            version: env!("CARGO_PKG_VERSION").to_string(),
+        },
+        instructions: Some(
+            "Handoff MCP server for AI session context persistence. \
+             Call handoff_load_context at session start, \
+             handoff_save_context at session end.\n\n\
+             ## 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\
+             ## Session End\n\
+             1. Call handoff_save_context with:\n\
+                - summary: one-line description of what was accomplished\n\
+                - decisions: key decisions made (with reason and confidence)\n\
+                - blockers: anything preventing progress\n\
+                - handoff_notes: caution/context/suggestion for the next session\n\
+                - context_pointers: files and line ranges the next session should look at\n\n\
+             ## During Work\n\
+             - Use handoff_update_task to create/update tasks as work progresses\n\
+             - Mark tasks in_progress when starting, done when complete\n\
+             - Record decisions as they are made, not just at session end"
+                .to_string(),
+        ),
+    };
+    match serde_json::to_value(result) {
+        Ok(value) => JsonRpcResponse::success(None, value),
+        Err(e) => JsonRpcResponse::error(None, INTERNAL_ERROR, format!("Serialization error: {e}")),
+    }
+}
+
+fn handle_tools_list() -> JsonRpcResponse {
+    let result = ToolsListResult {
+        tools: all_tool_definitions(),
+    };
+    match serde_json::to_value(result) {
+        Ok(value) => JsonRpcResponse::success(None, value),
+        Err(e) => JsonRpcResponse::error(None, INTERNAL_ERROR, format!("Serialization error: {e}")),
+    }
+}
+
+fn handle_tools_call(params: Option<&Value>) -> JsonRpcResponse {
+    let params = match params {
+        Some(p) => p,
+        None => {
+            return JsonRpcResponse::error(
+                None,
+                super::types::INVALID_REQUEST,
+                "tools/call requires params",
+            );
+        }
+    };
+
+    let name = match params.get("name").and_then(|v| v.as_str()) {
+        Some(n) => n,
+        None => {
+            return JsonRpcResponse::error(
+                None,
+                super::types::INVALID_REQUEST,
+                "tools/call requires 'name' parameter",
+            );
+        }
+    };
+
+    let arguments = params
+        .get("arguments")
+        .cloned()
+        .unwrap_or_else(|| json!({}));
+
+    handle_tool_call(name, &arguments)
+}
+
+fn handle_resources_list() -> JsonRpcResponse {
+    let resources = all_resource_definitions();
+    let result = json!({ "resources": resources });
+    JsonRpcResponse::success(None, result)
+}
+
+fn handle_resources_read(params: Option<&Value>) -> JsonRpcResponse {
+    let params = match params {
+        Some(p) => p,
+        None => {
+            return JsonRpcResponse::error(
+                None,
+                super::types::INVALID_REQUEST,
+                "resources/read requires params",
+            );
+        }
+    };
+
+    let uri = match params.get("uri").and_then(|v| v.as_str()) {
+        Some(u) => u,
+        None => {
+            return JsonRpcResponse::error(
+                None,
+                super::types::INVALID_REQUEST,
+                "resources/read requires 'uri' parameter",
+            );
+        }
+    };
+
+    match super::resources::handle_resource_read(uri) {
+        Ok(result) => JsonRpcResponse::success(None, result),
+        Err(e) => JsonRpcResponse::error(
+            None,
+            super::types::INVALID_REQUEST,
+            format!("Resource error: {e}"),
+        ),
+    }
+}

package/src/mcp/tools.rs

@@ -0,0 +1,284 @@
+use serde_json::{json, Value};
+
+use super::types::ToolDefinition;
+
+pub fn all_tool_definitions() -> Vec<ToolDefinition> {
+    vec![
+        ToolDefinition {
+            name: "handoff_init".to_string(),
+            description: "Initialize handoff tracking for a new project. Creates .handoff/ directory structure.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "project_name": {
+                        "type": "string",
+                        "description": "Project name"
+                    },
+                    "description": {
+                        "type": "string",
+                        "description": "Project description"
+                    }
+                },
+                "required": ["project_name"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_load_context".to_string(),
+            description: "Load handoff context for the current project. Call at session start to resume work.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_save_context".to_string(),
+            description: "Save current session state for the next session. Call at session end.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "summary": {
+                        "type": "string",
+                        "description": "One-line summary of this session"
+                    },
+                    "decisions": {
+                        "type": "array",
+                        "description": "Decisions made during this session",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "decision": { "type": "string" },
+                                "reason": { "type": "string" },
+                                "confidence": {
+                                    "type": "string",
+                                    "enum": ["confirmed", "estimated", "unverified"]
+                                }
+                            },
+                            "required": ["decision"]
+                        }
+                    },
+                    "blockers": {
+                        "type": "array",
+                        "items": { "type": "string" }
+                    },
+                    "checklist": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "item": { "type": "string" },
+                                "checked": { "type": "boolean" },
+                                "owner": {
+                                    "type": "string",
+                                    "enum": ["user", "ai"]
+                                }
+                            },
+                            "required": ["item"]
+                        }
+                    },
+                    "handoff_notes": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "note": { "type": "string" },
+                                "category": {
+                                    "type": "string",
+                                    "enum": ["caution", "context", "suggestion"]
+                                }
+                            },
+                            "required": ["note"]
+                        }
+                    },
+                    "references": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "label": { "type": "string" },
+                                "uri": { "type": "string" },
+                                "type": {
+                                    "type": "string",
+                                    "enum": ["file", "issue", "mr", "wiki", "doc", "url"]
+                                },
+                                "notes": { "type": "string" }
+                            },
+                            "required": ["label", "uri"]
+                        }
+                    },
+                    "context_pointers": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "path": { "type": "string" },
+                                "reason": { "type": "string" },
+                                "lines": { "type": "string" }
+                            },
+                            "required": ["path"]
+                        }
+                    },
+                    "environment": {
+                        "type": "object",
+                        "description": "Free-form environment state"
+                    }
+                },
+                "required": ["summary"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_list_tasks".to_string(),
+            description: "List all tasks for the current project 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",
+                        "description": "Filter by status",
+                        "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_update_task".to_string(),
+            description: "Add, update, or move a task. Manages the tasks/ directory structure.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "task": {
+                        "type": "object",
+                        "properties": {
+                            "id": { "type": "string", "description": "Task ID. Omit for new task (auto-generated)." },
+                            "title": { "type": "string" },
+                            "status": {
+                                "type": "string",
+                                "enum": ["todo", "in_progress", "review", "done", "blocked", "skipped"]
+                            },
+                            "notes": { "type": "string" },
+                            "priority": {
+                                "type": "string",
+                                "enum": ["low", "medium", "high"]
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "links": {
+                                "type": "array",
+                                "items": { "type": "string" }
+                            },
+                            "done_criteria": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "item": { "type": "string" },
+                                        "checked": { "type": "boolean" }
+                                    },
+                                    "required": ["item"]
+                                }
+                            }
+                        },
+                        "required": ["title"]
+                    },
+                    "parent_id": {
+                        "type": "string",
+                        "description": "Parent task ID for placement. Omit for auto-placement."
+                    },
+                    "move_to": {
+                        "type": "string",
+                        "description": "Move existing task subtree to a new parent."
+                    }
+                },
+                "required": ["task"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_get_config".to_string(),
+            description: "Read the project's handoff configuration.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    }
+                }
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_update_config".to_string(),
+            description: "Update the project's handoff configuration.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "project_dir": {
+                        "type": "string",
+                        "description": "Project directory path. Defaults to current working directory."
+                    },
+                    "updates": {
+                        "type": "object",
+                        "description": "Key-value pairs to update (dot-notation keys like 'settings.history_limit')"
+                    }
+                },
+                "required": ["updates"]
+            }),
+        },
+        ToolDefinition {
+            name: "handoff_dashboard".to_string(),
+            description: "Show handoff status across all projects in configured scan directories.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "scan_dirs": {
+                        "type": "array",
+                        "items": { "type": "string" },
+                        "description": "Directories to scan. Defaults to config's dashboard.scan_dirs."
+                    },
+                    "include_completed": {
+                        "type": "boolean",
+                        "description": "Include completed tasks in summary"
+                    }
+                }
+            }),
+        },
+    ]
+}
+
+pub fn all_resource_definitions() -> Vec<Value> {
+    vec![
+        json!({
+            "uri": "handoff://sessions",
+            "name": "Active Sessions",
+            "description": "All active session files for the current project",
+            "mimeType": "application/json"
+        }),
+        json!({
+            "uri": "handoff://config",
+            "name": "Project Configuration",
+            "description": "Current project's config.toml content",
+            "mimeType": "application/toml"
+        }),
+    ]
+}

package/src/mcp/types.rs

@@ -0,0 +1,108 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+#[derive(Debug, Deserialize)]
+pub struct JsonRpcRequest {
+    pub jsonrpc: String,
+    pub id: Option<Value>,
+    pub method: String,
+    #[serde(default)]
+    pub params: Option<Value>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct JsonRpcResponse {
+    pub jsonrpc: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub id: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub result: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<JsonRpcError>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct JsonRpcError {
+    pub code: i32,
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub data: Option<Value>,
+}
+
+pub const PARSE_ERROR: i32 = -32700;
+pub const INVALID_REQUEST: i32 = -32600;
+pub const METHOD_NOT_FOUND: i32 = -32601;
+pub const INTERNAL_ERROR: i32 = -32603;
+
+impl JsonRpcResponse {
+    pub fn success(id: Option<Value>, result: Value) -> Self {
+        Self {
+            jsonrpc: "2.0".to_string(),
+            id,
+            result: Some(result),
+            error: None,
+        }
+    }
+
+    pub fn error(id: Option<Value>, code: i32, message: impl Into<String>) -> Self {
+        Self {
+            jsonrpc: "2.0".to_string(),
+            id,
+            result: None,
+            error: Some(JsonRpcError {
+                code,
+                message: message.into(),
+                data: None,
+            }),
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+pub struct ServerInfo {
+    pub name: String,
+    pub version: String,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ServerCapabilities {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub tools: Option<ToolsCapability>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub resources: Option<ResourcesCapability>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ToolsCapability {
+    #[serde(rename = "listChanged")]
+    pub list_changed: bool,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ResourcesCapability {}
+
+#[derive(Debug, Serialize)]
+pub struct InitializeResult {
+    #[serde(rename = "protocolVersion")]
+    pub protocol_version: String,
+    pub capabilities: ServerCapabilities,
+    #[serde(rename = "serverInfo")]
+    pub server_info: ServerInfo,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub instructions: Option<String>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ToolDefinition {
+    pub name: String,
+    pub description: String,
+    #[serde(rename = "inputSchema")]
+    pub input_schema: Value,
+}
+
+#[derive(Debug, Serialize)]
+pub struct ToolsListResult {
+    pub tools: Vec<ToolDefinition>,
+}
+
+pub const PROTOCOL_VERSION: &str = "2025-03-26";

package/src/storage/config.rs

@@ -0,0 +1,112 @@
+use std::collections::HashMap;
+use std::path::Path;
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Config {
+    pub project: ProjectConfig,
+    #[serde(default)]
+    pub settings: SettingsConfig,
+    #[serde(default)]
+    pub dashboard: DashboardConfig,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ProjectConfig {
+    pub name: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SettingsConfig {
+    #[serde(default = "default_history_limit")]
+    pub history_limit: u32,
+    #[serde(default = "default_done_task_limit")]
+    pub done_task_limit: u32,
+    #[serde(default = "default_auto_git_summary")]
+    pub auto_git_summary: bool,
+    #[serde(default)]
+    pub context_files: Vec<String>,
+    #[serde(default)]
+    pub custom_fields: HashMap<String, toml::Value>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DashboardConfig {
+    #[serde(default = "default_scan_dirs")]
+    pub scan_dirs: Vec<String>,
+    #[serde(default)]
+    pub exclude_patterns: Vec<String>,
+}
+
+fn default_history_limit() -> u32 {
+    20
+}
+
+fn default_done_task_limit() -> u32 {
+    10
+}
+
+fn default_auto_git_summary() -> bool {
+    true
+}
+
+fn default_scan_dirs() -> Vec<String> {
+    vec!["~/pro/".to_string()]
+}
+
+impl Default for SettingsConfig {
+    fn default() -> Self {
+        Self {
+            history_limit: default_history_limit(),
+            done_task_limit: default_done_task_limit(),
+            auto_git_summary: default_auto_git_summary(),
+            context_files: Vec::new(),
+            custom_fields: HashMap::new(),
+        }
+    }
+}
+
+impl Default for DashboardConfig {
+    fn default() -> Self {
+        Self {
+            scan_dirs: default_scan_dirs(),
+            exclude_patterns: Vec::new(),
+        }
+    }
+}
+
+impl Config {
+    pub fn new(name: &str, description: &str) -> Self {
+        Self {
+            project: ProjectConfig {
+                name: name.to_string(),
+                description: if description.is_empty() {
+                    None
+                } else {
+                    Some(description.to_string())
+                },
+            },
+            settings: SettingsConfig::default(),
+            dashboard: DashboardConfig::default(),
+        }
+    }
+}
+
+pub fn read_config(path: &Path) -> Result<Config> {
+    let content = std::fs::read_to_string(path)
+        .with_context(|| format!("Failed to read config: {}", path.display()))?;
+    let config: Config = toml::from_str(&content)
+        .with_context(|| format!("Failed to parse config: {}", path.display()))?;
+    Ok(config)
+}
+
+pub fn write_config(path: &Path, config: &Config) -> Result<()> {
+    let content = toml::to_string_pretty(config).context("Failed to serialize config")?;
+    std::fs::write(path, content)
+        .with_context(|| format!("Failed to write config: {}", path.display()))?;
+    Ok(())
+}