pkm-mcp-server 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-03-17
+
+### Added
+- `vault_capture` tool — signal a PKM-worthy capture (decision, task, research, bug); returns immediately while a background hook creates the note
+- PKM hook scripts for Claude Code integration:
+  - SessionStart hook (`session-start.js`) — loads project context from vault automatically
+  - PostToolUse hook (`capture-handler.sh`) — spawns Sonnet agent for explicit `vault_capture` calls
+  - Stop hook (`stop-sweep.sh`) — spawns Haiku agent for passive decision/task sweep at session end
+- Enum validation for task `status` (pending/active/done/cancelled) and `priority` (low/normal/high/urgent) fields in `vault_write` and `vault_update_frontmatter` — non-task note types are unaffected
+
+### Changed
+- `sqlite-vec` upgraded from pinned alpha (0.1.7-alpha.2) to stable release (0.1.7)
+- `@modelcontextprotocol/sdk` updated to 1.27.1
+- `better-sqlite3` updated to 12.8.0
+
+### Security
+- Resolved 7 transitive dependency vulnerabilities (hono, @hono/node-server, ajv, express-rate-limit, flatted, minimatch, qs)
+
 ## [1.1.0] - 2026-02-23
 
 ### Changed
@@ -55,6 +73,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Atomic file creation in `vault_write` (`wx` flag) prevents race conditions
 - Error messages sanitized to prevent leaking absolute vault paths
 
-[Unreleased]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/AdrianV101/Obsidian-MCP/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/AdrianV101/Obsidian-MCP/releases/tag/v1.0.0

package/README.md

@@ -36,12 +36,12 @@ https://github.com/user-attachments/assets/58ad9c9b-d987-4728-89e7-33de20b73a38
 | `vault_recent` | Recently modified files |
 | `vault_links` | Wikilink analysis (incoming/outgoing) |
 | `vault_neighborhood` | Graph exploration via BFS wikilink traversal |
-| `vault_query` | Query notes by YAML frontmatter (type, status, tags, dates, custom fields, sorting) |
+| `vault_query` | Query notes by YAML frontmatter (type, status, tags/tags_any, dates, custom fields, sorting) |
 | `vault_tags` | Discover tags with counts; folder scoping, glob filters, inline tag parsing |
 | `vault_activity` | Session activity log for cross-conversation memory |
 | `vault_trash` | Soft-delete to `.trash/` (Obsidian convention), warns about broken incoming links |
 | `vault_move` | Move/rename files with automatic wikilink updating across vault |
-| `vault_update_frontmatter` | Atomic YAML frontmatter updates (set, create, remove fields) |
+| `vault_update_frontmatter` | Atomic YAML frontmatter updates (set, create, remove fields; validates enum fields by note type) |
 
 ### Fuzzy Path Resolution
 
@@ -211,7 +211,7 @@ All paths passed to tools are relative to vault root. The server includes path s
 
 ## How It Works
 
-**Note creation** is template-based. `vault_write` loads templates from `05-Templates/`, substitutes Templater-compatible variables (`<% tp.date.now("YYYY-MM-DD") %>`, `<% tp.file.title %>`), and validates required frontmatter fields (`type`, `created`, `tags`).
+**Note creation** is template-based. `vault_write` loads templates from `05-Templates/`, substitutes Templater-compatible variables (`<% tp.date.now("YYYY-MM-DD") %>`, `<% tp.file.title %>`), and validates required frontmatter fields (`type`, `created`, `tags`). Optional frontmatter fields — `status`, `priority`, `project`, `deciders`, `due`, `source` — can be set per template type. Task notes enforce enum validation on `status` (pending/active/done/cancelled) and `priority` (low/normal/high/urgent).
 
 **Semantic search** embeds notes on startup and watches for changes via `fs.watch`. Long notes are chunked by `##` headings. The index is a regenerable cache stored in `.obsidian/` so it syncs across machines via Obsidian Sync. The initial sync runs in the background — search is available immediately but may return incomplete results until sync finishes (a progress message is shown).
 

package/handlers.js

@@ -848,6 +848,21 @@ export async function createHandlers({ vaultPath, templateRegistry, semanticInde
     };
   }
 
+  async function handleCapture(args) {
+    const { type, title, content } = args;
+    if (!type || !title || !content) {
+      throw new Error(
+        `vault_capture requires type, title, and content. Got: type=${type || "(missing)"}, title=${title || "(missing)"}, content=${content ? "provided" : "(missing)"}`
+      );
+    }
+    return {
+      content: [{
+        type: "text",
+        text: `Capture queued: [${type}] ${title}`
+      }]
+    };
+  }
+
   return new Map([
     ["vault_read", handleRead],
     ["vault_write", handleWrite],
@@ -867,5 +882,6 @@ export async function createHandlers({ vaultPath, templateRegistry, semanticInde
     ["vault_trash", handleTrash],
     ["vault_move", handleMove],
     ["vault_update_frontmatter", handleUpdateFrontmatter],
+    ["vault_capture", handleCapture],
   ]);
 }

package/helpers.js

@@ -12,6 +12,39 @@ const PRIORITY_RANKS = { urgent: 3, high: 2, normal: 1, low: 0 };
 const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
+// Canonical frontmatter field constraints, keyed by note type.
+// Used by vault_write (template-based) and vault_update_frontmatter (existing files).
+const FIELD_ENUMS = {
+  status: {
+    task: ["pending", "active", "done", "cancelled"],
+  },
+  priority: {
+    task: Object.keys(PRIORITY_RANKS),  // low, normal, high, urgent
+  },
+};
+
+/**
+ * Validate a frontmatter field value against FIELD_ENUMS for a given note type.
+ * Throws if the value is not in the allowed set.
+ *
+ * @param {string} fieldName - the frontmatter field (e.g. "status")
+ * @param {*} value - the value being set
+ * @param {string} noteType - the note's type field (e.g. "task")
+ */
+export function validateFieldEnum(fieldName, value, noteType) {
+  if (value === null || value === undefined) return;
+  const enumsByType = FIELD_ENUMS[fieldName];
+  if (!enumsByType) return;
+  const allowed = enumsByType[noteType];
+  if (!allowed) return;
+  const strValue = String(value);
+  if (!allowed.includes(strValue)) {
+    throw new Error(
+      `Invalid ${fieldName} "${strValue}" for type "${noteType}". Allowed values: ${allowed.join(", ")}`
+    );
+  }
+}
+
 /**
  * Compare two frontmatter values for sorting.
  * Smart ordering: priority uses custom ranks, dates sort chronologically, strings use localeCompare.
@@ -314,11 +347,18 @@ export function substituteTemplateVariables(content, vars) {
         }
       }
 
+      // Extract note type from template for enum validation
+      const typeMatch = frontmatterSection.match(/^type:\s*(.+)$/m);
+      const noteType = typeMatch ? typeMatch[1].trim() : null;
+
       for (const [key, value] of Object.entries(vars.frontmatter)) {
         if (key === "tags") continue;
         if (DANGEROUS_KEYS.has(key)) {
           throw new Error(`Disallowed frontmatter key: "${key}"`);
         }
+        if (noteType && typeof value === "string") {
+          validateFieldEnum(key, value, noteType);
+        }
         if (typeof value === "string") {
           if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(key)) {
             throw new Error(`Invalid frontmatter key: "${key}". Keys must start with a letter and contain only letters, digits, hyphens, or underscores.`);
@@ -843,6 +883,11 @@ export function updateFrontmatter(content, fields) {
           throw new Error("tags must be a non-empty array");
         }
       }
+      // Use the file's existing type (or the new type if being changed) for enum validation
+      const effectiveType = key === "type" ? undefined : (fields.type || parsed.type);
+      if (effectiveType) {
+        validateFieldEnum(key, value, String(effectiveType));
+      }
       parsed[key] = value;
     }
   }

package/index.js

@@ -115,8 +115,8 @@ Pass custom <%...%> variables via the 'variables' parameter.`,
             description: "Frontmatter fields to set (e.g., {tags: ['tag1', 'tag2'], status: 'active'})",
             properties: {
               tags: { type: "array", items: { type: "string" }, description: "Tags for the note (required)" },
-              status: { type: "string", description: "Note status" },
-              priority: { type: "string", description: "Priority level (for tasks)" },
+              status: { type: "string", description: "Note status. For tasks: pending, active, done, cancelled" },
+              priority: { type: "string", description: "Priority level. For tasks: low, normal, high, urgent" },
               project: { type: "string", description: "Project name (for devlogs)" },
               deciders: { type: "string", description: "Decision makers (for ADRs)" },
               due: { type: "string", description: "Due date (for tasks)" },
@@ -157,7 +157,7 @@ Pass custom <%...%> variables via the 'variables' parameter.`,
     },
     {
       name: "vault_update_frontmatter",
-      description: "Update YAML frontmatter fields in an existing note. Parses existing frontmatter, updates specified fields, preserves everything else. Set a field to null to remove it. Protected fields (type, created, tags) cannot be removed.",
+      description: "Update YAML frontmatter fields in an existing note. Parses existing frontmatter, updates specified fields, preserves everything else. Set a field to null to remove it. Protected fields (type, created, tags) cannot be removed. Field values are validated against the note's type (e.g. task status must be: pending, active, done, cancelled; task priority must be: low, normal, high, urgent).",
       inputSchema: {
         type: "object",
         properties: {
@@ -344,6 +344,40 @@ Pass custom <%...%> variables via the 'variables' parameter.`,
         },
         required: ["old_path", "new_path"]
       }
+    },
+    {
+      name: "vault_capture",
+      description: "Signal that something is worth capturing in the PKM vault. " +
+        "Returns immediately — a background agent handles the actual note creation. " +
+        "Use this when you identify a decision, task, or research finding worth preserving.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["adr", "task", "research", "bug"],
+            description: "The type of capture: adr (decision), task, research (finding/pattern), bug (issue/fix)"
+          },
+          title: {
+            type: "string",
+            description: "Brief descriptive title (e.g., 'Use sqlite-vec over Chroma')"
+          },
+          content: {
+            type: "string",
+            description: "The substance of the capture — context, rationale, details. 1-5 sentences."
+          },
+          priority: {
+            type: "string",
+            enum: ["low", "normal", "high", "urgent"],
+            description: "Priority level (tasks only, default: normal)"
+          },
+          project: {
+            type: "string",
+            description: "Project name for vault routing (e.g., 'Obsidian-MCP'). If omitted, inferred from session context."
+          }
+        },
+        required: ["type", "title", "content"]
+      }
     }
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pkm-mcp-server",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for Obsidian vault integration with Claude Code — 18 tools for notes, search, and graph traversal",
   "main": "index.js",
   "exports": {
@@ -54,7 +54,7 @@
     "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^12.6.2",
     "js-yaml": "^4.1.0",
-    "sqlite-vec": "0.1.7-alpha.2"
+    "sqlite-vec": "^0.1.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",