handoff-mcp-server 0.23.0 → 0.24.0

package/Cargo.lock

@@ -145,7 +145,7 @@ dependencies = [
 
 [[package]]
 name = "handoff-mcp"
-version = "0.23.0"
+version = "0.24.0"
 dependencies = [
  "anyhow",
  "chrono",
@@ -655,6 +655,6 @@ dependencies = [
 
 [[package]]
 name = "zmij"
-version = "1.0.21"
+version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+checksum = "bd2f034a4bebf216c9e4b7083603e024cf930873fd67830cfb083c9fa33129d9"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "handoff-mcp"
-version = "0.23.0"
+version = "0.24.0"
 edition = "2021"
 description = "MCP server that gives AI coding agents persistent memory across sessions"
 license = "MIT"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handoff-mcp-server",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "MCP server that gives AI coding agents persistent memory across sessions",
   "license": "MIT",
   "author": "AlphaElements <66808803+alphaelements@users.noreply.github.com>",

package/skills/handoff-docs/SKILL.md

@@ -43,6 +43,23 @@ Mark verified sections:
 Check readiness:
 - `handoff_task_checklist(task_id=..., action="view")` — combined readiness view
 
+## Document Creation Rules
+
+1. **One document = one complete document**
+   - Always start with a `# Title` (h1 heading)
+   - Group related content of the same category (ADR, spec, design, etc.) into a single document
+   - Example: ADR-001 through ADR-005 belong inside `# Architecture Decision Records`
+     as `## ADR-001: Redis Session` through `## ADR-005: ...` sections
+
+2. **Use `append_body` to add sections**
+   - When adding a section to an existing document, use `append_body` instead of rewriting the whole body
+   - Example: `doc_save(doc_id="doc-...", append_body="## ADR-006: ...\n\n...")`
+
+3. **MCP handles splitting internally**
+   - There is no need for the AI to split content into separate documents manually
+   - MCP automatically computes a section index at each h2 heading boundary
+   - Use `doc_get(format="section", seq=N)` to retrieve individual sections on demand
+
 ## The 9 Doc Tools
 
 | Tool | Purpose |

package/src/mcp/handlers/docs.rs

@@ -61,12 +61,21 @@ pub fn handle_doc_save(arguments: &Value) -> Result<String> {
     let handoff = ensure_handoff_exists(&project_dir)?;
     ensure_docs_dir(&handoff)?;
 
-    let body = arguments
-        .get("body")
-        .and_then(|v| v.as_str())
-        .ok_or_else(|| anyhow::anyhow!("'body' is required"))?;
+    let body_arg = arguments.get("body").and_then(|v| v.as_str());
+    let append_body_arg = arguments.get("append_body").and_then(|v| v.as_str());
+    if body_arg.is_some() && append_body_arg.is_some() {
+        anyhow::bail!("'body' and 'append_body' are mutually exclusive");
+    }
+    if body_arg.is_none() && append_body_arg.is_none() {
+        anyhow::bail!("either 'body' or 'append_body' is required");
+    }
 
     let doc_id = arguments.get("doc_id").and_then(|v| v.as_str());
+    if append_body_arg.is_some() && doc_id.is_none() {
+        anyhow::bail!(
+            "'append_body' requires 'doc_id' (appending to a new document is not meaningful)"
+        );
+    }
     let existing = match doc_id {
         Some(id) => Some(
             find_doc_by_id(&handoff, id)?
@@ -75,6 +84,31 @@ pub fn handle_doc_save(arguments: &Value) -> Result<String> {
         None => None,
     };
 
+    // `append_body`: join the appended text onto the existing document's
+    // stripped body (read_doc_body — NOT read_full_body, whose
+    // BOM/frontmatter restoration would otherwise get re-detected and
+    // double-persisted by `split()` below). No separator is inserted when
+    // the existing body is empty/missing (spec §3.1 edge case).
+    let joined_body: String;
+    let body: &str = if let Some(append_body) = append_body_arg {
+        let existing_doc = existing
+            .as_ref()
+            .expect("append_body requires doc_id, checked above, so existing is Some");
+        let existing_body = read_doc_body(&handoff, &existing_doc.slug)?.unwrap_or_default();
+        let separator = arguments
+            .get("separator")
+            .and_then(|v| v.as_str())
+            .unwrap_or("\n\n");
+        joined_body = if existing_body.is_empty() {
+            append_body.to_string()
+        } else {
+            format!("{existing_body}{separator}{append_body}")
+        };
+        &joined_body
+    } else {
+        body_arg.expect("body_arg is Some in this branch, checked above")
+    };
+
     // slug: required for new documents, taken from the existing document on
     // update (the `slug` argument is ignored on update — renaming a
     // document's file-naming slug is out of scope for `doc_save`).
@@ -185,6 +219,12 @@ pub fn handle_doc_save(arguments: &Value) -> Result<String> {
     // it, computed fresh on every save (no stale-fragment cleanup needed —
     // there is nothing left on disk to clean up per section).
     let body_after_strip: String = split_doc.fragments.iter().map(|f| f.body).collect();
+    if !body_after_strip.starts_with("# ") {
+        warnings.push(
+            "body does not start with a level-1 heading — consider adding one for readability"
+                .to_string(),
+        );
+    }
     write_doc_body(&handoff, &slug, &body_after_strip)?;
     doc.sections = compute_sections(&split_doc);
 

package/src/mcp/tools.rs

@@ -1237,15 +1237,17 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         // ---- Document management tools (P1-6a, v5 rearchitecture: wiki/130-document-management.md §3.1) ----
         ToolDefinition {
             name: "handoff_doc_save".to_string(),
-            description: "Create or update a document from a full Markdown body. The body is stored verbatim at _doc.<slug>.md and split in-memory into a `sections` byte-offset index (no per-section files), syncing the bidirectional task<->doc link when task_ids is given. Omit doc_id to create a new document (slug is then required and must be unique); pass an existing doc_id to update it (slug is taken from the existing document — it cannot be renamed via doc_save). Returns a JSON string {doc_id,slug,title,doc_type,section_count,content_hash,warnings:[…]} — warnings lists any task_ids that could not be resolved.".to_string(),
+            description: "Save a complete document. The body MUST be a whole, human-readable Markdown document starting with a level-1 heading (e.g. `# Authentication Spec`) — group related content into ONE document (for example, all ADRs belong in a single `# Architecture Decision Records` document with each ADR as an `## ADR-001: ...` section, NOT as separate documents). MCP handles section-level indexing internally, so do not pre-split content yourself. To append a new section to an existing document (e.g. adding ADR-003) without rewriting the whole body, pass `append_body` with just the new section instead of `body` — `body` and `append_body` are mutually exclusive, and `append_body` requires an existing `doc_id` (there is nothing to append to when creating a new document). The body (or, for append_body, the resulting combined body) is stored verbatim at _doc.<slug>.md and split in-memory into a `sections` byte-offset index (no per-section files), syncing the bidirectional task<->doc link when task_ids is given. Omit doc_id to create a new document (slug is then required and must be unique); pass an existing doc_id to update it (slug is taken from the existing document — it cannot be renamed via doc_save). Returns a JSON string {doc_id,slug,title,doc_type,section_count,content_hash,warnings:[…]} — warnings lists any task_ids that could not be resolved, and includes a soft notice when the saved body does not start with a level-1 heading (the save is never rejected for this).".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {
                     "project_dir": { "type": "string", "description": "Project directory path. Defaults to current working directory." },
-                    "doc_id": { "type": "string", "description": "Existing document id to update. Omit to create a new document." },
+                    "doc_id": { "type": "string", "description": "Existing document id to update. Omit to create a new document. Required when append_body is given." },
                     "slug": { "type": "string", "description": "Human-readable file-naming slug ([a-z0-9-], max 60 chars), used to name _doc.<slug>.json/.md. Required when creating; ignored on update (the existing document's slug is kept)." },
-                    "title": { "type": "string", "description": "Document title. Required when creating; optional on update (defaults to the existing title)." },
-                    "body": { "type": "string", "description": "Full Markdown body. Required." },
+                    "title": { "type": "string", "description": "Document title. Required when creating; optional on update or append (defaults to the existing title)." },
+                    "body": { "type": "string", "description": "Full Markdown document, starting with a level-1 heading. Mutually exclusive with append_body; one of the two is required." },
+                    "append_body": { "type": "string", "description": "New section(s) to append to an existing document's body (e.g. `## ADR-003: ...`). Joined onto the existing body with `separator` before the usual split/save. Requires doc_id. Mutually exclusive with body; one of the two is required. Use the same line-ending style as the existing document." },
+                    "separator": { "type": "string", "description": "append_body only: text inserted between the existing body and append_body.", "default": "\n\n" },
                     "doc_type": { "type": "string", "description": "Document type.", "enum": ["spec", "design", "adr", "guide", "note"], "default": "note" },
                     "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags for filtering/search." },
                     "scope_paths": { "type": "array", "items": { "type": "string" }, "description": "Path prefixes this document applies to; boosts relevance in doc_list(query=...) when a file path matches." },
@@ -1254,8 +1256,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
                     "related": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rel": { "type": "string", "enum": ["supersedes", "references", "implements", "extends", "conflicts"] } }, "required": ["id", "rel"] }, "description": "Sibling/relative relationships to other documents." },
                     "split_level": { "type": "integer", "description": "ATX heading level at/above which the body is split into sections.", "default": 2 },
                     "auto_inject": { "type": "string", "description": "Auto-injection control.", "enum": ["auto", "full", "outline", "none"], "default": "auto" }
-                },
-                "required": ["body"]
+                }
             }),
         },
         ToolDefinition {
@@ -1417,7 +1418,7 @@ pub fn all_tool_definitions() -> Vec<ToolDefinition> {
         },
         ToolDefinition {
             name: "handoff_doc_import".to_string(),
-            description: "Bulk-write an analyzed payload (from handoff_doc_analyze, with the AI's overrides applied) as new documents. Each analyzed.auto_resolved entry must carry its file's full Markdown 'body' (doc_import writes from the payload, it does not re-read the filesystem). Each document's slug is taken from its override's 'slug' if given, else its suggested_slug, disambiguated with a numeric suffix on collision. Persists every file as a document, applies proposed_tree parent/children relationships, links task_ids to every imported document (bidirectionally), and invalidates the doc corpus cache. Returns a JSON string {imported_count,documents:[{doc_id,slug,title,section_count}],warnings:[…]}.".to_string(),
+            description: "Bulk-import pre-existing Markdown files. Each file becomes ONE document in .handoff/docs/ — the file's content is stored as-is, including its h1 heading. Do NOT split a single source file into multiple documents; MCP indexes sections internally. Writes an analyzed payload (from handoff_doc_analyze, with the AI's overrides applied) as new documents. Each analyzed.auto_resolved entry must carry its file's full Markdown 'body' (doc_import writes from the payload, it does not re-read the filesystem). Each document's slug is taken from its override's 'slug' if given, else its suggested_slug, disambiguated with a numeric suffix on collision. Persists every file as a document, applies proposed_tree parent/children relationships, links task_ids to every imported document (bidirectionally), and invalidates the doc corpus cache. Returns a JSON string {imported_count,documents:[{doc_id,slug,title,section_count}],warnings:[…]}.".to_string(),
             input_schema: json!({
                 "type": "object",
                 "properties": {