@velvetmonkey/flywheel-crank 0.1.0 → 0.2.0

package/README.md

@@ -14,7 +14,7 @@ While **Flywheel** provides read-only graph intelligence (backlinks, queries, st
 - Toggle and create tasks
 - Update frontmatter
 - Create and delete notes
-- Auto-commit with undo support
+- Optional git commits with undo support
 
 ## Installation
 
@@ -27,10 +27,7 @@ Add to your project's `.mcp.json` (in your vault root). **Zero-config** if `.mcp
   "mcpServers": {
     "flywheel-crank": {
       "command": "npx",
-      "args": ["-y", "@velvetmonkey/flywheel-crank"],
-      "env": {
-        "AUTO_COMMIT": "true"
-      }
+      "args": ["-y", "@velvetmonkey/flywheel-crank"]
     }
   }
 }
@@ -52,8 +49,7 @@ If `.mcp.json` is NOT in your vault, set `PROJECT_PATH`:
       "command": "npx",
       "args": ["-y", "@velvetmonkey/flywheel-crank"],
       "env": {
-        "PROJECT_PATH": "/path/to/your/vault",
-        "AUTO_COMMIT": "true"
+        "PROJECT_PATH": "/path/to/your/vault"
       }
     }
   }
@@ -69,8 +65,7 @@ If `.mcp.json` is NOT in your vault, set `PROJECT_PATH`:
       "command": "cmd",
       "args": ["/c", "npx", "-y", "@velvetmonkey/flywheel-crank"],
       "env": {
-        "PROJECT_PATH": "C:/Users/yourname/path/to/vault",
-        "AUTO_COMMIT": "true"
+        "PROJECT_PATH": "C:/Users/yourname/path/to/vault"
       }
     }
   }
@@ -83,10 +78,10 @@ If `.mcp.json` is NOT in your vault, set `PROJECT_PATH`:
 
 ```bash
 # Zero-config (run from vault directory)
-claude mcp add flywheel-crank -e AUTO_COMMIT=true -- npx -y @velvetmonkey/flywheel-crank
+claude mcp add flywheel-crank -- npx -y @velvetmonkey/flywheel-crank
 
 # With explicit vault path
-claude mcp add flywheel-crank -e PROJECT_PATH=/path/to/vault -e AUTO_COMMIT=true -- npx -y @velvetmonkey/flywheel-crank
+claude mcp add flywheel-crank -e PROJECT_PATH=/path/to/vault -- npx -y @velvetmonkey/flywheel-crank
 ```
 
 ### Verify
@@ -105,18 +100,65 @@ claude mcp list  # Should show: flywheel-crank
 | Notes | `vault_create_note`, `vault_delete_note` |
 | System | `vault_list_sections`, `vault_undo_last_mutation` |
 
+## The `commit` Parameter (Undo Support)
+
+Every mutation tool has an optional `commit` parameter. Here's what it does and why you'd use it:
+
+### What is a commit?
+
+If your vault is tracked with **git** (a version control system), setting `commit: true` creates a **save point** after each change. Think of it like a checkpoint in a video game - you can always go back to it.
+
+### Why use it?
+
+| `commit: false` (default) | `commit: true` |
+|---------------------------|----------------|
+| Changes saved to file immediately | Changes saved AND recorded in git history |
+| No undo available | Can undo with `vault_undo_last_mutation` |
+| Faster (no git overhead) | Slightly slower |
+| Good for: bulk edits, testing | Good for: important changes you might want to reverse |
+
+### Example
+
+```javascript
+// Without commit - change is made, no undo available
+vault_add_to_section({
+  path: "daily/2026-01-28.md",
+  section: "Log",
+  content: "Meeting with team"
+})
+
+// With commit - change is made AND you can undo it later
+vault_add_to_section({
+  path: "daily/2026-01-28.md",
+  section: "Log",
+  content: "Meeting with team",
+  commit: true  // Creates undo point
+})
+```
+
+### Undoing a change
+
+If you used `commit: true`, you can undo with:
+
+```javascript
+vault_undo_last_mutation({ confirm: true })
+```
+
+This reverts your vault to the state before the last committed change.
+
+> **Note**: Undo only works if your vault is a git repository. Most Obsidian users who sync via git already have this set up. If you're unsure, the tool will tell you if undo isn't available.
+
 ## Configuration
 
 | Environment Variable | Required | Default | Description |
 |---------------------|:--------:|---------|-------------|
 | `PROJECT_PATH` | No | `cwd()` | Path to markdown vault directory |
-| `AUTO_COMMIT` | No | `false` | Auto-commit mutations to git |
 
 ## Design Principles
 
 - **Deterministic**: No AI-driven edits, predictable output
 - **Atomic**: Each mutation is a single, reversible operation
-- **Safe**: Path sandboxing, auto-commit, undo support
+- **Safe**: Path sandboxing, explicit commit opt-in, undo support
 - **Obsidian-compatible**: Follows Obsidian conventions (task format, wikilinks, etc.)
 
 ## Flywheel + Crank
@@ -132,8 +174,7 @@ Use both together for full vault intelligence:
     },
     "flywheel-crank": {
       "command": "npx",
-      "args": ["-y", "@velvetmonkey/flywheel-crank"],
-      "env": { "AUTO_COMMIT": "true" }
+      "args": ["-y", "@velvetmonkey/flywheel-crank"]
     }
   }
 }
@@ -144,7 +185,7 @@ Use both together for full vault intelligence:
 
 ## License
 
-AGPL-3.0 — [Ben Cassie](https://github.com/velvetmonkey)
+AGPL-3.0 — [velvetmonkey](https://github.com/velvetmonkey)
 
 ## Links
 

package/dist/index.js

@@ -308,7 +308,7 @@ async function undoLastCommit(vaultPath2) {
 // src/tools/mutations.ts
 import fs2 from "fs/promises";
 import path3 from "path";
-function registerMutationTools(server2, vaultPath2, autoCommit2) {
+function registerMutationTools(server2, vaultPath2) {
   server2.tool(
     "vault_add_to_section",
     "Add content to a specific section in a markdown note",
@@ -317,9 +317,10 @@ function registerMutationTools(server2, vaultPath2, autoCommit2) {
       section: z.string().describe('Heading text to add to (e.g., "Log" or "## Log")'),
       content: z.string().describe("Content to add to the section"),
       position: z.enum(["append", "prepend"]).default("append").describe("Where to insert content"),
-      format: z.enum(["plain", "bullet", "task", "numbered", "timestamp-bullet"]).default("plain").describe("How to format the content")
+      format: z.enum(["plain", "bullet", "task", "numbered", "timestamp-bullet"]).default("plain").describe("How to format the content"),
+      commit: z.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, section, content, position, format }) => {
+    async ({ path: notePath, section, content, position, format, commit }) => {
       try {
         const fullPath = path3.join(vaultPath2, notePath);
         try {
@@ -352,7 +353,7 @@ function registerMutationTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, updatedContent, frontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Add]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -388,9 +389,10 @@ function registerMutationTools(server2, vaultPath2, autoCommit2) {
       section: z.string().describe('Heading text to remove from (e.g., "Log" or "## Log")'),
       pattern: z.string().describe("Text or pattern to match for removal"),
       mode: z.enum(["first", "last", "all"]).default("first").describe("Which matches to remove"),
-      useRegex: z.boolean().default(false).describe("Treat pattern as regex")
+      useRegex: z.boolean().default(false).describe("Treat pattern as regex"),
+      commit: z.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, section, pattern, mode, useRegex }) => {
+    async ({ path: notePath, section, pattern, mode, useRegex, commit }) => {
       try {
         const fullPath = path3.join(vaultPath2, notePath);
         try {
@@ -431,7 +433,7 @@ function registerMutationTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, removeResult.content, frontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Remove]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -467,9 +469,10 @@ function registerMutationTools(server2, vaultPath2, autoCommit2) {
       search: z.string().describe("Text or pattern to search for"),
       replacement: z.string().describe("Text to replace with"),
       mode: z.enum(["first", "last", "all"]).default("first").describe("Which matches to replace"),
-      useRegex: z.boolean().default(false).describe("Treat search as regex")
+      useRegex: z.boolean().default(false).describe("Treat search as regex"),
+      commit: z.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, section, search, replacement, mode, useRegex }) => {
+    async ({ path: notePath, section, search, replacement, mode, useRegex, commit }) => {
       try {
         const fullPath = path3.join(vaultPath2, notePath);
         try {
@@ -511,7 +514,7 @@ function registerMutationTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, replaceResult.content, frontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Replace]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -592,16 +595,17 @@ function toggleTask(content, lineNumber) {
     newState
   };
 }
-function registerTaskTools(server2, vaultPath2, autoCommit2) {
+function registerTaskTools(server2, vaultPath2) {
   server2.tool(
     "vault_toggle_task",
     "Toggle a task checkbox between checked and unchecked",
     {
       path: z2.string().describe("Vault-relative path to the note"),
       task: z2.string().describe("Task text to find (partial match supported)"),
-      section: z2.string().optional().describe("Optional: limit search to this section")
+      section: z2.string().optional().describe("Optional: limit search to this section"),
+      commit: z2.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, task, section }) => {
+    async ({ path: notePath, task, section, commit }) => {
       try {
         const fullPath = path4.join(vaultPath2, notePath);
         try {
@@ -653,7 +657,7 @@ function registerTaskTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, toggleResult.content, frontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Task]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -690,9 +694,10 @@ function registerTaskTools(server2, vaultPath2, autoCommit2) {
       section: z2.string().describe("Section to add the task to"),
       task: z2.string().describe("Task text (without checkbox)"),
       position: z2.enum(["append", "prepend"]).default("append").describe("Where to add the task"),
-      completed: z2.boolean().default(false).describe("Whether the task should start as completed")
+      completed: z2.boolean().default(false).describe("Whether the task should start as completed"),
+      commit: z2.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, section, task, position, completed }) => {
+    async ({ path: notePath, section, task, position, completed, commit }) => {
       try {
         const fullPath = path4.join(vaultPath2, notePath);
         try {
@@ -726,7 +731,7 @@ function registerTaskTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, updatedContent, frontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Task]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -760,15 +765,16 @@ function registerTaskTools(server2, vaultPath2, autoCommit2) {
 import { z as z3 } from "zod";
 import fs4 from "fs/promises";
 import path5 from "path";
-function registerFrontmatterTools(server2, vaultPath2, autoCommit2) {
+function registerFrontmatterTools(server2, vaultPath2) {
   server2.tool(
     "vault_update_frontmatter",
     "Update frontmatter fields in a note (merge with existing frontmatter)",
     {
       path: z3.string().describe("Vault-relative path to the note"),
-      frontmatter: z3.record(z3.any()).describe("Frontmatter fields to update (JSON object)")
+      frontmatter: z3.record(z3.any()).describe("Frontmatter fields to update (JSON object)"),
+      commit: z3.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, frontmatter: updates }) => {
+    async ({ path: notePath, frontmatter: updates, commit }) => {
       try {
         const fullPath = path5.join(vaultPath2, notePath);
         try {
@@ -786,7 +792,7 @@ function registerFrontmatterTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, content, updatedFrontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:FM]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -821,9 +827,10 @@ function registerFrontmatterTools(server2, vaultPath2, autoCommit2) {
     {
       path: z3.string().describe("Vault-relative path to the note"),
       key: z3.string().describe("Field name to add"),
-      value: z3.any().describe("Field value (string, number, boolean, array, object)")
+      value: z3.any().describe("Field value (string, number, boolean, array, object)"),
+      commit: z3.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, key, value }) => {
+    async ({ path: notePath, key, value, commit }) => {
       try {
         const fullPath = path5.join(vaultPath2, notePath);
         try {
@@ -849,7 +856,7 @@ function registerFrontmatterTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, content, updatedFrontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:FM]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -883,7 +890,7 @@ function registerFrontmatterTools(server2, vaultPath2, autoCommit2) {
 import { z as z4 } from "zod";
 import fs5 from "fs/promises";
 import path6 from "path";
-function registerNoteTools(server2, vaultPath2, autoCommit2) {
+function registerNoteTools(server2, vaultPath2) {
   server2.tool(
     "vault_create_note",
     "Create a new note in the vault with optional frontmatter and content",
@@ -891,9 +898,10 @@ function registerNoteTools(server2, vaultPath2, autoCommit2) {
       path: z4.string().describe('Vault-relative path for the new note (e.g., "daily-notes/2026-01-28.md")'),
       content: z4.string().default("").describe("Initial content for the note"),
       frontmatter: z4.record(z4.any()).default({}).describe("Frontmatter fields (JSON object)"),
-      overwrite: z4.boolean().default(false).describe("If true, overwrite existing file")
+      overwrite: z4.boolean().default(false).describe("If true, overwrite existing file"),
+      commit: z4.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, content, frontmatter, overwrite }) => {
+    async ({ path: notePath, content, frontmatter, overwrite, commit }) => {
       try {
         if (!validatePath(vaultPath2, notePath)) {
           const result2 = {
@@ -921,7 +929,7 @@ function registerNoteTools(server2, vaultPath2, autoCommit2) {
         await writeVaultFile(vaultPath2, notePath, content, frontmatter);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Create]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -954,9 +962,10 @@ Content length: ${content.length} chars`,
     "Delete a note from the vault",
     {
       path: z4.string().describe("Vault-relative path to the note to delete"),
-      confirm: z4.boolean().default(false).describe("Must be true to confirm deletion")
+      confirm: z4.boolean().default(false).describe("Must be true to confirm deletion"),
+      commit: z4.boolean().default(false).describe("If true, commit this change to git (creates undo point)")
     },
-    async ({ path: notePath, confirm }) => {
+    async ({ path: notePath, confirm, commit }) => {
       try {
         if (!confirm) {
           const result2 = {
@@ -988,7 +997,7 @@ Content length: ${content.length} chars`,
         await fs5.unlink(fullPath);
         let gitCommit;
         let gitError;
-        if (autoCommit2) {
+        if (commit) {
           const gitResult = await commitChange(vaultPath2, notePath, "[Crank:Delete]");
           if (gitResult.success) {
             gitCommit = gitResult.hash;
@@ -1021,7 +1030,7 @@ Content length: ${content.length} chars`,
 import { z as z5 } from "zod";
 import fs6 from "fs/promises";
 import path7 from "path";
-function registerSystemTools(server2, vaultPath2, autoCommit2) {
+function registerSystemTools(server2, vaultPath2) {
   server2.tool(
     "vault_list_sections",
     "List all sections (headings) in a markdown note",
@@ -1107,14 +1116,6 @@ Date: ${lastCommit.date}`
           };
           return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
         }
-        if (!autoCommit2) {
-          const result2 = {
-            success: false,
-            message: 'Undo is only available when AUTO_COMMIT is enabled. Set AUTO_COMMIT="true" in .mcp.json to enable automatic git commits for each mutation.',
-            path: ""
-          };
-          return { content: [{ type: "text", text: JSON.stringify(result2, null, 2) }] };
-        }
         const isRepo = await isGitRepo(vaultPath2);
         if (!isRepo) {
           const result2 = {
@@ -1181,15 +1182,13 @@ var server = new McpServer({
   version: "0.1.0"
 });
 var vaultPath = process.env.PROJECT_PATH || findVaultRoot();
-var autoCommit = process.env.AUTO_COMMIT === "true";
 console.error(`[Crank] Starting Flywheel Crank MCP server`);
 console.error(`[Crank] Vault path: ${vaultPath}`);
-console.error(`[Crank] Auto-commit: ${autoCommit}`);
-registerMutationTools(server, vaultPath, autoCommit);
-registerTaskTools(server, vaultPath, autoCommit);
-registerFrontmatterTools(server, vaultPath, autoCommit);
-registerNoteTools(server, vaultPath, autoCommit);
-registerSystemTools(server, vaultPath, autoCommit);
+registerMutationTools(server, vaultPath);
+registerTaskTools(server, vaultPath);
+registerFrontmatterTools(server, vaultPath);
+registerNoteTools(server, vaultPath);
+registerSystemTools(server, vaultPath);
 var transport = new StdioServerTransport();
 await server.connect(transport);
 console.error(`[Crank] Flywheel Crank MCP server started successfully`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/flywheel-crank",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Deterministic vault mutations for Obsidian via MCP",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "url": "https://github.com/velvetmonkey/flywheel-crank/issues"
   },
   "homepage": "https://github.com/velvetmonkey/flywheel-crank#readme",
-  "author": "Ben Cassie",
+  "author": "velvetmonkey",
   "keywords": ["obsidian", "mcp", "model-context-protocol", "claude", "mutations", "vault-writes", "markdown"],
   "scripts": {
     "build": "npx esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external && chmod +x dist/index.js",