@hanna84/mcp-writing 1.0.0 → 1.3.6

package/index.js

@@ -4,12 +4,17 @@ import http from "node:http";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
+import yaml from "js-yaml";
 import { z } from "zod";
 import { openDb } from "./db.js";
-import { syncAll, isSyncDirWritable, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath } from "./sync.js";
+import { syncAll, isSyncDirWritable, writeMeta, readMeta, indexSceneFile, normalizeSceneMetaForPath, sidecarPath } from "./sync.js";
+import { isGitAvailable, isGitRepository, initGitRepository, createSnapshot, listSnapshots, getSceneProseAtCommit } from "./git.js";
+import { renderCharacterArcTemplate, renderCharacterSheetTemplate, renderPlaceSheetTemplate, slugifyEntityName } from "./world-entity-templates.js";
 
 const SYNC_DIR = process.env.WRITING_SYNC_DIR ?? "./sync";
 const DB_PATH = process.env.DB_PATH ?? "./writing.db";
+const SYNC_DIR_ABS = path.resolve(SYNC_DIR);
+const DB_PATH_DISPLAY = DB_PATH === ":memory:" ? DB_PATH : path.resolve(DB_PATH);
 const HTTP_PORT = parseInt(process.env.HTTP_PORT ?? "3000", 10);
 const MAX_CHAPTER_SCENES = parseInt(process.env.MAX_CHAPTER_SCENES ?? "10", 10);
 const DEFAULT_METADATA_PAGE_SIZE = parseInt(process.env.DEFAULT_METADATA_PAGE_SIZE ?? "20", 10);
@@ -92,17 +97,161 @@ function inferCharacterIdsFromProse(dbHandle, prose, projectId) {
   return [...new Set(found)].slice(0, 12);
 }
 
+function readSupportingNotesForEntity(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  const base = path.basename(filePath, ext).toLowerCase();
+  if (base !== "sheet") return [];
+
+  const dir = path.dirname(filePath);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  return entries
+    .filter(entry => entry.isFile())
+    .map(entry => entry.name)
+    .filter(name => /\.(md|txt)$/i.test(name))
+    .filter(name => !/^sheet\.(md|txt)$/i.test(name))
+    .sort((a, b) => a.localeCompare(b))
+    .map(name => {
+      const notePath = path.join(dir, name);
+      try {
+        const raw = fs.readFileSync(notePath, "utf8");
+        const { content } = matter(raw);
+        return {
+          file_name: name,
+          content: content.trim(),
+        };
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .filter(note => note.content);
+}
+
+function readEntityMetadata(filePath) {
+  const metaPath = sidecarPath(filePath);
+  if (fs.existsSync(metaPath)) {
+    try {
+      return yaml.load(fs.readFileSync(metaPath, "utf8")) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  try {
+    return matter(fs.readFileSync(filePath, "utf8")).data ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function resolveProjectRoot(projectId) {
+  if (projectId.includes("/")) {
+    const [universeId, projectSlug] = projectId.split("/");
+    return path.join(SYNC_DIR, "universes", universeId, projectSlug);
+  }
+  return path.join(SYNC_DIR, "projects", projectId);
+}
+
+function resolveWorldEntityDir({ kind, projectId, universeId, name }) {
+  const slug = slugifyEntityName(name);
+  const baseDir = projectId
+    ? path.join(resolveProjectRoot(projectId), "world")
+    : path.join(SYNC_DIR, "universes", universeId, "world");
+  const bucket = kind === "character" ? "characters" : "places";
+  return {
+    slug,
+    dir: path.join(baseDir, bucket, slug),
+  };
+}
+
+function createCanonicalWorldEntity({ kind, name, notes, projectId, universeId, meta }) {
+  const prefix = kind === "character" ? "char" : "place";
+  const idKey = kind === "character" ? "character_id" : "place_id";
+  const slug = slugifyEntityName(name);
+  if (!slug) throw new Error("Name must contain at least one alphanumeric character.");
+
+  const { dir } = resolveWorldEntityDir({ kind, projectId, universeId, name });
+  const prosePath = path.join(dir, "sheet.md");
+  const metaPath = sidecarPath(prosePath);
+  if (fs.existsSync(prosePath) || fs.existsSync(metaPath)) {
+    throw new Error(`Canonical sheet already exists at ${dir}`);
+  }
+
+  fs.mkdirSync(dir, { recursive: true });
+  const defaultSheet = kind === "character"
+    ? renderCharacterSheetTemplate(name)
+    : renderPlaceSheetTemplate(name);
+  fs.writeFileSync(prosePath, `${notes?.trim() ?? defaultSheet}${(notes?.trim() ?? defaultSheet) ? "\n" : ""}`, "utf8");
+  if (kind === "character") {
+    fs.writeFileSync(path.join(dir, "arc.md"), `${renderCharacterArcTemplate(name)}\n`, "utf8");
+  }
+  const payload = {
+    [idKey]: `${prefix}-${slug}`,
+    name,
+    ...meta,
+  };
+  fs.writeFileSync(metaPath, yaml.dump(payload, { lineWidth: 120 }), "utf8");
+
+  syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
+
+  return {
+    id: payload[idKey],
+    prose_path: prosePath,
+    meta_path: metaPath,
+    project_id: projectId ?? null,
+    universe_id: universeId ?? null,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Database setup
 // ---------------------------------------------------------------------------
 const db = openDb(DB_PATH);
 
+process.stderr.write(`[mcp-writing] Sync dir: ${SYNC_DIR_ABS}\n`);
+process.stderr.write(`[mcp-writing] DB path: ${DB_PATH_DISPLAY}\n`);
+
 // Check sync dir writability once at startup (needed for Phase 2 sidecar writes)
 const SYNC_DIR_WRITABLE = isSyncDirWritable(SYNC_DIR);
 if (!SYNC_DIR_WRITABLE) {
   process.stderr.write(`[mcp-writing] WARNING: sync dir is not writable — sidecar auto-migration and metadata write-back will be unavailable\n`);
 }
 
+// Check git availability and initialize repository if needed (Phase 3)
+const GIT_AVAILABLE = isGitAvailable();
+let GIT_ENABLED = false;
+if (GIT_AVAILABLE && SYNC_DIR_WRITABLE) {
+  if (!isGitRepository(SYNC_DIR)) {
+    try {
+      initGitRepository(SYNC_DIR);
+      process.stderr.write(`[mcp-writing] Initialized git repository at ${SYNC_DIR}\n`);
+      GIT_ENABLED = true;
+    } catch (err) {
+      process.stderr.write(`[mcp-writing] WARNING: Failed to initialize git repository: ${err.message}\n`);
+    }
+  } else {
+    GIT_ENABLED = true;
+    process.stderr.write(`[mcp-writing] Git repository detected at ${SYNC_DIR} — Phase 3 editing tools enabled\n`);
+  }
+} else if (!GIT_AVAILABLE) {
+  process.stderr.write(`[mcp-writing] WARNING: git not found on PATH — Phase 3 editing tools will be unavailable\n`);
+} else if (!SYNC_DIR_WRITABLE) {
+  process.stderr.write(`[mcp-writing] NOTE: sync dir is read-only — Phase 3 editing tools will be unavailable\n`);
+}
+
+// In-memory storage for pending edit proposals (Phase 3)
+const pendingProposals = new Map();
+let nextProposalId = 1;
+function generateProposalId() {
+  return `proposal-${nextProposalId++}`;
+}
+
 // Run sync on startup
 syncAll(db, SYNC_DIR, { writable: SYNC_DIR_WRITABLE });
 
@@ -122,6 +271,23 @@ function createMcpServer() {
     return { content: [{ type: "text", text: parts.join(" ") }] };
   });
 
+  // ---- get_runtime_config --------------------------------------------------
+  s.tool(
+    "get_runtime_config",
+    "Show the active runtime paths and capabilities for this server instance (sync dir, database path, writability, and git availability). Use this to verify which manuscript location is currently connected.",
+    {},
+    async () => {
+      return jsonResponse({
+        sync_dir: SYNC_DIR_ABS,
+        db_path: DB_PATH_DISPLAY,
+        sync_dir_writable: SYNC_DIR_WRITABLE,
+        git_available: GIT_AVAILABLE,
+        git_enabled: GIT_ENABLED,
+        http_port: HTTP_PORT,
+      });
+    }
+  );
+
   // ---- find_scenes ---------------------------------------------------------
   s.tool(
     "find_scenes",
@@ -203,22 +369,34 @@ function createMcpServer() {
   // ---- get_scene_prose -----------------------------------------------------
   s.tool(
     "get_scene_prose",
-    "Load the full prose text of a single scene. Use this for close reading, continuity checks, or when you need the actual writing. For overview or filtering, use find_scenes instead — it is much cheaper.",
+    "Load the full prose text of a single scene. Use this for close reading, continuity checks, or when you need the actual writing. For overview or filtering, use find_scenes instead — it is much cheaper. Optionally retrieve a past version from git history.",
     {
       scene_id: z.string().describe("The scene_id to retrieve (e.g. 'sc-001-prologue'). Get this from find_scenes or get_arc."),
+      commit: z.string().optional().describe("Optional git commit hash to retrieve a past version. Use list_snapshots to find valid hashes. If omitted, returns the current prose."),
     },
-    async ({ scene_id }) => {
+    async ({ scene_id, commit }) => {
       const scene = db.prepare(`SELECT file_path, metadata_stale FROM scenes WHERE scene_id = ?`).get(scene_id);
       if (!scene) {
         return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found. Run sync() if you just added it.`);
       }
       try {
-        const raw = fs.readFileSync(scene.file_path, "utf8");
-        const { content: prose } = matter(raw);
-        const warning = scene.metadata_stale
+        let rawContent;
+        if (commit && GIT_ENABLED) {
+          // Retrieve from git history
+          rawContent = getSceneProseAtCommit(SYNC_DIR, scene.file_path, commit);
+        } else if (commit && !GIT_ENABLED) {
+          return errorResponse("GIT_UNAVAILABLE", "Git is not available — cannot retrieve historical versions.");
+        } else {
+          // Retrieve current version
+          rawContent = fs.readFileSync(scene.file_path, "utf8");
+        }
+
+        const { content: prose } = matter(rawContent);
+        const versionNote = commit ? `\n\n(Retrieved from commit: ${commit})` : "";
+        const warning = scene.metadata_stale && !commit
           ? `\n\n⚠️ Metadata for this scene may be stale — prose has changed since last enrichment.`
           : "";
-        return { content: [{ type: "text", text: prose.trim() + warning }] };
+        return { content: [{ type: "text", text: prose.trim() + versionNote + warning }] };
       } catch (err) {
         if (err.code === "ENOENT") {
           return errorResponse(
@@ -352,7 +530,7 @@ function createMcpServer() {
   // ---- get_character_sheet -------------------------------------------------
   s.tool(
     "get_character_sheet",
-    "Get full character details: role, arc_summary, traits, and the full content of the character notes file. Use list_characters first to get the character_id.",
+    "Get full character details: role, arc_summary, traits, the canonical sheet content, and any adjacent support notes when the character uses a folder-based layout. Use list_characters first to get the character_id.",
     {
       character_id: z.string().describe("The character_id to look up (e.g. 'char-sebastian'). Use list_characters to find valid IDs."),
     },
@@ -366,19 +544,67 @@ function createMcpServer() {
         .all(character_id).map(r => r.trait);
 
       let notes = "";
+      let supportingNotes = [];
       if (character.file_path) {
         try {
           const raw = fs.readFileSync(character.file_path, "utf8");
           const { content } = matter(raw);
           notes = content.trim();
-        } catch {}
+          supportingNotes = readSupportingNotesForEntity(character.file_path);
+        } catch { /* empty */ }
       }
 
-      const result = { ...character, traits, notes: notes || undefined };
+      const result = {
+        ...character,
+        traits,
+        notes: notes || undefined,
+        supporting_notes: supportingNotes.length ? supportingNotes : undefined,
+      };
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
 
+  // ---- create_character_sheet ---------------------------------------------
+  s.tool(
+    "create_character_sheet",
+    "Create a canonical character sheet folder with sheet.md and sheet.meta.yaml so the character can be indexed immediately. Use this before migrating freeform notes into the new folder structure.",
+    {
+      name: z.string().describe("Display name of the character (e.g. 'Mira Nystrom')."),
+      project_id: z.string().optional().describe("Project scope for a book-local character (e.g. 'universe-1/book-1-the-lamb' or 'test-novel')."),
+      universe_id: z.string().optional().describe("Universe scope for a cross-book shared character (e.g. 'universe-1')."),
+      notes: z.string().optional().describe("Optional starter prose content for sheet.md."),
+      fields: z.object({
+        role: z.string().optional(),
+        arc_summary: z.string().optional(),
+        first_appearance: z.string().optional(),
+        traits: z.array(z.string()).optional(),
+      }).optional().describe("Optional starter metadata fields for the character sidecar."),
+    },
+    async ({ name, project_id, universe_id, notes, fields }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot create character sheet: sync dir is read-only.");
+      }
+      if ((project_id && universe_id) || (!project_id && !universe_id)) {
+        return errorResponse("VALIDATION_ERROR", "Provide exactly one of project_id or universe_id.");
+      }
+
+      try {
+        const created = createCanonicalWorldEntity({
+          kind: "character",
+          name,
+          notes,
+          projectId: project_id,
+          universeId: universe_id,
+          meta: fields ?? {},
+        });
+
+        return jsonResponse({ ok: true, action: "created", kind: "character", ...created });
+      } catch (err) {
+        return errorResponse("IO_ERROR", `Failed to create character sheet: ${err.message}`);
+      }
+    }
+  );
+
   // ---- list_places ---------------------------------------------------------
   s.tool(
     "list_places",
@@ -404,6 +630,87 @@ function createMcpServer() {
     }
   );
 
+  // ---- create_place_sheet -------------------------------------------------
+  s.tool(
+    "create_place_sheet",
+    "Create a canonical place sheet folder with sheet.md and sheet.meta.yaml so the place can be indexed immediately. Use this before migrating freeform notes into the new folder structure.",
+    {
+      name: z.string().describe("Display name of the place (e.g. 'University Hospital')."),
+      project_id: z.string().optional().describe("Project scope for a book-local place (e.g. 'universe-1/book-1-the-lamb' or 'test-novel')."),
+      universe_id: z.string().optional().describe("Universe scope for a cross-book shared place (e.g. 'universe-1')."),
+      notes: z.string().optional().describe("Optional starter prose content for sheet.md."),
+      fields: z.object({
+        associated_characters: z.array(z.string()).optional(),
+        tags: z.array(z.string()).optional(),
+      }).optional().describe("Optional starter metadata fields for the place sidecar."),
+    },
+    async ({ name, project_id, universe_id, notes, fields }) => {
+      if (!SYNC_DIR_WRITABLE) {
+        return errorResponse("READ_ONLY", "Cannot create place sheet: sync dir is read-only.");
+      }
+      if ((project_id && universe_id) || (!project_id && !universe_id)) {
+        return errorResponse("VALIDATION_ERROR", "Provide exactly one of project_id or universe_id.");
+      }
+
+      try {
+        const created = createCanonicalWorldEntity({
+          kind: "place",
+          name,
+          notes,
+          projectId: project_id,
+          universeId: universe_id,
+          meta: fields ?? {},
+        });
+
+        return jsonResponse({ ok: true, action: "created", kind: "place", ...created });
+      } catch (err) {
+        return errorResponse("IO_ERROR", `Failed to create place sheet: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- get_place_sheet -----------------------------------------------------
+  s.tool(
+    "get_place_sheet",
+    "Get full place details: associated_characters, tags, the canonical sheet content, and any adjacent support notes when the place uses a folder-based layout. Use list_places first to get the place_id.",
+    {
+      place_id: z.string().describe("The place_id to look up (e.g. 'place-harbor-district'). Use list_places to find valid IDs."),
+    },
+    async ({ place_id }) => {
+      const place = db.prepare(`SELECT * FROM places WHERE place_id = ?`).get(place_id);
+      if (!place) {
+        return errorResponse("NOT_FOUND", `Place '${place_id}' not found.`);
+      }
+
+      let notes = "";
+      let supportingNotes = [];
+      let associatedCharacters = [];
+      let tags = [];
+
+      if (place.file_path) {
+        try {
+          const raw = fs.readFileSync(place.file_path, "utf8");
+          const { content } = matter(raw);
+          notes = content.trim();
+          supportingNotes = readSupportingNotesForEntity(place.file_path);
+
+          const meta = readEntityMetadata(place.file_path);
+          associatedCharacters = Array.isArray(meta.associated_characters) ? meta.associated_characters : [];
+          tags = Array.isArray(meta.tags) ? meta.tags : [];
+        } catch { /* empty */ }
+      }
+
+      const result = {
+        ...place,
+        associated_characters: associatedCharacters.length ? associatedCharacters : undefined,
+        tags: tags.length ? tags : undefined,
+        notes: notes || undefined,
+        supporting_notes: supportingNotes.length ? supportingNotes : undefined,
+      };
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+
   // ---- search_metadata -----------------------------------------------------
   s.tool(
     "search_metadata",
@@ -779,7 +1086,7 @@ function createMcpServer() {
     {
       scene_id:   z.string().describe("The scene_id to flag (e.g. 'sc-012-open-to-anyone')."),
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
-      note:       z.string().describe("The flag note (e.g. 'Victor knows Mira\'s name here, but they haven\'t been introduced yet — contradicts sc-006')."),
+      note:       z.string().describe("The flag note (e.g. 'Victor knows Mira\u2019s name here, but they haven\u2019t been introduced yet \u2014 contradicts sc-006')."),
     },
     async ({ scene_id, project_id, note }) => {
       if (!SYNC_DIR_WRITABLE) {
@@ -835,6 +1142,249 @@ function createMcpServer() {
     }
   );
 
+  // ---- PHASE 3: Prose Editing (git-backed) --------------------------------
+
+  // ---- propose_edit --------------------------------------------------------
+  s.tool(
+    "propose_edit",
+    "Generate a proposed revision for a scene. Returns a proposal_id and a diff preview. Nothing is written yet — you must call commit_edit to apply the change. This tool requires git to be available.",
+    {
+      scene_id: z.string().describe("The scene_id to revise (e.g. 'sc-011-sebastian')."),
+      instruction: z.string().describe("A brief instruction for the edit (e.g. 'Tighten the opening paragraph'). Used in the git commit message."),
+      revised_prose: z.string().describe("The complete revised prose text for the scene."),
+    },
+    async ({ scene_id, instruction, revised_prose }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported. Ensure git is installed and the sync directory is writable.");
+      }
+
+      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+      }
+
+      try {
+        // Read current prose
+        const raw = fs.readFileSync(scene.file_path, "utf8");
+        const { data: metadata, content: currentProse } = matter(raw);
+
+        // Generate a simple diff representation
+        const currentLines = currentProse.trim().split("\n");
+        const revisedLines = revised_prose.trim().split("\n");
+        const diffLines = [];
+        const maxLines = Math.max(currentLines.length, revisedLines.length);
+
+        // Simple line-by-line diff
+        for (let i = 0; i < Math.min(3, maxLines); i++) {
+          const curr = currentLines[i] || "(removed)";
+          const rev = revisedLines[i] || "(removed)";
+          if (curr !== rev) {
+            diffLines.push(`- ${curr.substring(0, 80)}`);
+            diffLines.push(`+ ${rev.substring(0, 80)}`);
+          }
+        }
+        if (maxLines > 3) {
+          diffLines.push(`... (${maxLines - 3} more lines)`);
+        }
+
+        const proposalId = generateProposalId();
+        pendingProposals.set(proposalId, {
+          scene_id,
+          scene_file_path: scene.file_path,
+          instruction,
+          revised_prose,
+          original_prose: currentProse,
+          metadata,
+          created_at: new Date().toISOString(),
+        });
+
+        const summary = {
+          proposal_id: proposalId,
+          scene_id,
+          instruction,
+          diff_preview: diffLines.join("\n"),
+          note: "Review the diff above. Call commit_edit with this proposal_id to apply the change.",
+        };
+
+        return jsonResponse(summary);
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file for scene '${scene_id}' not found at indexed path.`, { indexed_path: scene.file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to read scene file: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- commit_edit ---------------------------------------------------------
+  s.tool(
+    "commit_edit",
+    "Apply a proposed edit and commit it to git. First creates a pre-edit snapshot, then writes the revised prose and metadata back to disk. The scene metadata stale flag is cleared.",
+    {
+      scene_id: z.string().describe("The scene_id being revised."),
+      proposal_id: z.string().describe("The proposal_id returned by propose_edit."),
+    },
+    async ({ scene_id, proposal_id }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — prose editing is not supported.");
+      }
+
+      const proposal = pendingProposals.get(proposal_id);
+      if (!proposal) {
+        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has expired.`);
+      }
+
+      if (proposal.scene_id !== scene_id) {
+        return errorResponse("INVALID_EDIT", `Proposal '${proposal_id}' is for scene '${proposal.scene_id}', not '${scene_id}'.`);
+      }
+
+      try {
+        // Reconstruct file content, preserving frontmatter only if the original had it
+        const hasFrontmatter = proposal.metadata && Object.keys(proposal.metadata).length > 0;
+        const content = hasFrontmatter
+          ? `---\n${yaml.dump(proposal.metadata)}---\n\n${proposal.revised_prose}\n`
+          : `${proposal.revised_prose}\n`;
+
+        // Create pre-edit snapshot (commits current state before overwriting)
+        const snapshot = createSnapshot(SYNC_DIR, proposal.scene_file_path, scene_id, proposal.instruction);
+
+        // Write the revised prose to disk
+        fs.writeFileSync(proposal.scene_file_path, content, "utf8");
+
+        // Re-index using canonical metadata (sidecar takes precedence over inline frontmatter)
+        const { meta: canonicalMeta } = readMeta(proposal.scene_file_path, SYNC_DIR, { writable: false });
+        const { content: newProse } = matter(content);
+        indexSceneFile(db, SYNC_DIR, proposal.scene_file_path, canonicalMeta, newProse);
+
+        // Clean up the proposal
+        pendingProposals.delete(proposal_id);
+
+        const result = {
+          ok: true,
+          scene_id,
+          proposal_id,
+          snapshot_commit: snapshot.commit_hash,
+          message: `Committed edit for scene '${scene_id}'${snapshot.commit_hash ? ` (snapshot: ${snapshot.commit_hash.substring(0, 7)})` : " (no changes to snapshot)"}`,
+        };
+
+        return jsonResponse(result);
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file not found at indexed path.`, { indexed_path: proposal.scene_file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to commit edit: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- discard_edit --------------------------------------------------------
+  s.tool(
+    "discard_edit",
+    "Discard a pending proposal without applying it. The proposal is deleted and the prose remains unchanged.",
+    {
+      proposal_id: z.string().describe("The proposal_id to discard (from propose_edit)."),
+    },
+    async ({ proposal_id }) => {
+      const proposal = pendingProposals.get(proposal_id);
+      if (!proposal) {
+        return errorResponse("PROPOSAL_NOT_FOUND", `Proposal '${proposal_id}' not found or has already been discarded.`);
+      }
+
+      pendingProposals.delete(proposal_id);
+      return jsonResponse({
+        ok: true,
+        proposal_id,
+        message: `Discarded proposal '${proposal_id}' for scene '${proposal.scene_id}'.`,
+      });
+    }
+  );
+
+  // ---- snapshot_scene -------------------------------------------------------
+  s.tool(
+    "snapshot_scene",
+    "Manually create a git commit (snapshot) for the current state of a scene. Use this to mark important editing checkpoints outside of the propose/commit workflow.",
+    {
+      scene_id: z.string().describe("The scene_id to snapshot."),
+      project_id: z.string().describe("Project the scene belongs to."),
+      reason: z.string().describe("A brief reason for the snapshot (e.g. 'Character arc milestone reached')."),
+    },
+    async ({ scene_id, project_id, reason }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be created.");
+      }
+
+      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ? AND project_id = ?`)
+        .get(scene_id, project_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found in project '${project_id}'.`);
+      }
+
+      try {
+        const snapshot = createSnapshot(SYNC_DIR, scene.file_path, scene_id, reason);
+        if (!snapshot.commit_hash) {
+          return jsonResponse({
+            ok: true,
+            scene_id,
+            reason,
+            message: "No changes to snapshot.",
+          });
+        }
+
+        return jsonResponse({
+          ok: true,
+          scene_id,
+          reason,
+          commit_hash: snapshot.commit_hash,
+          message: `Created snapshot for scene '${scene_id}': ${reason}`,
+        });
+      } catch (err) {
+        if (err.code === "ENOENT") {
+          return errorResponse("STALE_PATH", `Prose file not found at indexed path.`, { indexed_path: scene.file_path });
+        }
+        return errorResponse("IO_ERROR", `Failed to create snapshot: ${err.message}`);
+      }
+    }
+  );
+
+  // ---- list_snapshots -------------------------------------------------------
+  s.tool(
+    "list_snapshots",
+    "List git commit history for a scene, with timestamps and commit messages. Use this to find commit hashes for get_scene_prose historical retrieval.",
+    {
+      scene_id: z.string().describe("The scene_id to list snapshots for."),
+    },
+    async ({ scene_id }) => {
+      if (!GIT_ENABLED) {
+        return errorResponse("GIT_UNAVAILABLE", "Git is not available — snapshots cannot be retrieved.");
+      }
+
+      const scene = db.prepare(`SELECT file_path FROM scenes WHERE scene_id = ?`).get(scene_id);
+      if (!scene) {
+        return errorResponse("NOT_FOUND", `Scene '${scene_id}' not found.`);
+      }
+
+      try {
+        const snapshots = listSnapshots(SYNC_DIR, scene.file_path);
+        if (!snapshots || snapshots.length === 0) {
+          return errorResponse("NO_RESULTS", `No snapshots found for scene '${scene_id}'. Try editing and committing the scene first.`);
+        }
+
+        return jsonResponse({
+          scene_id,
+          snapshots: snapshots.map(s => ({
+            commit_hash: s.commit_hash,
+            short_hash: s.commit_hash.substring(0, 7),
+            timestamp: s.timestamp,
+            message: s.message,
+          })),
+          note: "Use the commit_hash values with get_scene_prose(scene_id, commit) to retrieve a past version.",
+        });
+      } catch (err) {
+        return errorResponse("IO_ERROR", `Failed to list snapshots: ${err.message}`);
+      }
+    }
+  );
+
   return s;
 }
 
@@ -850,8 +1400,8 @@ const httpServer = http.createServer(async (req, res) => {
 
     const existing = activeSessions.get(sessionId);
     if (existing) {
-      try { await existing.transport.close(); } catch {}
-      try { await existing.server.close(); } catch {}
+      try { await existing.transport.close(); } catch { /* empty */ }
+      try { await existing.server.close(); } catch { /* empty */ }
       activeSessions.delete(sessionId);
     }