handoff-mcp-server 0.1.0

package/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "handoff-mcp"
+version = "0.1.0"
+edition = "2021"
+description = "MCP server that gives AI coding agents persistent memory across sessions"
+license = "MIT"
+repository = "https://github.com/alphaelements/handoff-mcp"
+homepage = "https://github.com/alphaelements/handoff-mcp"
+readme = "README.md"
+keywords = ["mcp", "ai", "claude", "handoff", "context"]
+categories = ["command-line-utilities", "development-tools"]
+rust-version = "1.70"
+exclude = ["lefthook.yml", "tmp/", "wiki/", "docs/", ".claude/", ".vscode/"]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+toml = "0.8"
+chrono = { version = "0.4", features = ["serde"] }
+anyhow = "1"
+thiserror = "2"
+
+[dev-dependencies]
+tempfile = "3.27.0"

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AlphaElements Co., Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# handoff-mcp
+
+An MCP server that gives AI coding agents persistent memory across sessions.
+
+When you close a Claude Code session and start a new one, the new session has no idea what the previous one was doing. handoff-mcp solves this by saving session context — tasks, decisions, blockers, and file pointers — to a local `.handoff/` directory that the next session can load automatically.
+
+## The Problem
+
+AI coding sessions are stateless. Every new session starts from zero:
+
+- **"What was I working on?"** — the agent doesn't know
+- **"What decisions were made?"** — lost with the previous context window
+- **"What's left to do?"** — you have to re-explain everything
+
+This gets painful fast on multi-session projects.
+
+## How It Works
+
+```
+Session 1                          Session 2
+┌──────────────┐                   ┌──────────────┐
+│ Working...   │   .handoff/       │ Loading...   │
+│              │──────────────────>│              │
+│ save_context │   tasks/          │ load_context │
+│  - summary   │   sessions/      │  - tasks     │
+│  - decisions │   config.toml    │  - decisions │
+│  - blockers  │                   │  - blockers  │
+│  - tasks     │                   │  - git state │
+└──────────────┘                   └──────────────┘
+```
+
+At session end, the agent calls `handoff_save_context` to persist what matters. At session start, it calls `handoff_load_context` to pick up where things left off.
+
+## Installation
+
+### npm (recommended)
+
+```bash
+npm install -g handoff-mcp-server
+```
+
+### Build from source
+
+```bash
+git clone https://github.com/alphaelements/handoff-mcp.git
+cd handoff-mcp
+cargo build --release
+```
+
+## Setup
+
+Add to your Claude Code MCP configuration:
+
+**Global** (`~/.claude/.mcp.json`) — available in all projects:
+
+```json
+{
+  "handoff": {
+    "command": "handoff-mcp",
+    "args": []
+  }
+}
+```
+
+**Per-project** (`.mcp.json` in project root):
+
+```json
+{
+  "handoff": {
+    "command": "handoff-mcp",
+    "args": []
+  }
+}
+```
+
+## Quick Start
+
+1. **Initialize** a project:
+
+   The agent calls `handoff_init` with your project name. This creates a `.handoff/` directory:
+
+   ```
+   .handoff/
+   ├── config.toml      # Project settings
+   ├── sessions/        # Session history (TOML files)
+   └── tasks/           # Task tree (directories + TOML files)
+   ```
+
+2. **Work normally** — create tasks, track progress, make decisions.
+
+3. **Save context** at session end — the agent captures a summary, decisions, blockers, and references.
+
+4. **Load context** at next session start — the agent reads back everything and resumes.
+
+> Add `.handoff/` to your `.gitignore` — it contains local working state, not code.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `handoff_init` | Initialize `.handoff/` directory for a project |
+| `handoff_load_context` | Load session context, tasks, and git state at session start |
+| `handoff_save_context` | Save session summary, decisions, blockers, and references |
+| `handoff_list_tasks` | List tasks with optional status filter |
+| `handoff_update_task` | Create, update, or move tasks in a hierarchical tree |
+| `handoff_get_config` | Read project configuration |
+| `handoff_update_config` | Update project configuration |
+| `handoff_dashboard` | Overview of all handoff-enabled projects |
+
+### Task Management
+
+Tasks are stored as a directory tree, supporting hierarchical structures:
+
+```
+tasks/
+├── 01-todo--implement-auth/
+│   ├── task.toml
+│   ├── 01.1-done--design-schema/
+│   │   └── task.toml
+│   └── 01.2-in_progress--write-handlers/
+│       └── task.toml
+└── 02-blocked--deploy-staging/
+    └── task.toml
+```
+
+Statuses: `todo` | `in_progress` | `review` | `done` | `blocked` | `skipped`
+
+Each task can have:
+- Priority (`low` / `medium` / `high`)
+- Labels
+- Done criteria (checklist items)
+- Links to issues, MRs, or docs
+- Notes
+
+### Session Context
+
+When saving context, the agent can record:
+
+- **Summary** — one-line description of what happened
+- **Decisions** — what was decided and why, with confidence levels (`confirmed` / `estimated` / `unverified`)
+- **Blockers** — what's preventing progress
+- **Checklist** — items for the next session
+- **Handoff notes** — categorized as `caution`, `context`, or `suggestion`
+- **References** — links to files, issues, MRs, wiki pages, or URLs
+- **Context pointers** — specific files and line ranges the next session should look at
+- **Git state** — current branch, recent commits, and dirty files (captured automatically)
+
+### Dashboard
+
+`handoff_dashboard` scans directories for projects with `.handoff/` and shows a summary:
+
+```
+## my-project (3 tasks)
+  - [in_progress] Implement auth (high)
+  - [todo] Add tests (medium)
+  - [blocked] Deploy staging (medium)
+
+## other-project (1 task)
+  - [review] Update README (low)
+```
+
+## Configuration
+
+`.handoff/config.toml`:
+
+```toml
+[project]
+name = "my-project"
+description = "Project description"
+
+[settings]
+history_limit = 20         # Max closed sessions to keep
+done_task_limit = 10       # Max completed tasks to show
+auto_git_summary = true    # Capture git state automatically
+
+[dashboard]
+scan_dirs = ["~/pro/"]     # Directories to scan for dashboard
+```
+
+## MCP Resources
+
+| URI | Description |
+|-----|-------------|
+| `handoff://sessions` | Active session data (JSON) |
+| `handoff://config` | Project configuration (TOML) |
+
+## Recommended CLAUDE.md Setup
+
+Add the following to your project's `CLAUDE.md` so the agent uses handoff consistently:
+
+```markdown
+## Session Handoff
+
+This project uses handoff-mcp for session continuity.
+
+- **Session start**: Call `handoff_load_context` to load previous session state.
+  If not initialized, call `handoff_init` with the project name.
+- **Session end**: Call `handoff_save_context` with a summary, decisions, and blockers.
+- **During work**: Use `handoff_update_task` to track progress.
+  Mark tasks `in_progress` when starting, `done` when complete.
+- **Decisions**: Record decisions with confidence levels as they are made,
+  not just at session end. Use `confirmed` for verified facts, `estimated`
+  for reasonable assumptions, `unverified` for unknowns.
+```
+
+## Skill File (Optional)
+
+This repository includes a skill file at [`skills/handoff/SKILL.md`](skills/handoff/SKILL.md) that makes handoff behavior automatic in Claude Code. Copy it to your user skills directory:
+
+```bash
+cp -r skills/handoff ~/.claude/skills/
+```
+
+This teaches the agent to automatically load context at session start, track tasks during work, and save context at session end.
+
+## Compatibility
+
+- **Claude Code** — fully supported (stdio transport)
+- **Other MCP clients** — any client supporting the MCP stdio transport
+
+## License
+
+MIT

package/bin/handoff-mcp.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const binary = path.join(__dirname, "handoff-mcp-bin");
+
+if (!fs.existsSync(binary)) {
+  console.error(
+    "handoff-mcp binary not found. Try reinstalling: npm install -g handoff-mcp-server"
+  );
+  process.exit(1);
+}
+
+try {
+  execFileSync(binary, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  if (e.status != null) process.exit(e.status);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "handoff-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server that gives AI coding agents persistent memory across sessions",
+  "license": "MIT",
+  "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alphaelements/handoff-mcp.git"
+  },
+  "homepage": "https://github.com/alphaelements/handoff-mcp",
+  "keywords": [
+    "mcp",
+    "ai",
+    "claude",
+    "handoff",
+    "context",
+    "session"
+  ],
+  "bin": {
+    "handoff-mcp": "./bin/handoff-mcp.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "src/",
+    "tests/",
+    "Cargo.toml",
+    "Cargo.lock",
+    "LICENSE",
+    "README.md"
+  ],
+  "os": [
+    "linux",
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const BIN_DIR = path.join(ROOT, "bin");
+const BINARY = path.join(BIN_DIR, "handoff-mcp-bin");
+
+if (fs.existsSync(BINARY)) {
+  process.exit(0);
+}
+
+try {
+  execSync("cargo --version", { stdio: "ignore" });
+} catch {
+  console.error(
+    "Error: Rust toolchain not found.\n" +
+      "handoff-mcp-server requires Rust to build from source.\n" +
+      "Install Rust: https://rustup.rs/"
+  );
+  process.exit(1);
+}
+
+console.log("Building handoff-mcp from source...");
+try {
+  execSync("cargo build --release", { cwd: ROOT, stdio: "inherit" });
+} catch {
+  console.error("Error: cargo build failed.");
+  process.exit(1);
+}
+
+const built = path.join(ROOT, "target", "release", "handoff-mcp");
+if (!fs.existsSync(built)) {
+  console.error("Error: binary not found after build.");
+  process.exit(1);
+}
+
+fs.mkdirSync(BIN_DIR, { recursive: true });
+fs.copyFileSync(built, BINARY);
+fs.chmodSync(BINARY, 0o755);
+console.log("handoff-mcp installed successfully.");

package/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod mcp;
+pub mod storage;

package/src/main.rs

@@ -0,0 +1,29 @@
+use std::io::{self, BufRead, Write};
+
+use handoff_mcp::mcp::protocol::process_line;
+
+fn main() {
+    eprintln!("handoff-mcp v{}", env!("CARGO_PKG_VERSION"));
+
+    let stdin = io::stdin();
+    let mut stdout = io::stdout();
+
+    for line in stdin.lock().lines() {
+        let line = match line {
+            Ok(l) => l,
+            Err(e) => {
+                eprintln!("stdin read error: {e}");
+                break;
+            }
+        };
+
+        if let Some(response) = process_line(&line) {
+            if writeln!(stdout, "{response}").is_err() {
+                break;
+            }
+            if stdout.flush().is_err() {
+                break;
+            }
+        }
+    }
+}

package/src/mcp/handlers/config.rs

@@ -0,0 +1,115 @@
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage::config::{read_config, write_config};
+use crate::storage::ensure_handoff_exists;
+
+pub fn handle_get(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let config = read_config(&handoff.join("config.toml"))?;
+    let result = serde_json::to_value(&config).context("Failed to serialize config")?;
+    serde_json::to_string_pretty(&result).context("Failed to format config")
+}
+
+pub fn handle_update(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+
+    let handoff = ensure_handoff_exists(&project_dir)?;
+    let config_path = handoff.join("config.toml");
+    let mut config = read_config(&config_path)?;
+
+    let updates = arguments
+        .get("updates")
+        .ok_or_else(|| anyhow::anyhow!("'updates' parameter is required"))?;
+
+    let updates = updates
+        .as_object()
+        .ok_or_else(|| anyhow::anyhow!("'updates' must be an object"))?;
+
+    let mut applied = Vec::new();
+
+    for (key, value) in updates {
+        match key.as_str() {
+            "settings.history_limit" => {
+                if let Some(n) = value.as_u64() {
+                    config.settings.history_limit = n as u32;
+                    applied.push(format!("settings.history_limit = {n}"));
+                }
+            }
+            "settings.done_task_limit" => {
+                if let Some(n) = value.as_u64() {
+                    config.settings.done_task_limit = n as u32;
+                    applied.push(format!("settings.done_task_limit = {n}"));
+                }
+            }
+            "settings.auto_git_summary" => {
+                if let Some(b) = value.as_bool() {
+                    config.settings.auto_git_summary = b;
+                    applied.push(format!("settings.auto_git_summary = {b}"));
+                }
+            }
+            "settings.context_files" => {
+                if let Some(arr) = value.as_array() {
+                    config.settings.context_files = arr
+                        .iter()
+                        .filter_map(|v| v.as_str().map(String::from))
+                        .collect();
+                    applied.push(format!(
+                        "settings.context_files = {:?}",
+                        config.settings.context_files
+                    ));
+                }
+            }
+            "dashboard.scan_dirs" => {
+                if let Some(arr) = value.as_array() {
+                    config.dashboard.scan_dirs = arr
+                        .iter()
+                        .filter_map(|v| v.as_str().map(String::from))
+                        .collect();
+                    applied.push(format!(
+                        "dashboard.scan_dirs = {:?}",
+                        config.dashboard.scan_dirs
+                    ));
+                }
+            }
+            "dashboard.exclude_patterns" => {
+                if let Some(arr) = value.as_array() {
+                    config.dashboard.exclude_patterns = arr
+                        .iter()
+                        .filter_map(|v| v.as_str().map(String::from))
+                        .collect();
+                    applied.push(format!(
+                        "dashboard.exclude_patterns = {:?}",
+                        config.dashboard.exclude_patterns
+                    ));
+                }
+            }
+            "project.name" => {
+                if let Some(s) = value.as_str() {
+                    config.project.name = s.to_string();
+                    applied.push(format!("project.name = {s}"));
+                }
+            }
+            "project.description" => {
+                if let Some(s) = value.as_str() {
+                    config.project.description = Some(s.to_string());
+                    applied.push(format!("project.description = {s}"));
+                }
+            }
+            other => {
+                applied.push(format!("{other}: unknown key (skipped)"));
+            }
+        }
+    }
+
+    write_config(&config_path, &config)?;
+
+    if applied.is_empty() {
+        Ok("No updates applied".to_string())
+    } else {
+        Ok(format!("Updated config:\n{}", applied.join("\n")))
+    }
+}

package/src/mcp/handlers/dashboard.rs

@@ -0,0 +1,109 @@
+use std::path::Path;
+
+use anyhow::{Context, Result};
+use serde_json::Value;
+
+use crate::storage::config::read_config;
+use crate::storage::sessions::read_active_sessions;
+use crate::storage::tasks::build_task_index;
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let scan_dirs: Vec<String> = arguments
+        .get("scan_dirs")
+        .and_then(|v| v.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect()
+        })
+        .unwrap_or_else(|| vec!["~/pro/".to_string()]);
+
+    let mut projects = Vec::new();
+    let mut total_active = 0u32;
+    let mut total_blocked = 0u32;
+
+    for scan_dir in &scan_dirs {
+        let expanded = expand_tilde(scan_dir);
+        let expanded_path = Path::new(&expanded);
+
+        if !expanded_path.exists() {
+            continue;
+        }
+
+        let entries = match std::fs::read_dir(expanded_path) {
+            Ok(e) => e,
+            Err(_) => continue,
+        };
+
+        for entry in entries.flatten() {
+            if !entry.file_type().map(|ft| ft.is_dir()).unwrap_or(false) {
+                continue;
+            }
+
+            let project_path = entry.path();
+            let handoff_dir = project_path.join(".handoff");
+
+            if !handoff_dir.join("config.toml").exists() {
+                continue;
+            }
+
+            if let Ok(info) = collect_project_info(&project_path) {
+                total_active += info["active_tasks"].as_u64().unwrap_or(0) as u32;
+                total_blocked += info["blocked_tasks"].as_u64().unwrap_or(0) as u32;
+                projects.push(info);
+            }
+        }
+    }
+
+    let result = serde_json::json!({
+        "projects": projects,
+        "total_active_tasks": total_active,
+        "total_blocked": total_blocked,
+    });
+
+    serde_json::to_string_pretty(&result).context("Failed to serialize dashboard")
+}
+
+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 (_, summary) =
+        build_task_index(&handoff_dir.join("tasks"), config.settings.done_task_limit)?;
+
+    let last_session_ended = sessions.last().and_then(|s| s.ended_at.clone());
+
+    let branch = sessions.last().and_then(|s| s.branch.clone());
+
+    let active_tasks = *summary.by_status.get("in_progress").unwrap_or(&0)
+        + *summary.by_status.get("todo").unwrap_or(&0)
+        + *summary.by_status.get("review").unwrap_or(&0);
+
+    let blocked_tasks = *summary.by_status.get("blocked").unwrap_or(&0);
+
+    let blockers: Vec<String> = sessions
+        .iter()
+        .flat_map(|s| s.blockers.iter().cloned())
+        .collect();
+
+    Ok(serde_json::json!({
+        "name": config.project.name,
+        "path": project_path.to_string_lossy(),
+        "last_session_ended": last_session_ended,
+        "branch": branch,
+        "active_tasks": active_tasks,
+        "blocked_tasks": blocked_tasks,
+        "blockers": blockers,
+    }))
+}
+
+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()
+}

package/src/mcp/handlers/init.rs

@@ -0,0 +1,28 @@
+use anyhow::Result;
+use serde_json::Value;
+
+use super::resolve_project_dir;
+use crate::storage;
+
+pub fn handle(arguments: &Value) -> Result<String> {
+    let project_dir = resolve_project_dir(arguments)?;
+
+    let project_name = arguments
+        .get("project_name")
+        .and_then(|v| v.as_str())
+        .ok_or_else(|| anyhow::anyhow!("project_name is required"))?;
+
+    let description = arguments
+        .get("description")
+        .and_then(|v| v.as_str())
+        .unwrap_or("");
+
+    storage::init_handoff(&project_dir, project_name, description)?;
+
+    Ok(format!(
+        "Initialized handoff tracking for '{}' at {}/.handoff/\n\
+         Created: config.toml, sessions/, tasks/",
+        project_name,
+        project_dir.display()
+    ))
+}