pkm-mcp-server 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -6,6 +6,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-03-21
+
+### Fixed
+- `pkm-mcp-server init` now correctly registers the MCP server with Claude Code via `claude mcp add` instead of writing to the wrong config file (`~/.claude/settings.json`). Previously, the server appeared to register successfully but was never visible to Claude Code.
+
+## [1.3.0] - 2026-03-19
+
+### Added
+- `pkm-mcp-server init` — interactive onboarding wizard that walks users through vault setup, template installation, folder structure, OpenAI API key configuration, and Claude Code registration in a single session
+- `cli.js` — new CLI dispatcher with `init` and `--version` subcommands; existing MCP server behavior unchanged when run without arguments
+- `templates/note.md` — minimal generic note template for users who prefer to define their own templates
+- 36 unit tests for init wizard helpers
+
+### Changed
+- `index.js` refactored to export `startServer()` for CLI dispatcher (backward compatible — `node index.js` still works)
+- Entry point updated from `index.js` to `cli.js` in package.json (`bin`, `main`, `exports`)
+
+### Dependencies
+- Added `@inquirer/prompts` for interactive CLI prompts
+
 ## [1.2.1] - 2026-03-17
 
 ### Added

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js >= 20](https://img.shields.io/badge/Node.js-%3E%3D20-green.svg)](https://nodejs.org/)
 [![CI](https://github.com/AdrianV101/Obsidian-MCP/actions/workflows/ci.yml/badge.svg)](https://github.com/AdrianV101/Obsidian-MCP/actions/workflows/ci.yml)
 
-An MCP (Model Context Protocol) server that gives Claude Code full read/write access to your Obsidian vault. 18 tools for note CRUD, full-text search, semantic search, graph traversal, metadata queries, and session activity tracking. Published on npm as [`pkm-mcp-server`](https://www.npmjs.com/package/pkm-mcp-server).
+An MCP (Model Context Protocol) server that gives Claude Code full read/write access to your Obsidian vault. 19 tools for note CRUD, full-text search, semantic search, graph traversal, metadata queries, session activity tracking, and passive knowledge capture. Published on npm as [`pkm-mcp-server`](https://www.npmjs.com/package/pkm-mcp-server).
 
 ## Why
 
@@ -42,6 +42,7 @@ https://github.com/user-attachments/assets/58ad9c9b-d987-4728-89e7-33de20b73a38
 | `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; validates enum fields by note type) |
+| `vault_capture` | Signal a PKM-worthy capture (decision, task, research, bug); returns immediately, background hook creates the note |
 
 ### Fuzzy Path Resolution
 
@@ -55,7 +56,7 @@ vault_read({ path: "devlog.md" })
 // Same result — .md extension is optional
 
 vault_links({ path: "alpha" })
-// Works on vault_links, vault_neighborhood, vault_suggest_links too
+// Works on vault_peek, vault_links, vault_neighborhood, vault_suggest_links too
 ```
 
 Folder-scoped tools accept partial folder names:
@@ -81,69 +82,59 @@ Ambiguous matches return an error listing candidates. Exact paths always work un
 
 ## Quick Start
 
-### 1. Install
+### 1. Install and Set Up
 
 **From npm** (recommended):
 
 ```bash
 npm install -g pkm-mcp-server
+pkm-mcp-server init
 ```
 
+The setup wizard walks you through:
+1. Vault path (existing or new)
+2. Note templates (full set, minimal, or skip)
+3. PARA folder structure
+4. OpenAI API key for semantic search (optional)
+5. Automatic registration with Claude Code
+
+Restart Claude Code after setup. The server provides all tools except semantic search out of the box.
+
 **From source:**
 
 ```bash
 git clone https://github.com/AdrianV101/Obsidian-MCP.git
 cd Obsidian-MCP
 npm install
+node cli.js init
 ```
 
-### 2. Register with Claude Code
-
-Add to `~/.claude/settings.json`:
+### 2. Manual Registration (alternative)
 
-**If installed from npm:**
+If you prefer to skip the wizard, register directly with the Claude CLI:
 
-```json
-{
-  "mcpServers": {
-    "obsidian-pkm": {
-      "command": "npx",
-      "args": ["-y", "pkm-mcp-server"],
-      "env": {
-        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
-      }
-    }
-  }
-}
+```bash
+claude mcp add -s user -e VAULT_PATH=/absolute/path/to/your/vault obsidian-pkm -- npx -y pkm-mcp-server
 ```
 
-**If installed from source:**
+For a source install:
 
-```json
-{
-  "mcpServers": {
-    "obsidian-pkm": {
-      "command": "node",
-      "args": ["/absolute/path/to/index.js"],
-      "env": {
-        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
-      }
-    }
-  }
-}
+```bash
+claude mcp add -s user -e VAULT_PATH=/absolute/path/to/your/vault obsidian-pkm -- node /absolute/path/to/cli.js
 ```
 
-Restart Claude Code. The server provides all tools except semantic search out of the box.
+Verify with `claude mcp list` — you should see `obsidian-pkm: ... - Connected`.
 
 ### 3. Enable Semantic Search (optional)
 
-Add your OpenAI API key to the env block:
+If you didn't set this up during `init`, add your OpenAI API key by re-registering:
 
-```json
-"env": {
-  "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
-  "OPENAI_API_KEY": "sk-..."
-}
+```bash
+claude mcp remove obsidian-pkm
+claude mcp add -s user \
+  -e VAULT_PATH=/absolute/path/to/your/vault \
+  -e OPENAI_API_KEY=sk-... \
+  obsidian-pkm -- npx -y pkm-mcp-server
 ```
 
 This enables `vault_semantic_search` and `vault_suggest_links`. Uses `text-embedding-3-large` with a SQLite + sqlite-vec index stored at `.obsidian/semantic-index.db`. The index rebuilds automatically — delete the DB file to force a full re-embed.
@@ -279,7 +270,9 @@ All paths passed to tools are relative to vault root. The server includes path s
 
 **Graph exploration** resolves `[[wikilinks]]` to file paths (handling aliases, headings, and ambiguous basenames), then does BFS traversal to return notes grouped by hop distance.
 
-**Activity logging** records every tool call with timestamps and session IDs, enabling Claude to recall what happened in previous conversations.
+**Activity logging** records every tool call (except `vault_activity` itself) with timestamps and session IDs, enabling Claude to recall what happened in previous conversations.
+
+**Passive capture** uses `vault_capture` to signal that something is worth persisting (a decision, task, research finding, or bug). The tool returns immediately — a PostToolUse hook spawns a background agent that creates the structured vault note. Combined with the Stop hook (which sweeps each session for un-captured decisions and tasks), this keeps the vault up to date without interrupting the coding flow.
 
 ## Troubleshooting
 
@@ -287,13 +280,16 @@ All paths passed to tools are relative to vault root. The server includes path s
 You need C++ build tools. See [Prerequisites](#prerequisites) for your platform. On Linux, `sudo apt install build-essential python3` usually fixes it.
 
 **Server starts but all tool calls fail with ENOENT**
-Your `VAULT_PATH` is wrong or missing. The server now validates this at startup and exits with a clear error. Set it explicitly in your `settings.json` env block.
+Your `VAULT_PATH` is wrong or missing. The server validates this at startup and exits with a clear error. Re-register with the correct path: `claude mcp remove obsidian-pkm && claude mcp add -s user -e VAULT_PATH=/correct/path obsidian-pkm -- npx -y pkm-mcp-server`
 
 **`vault_write` says "no templates available"**
-Copy the `templates/` files from this repo into your vault's `05-Templates/` directory. The server loads templates from there at startup.
+Run `pkm-mcp-server init` to install templates, or copy the `templates/` files from this repo into your vault's `05-Templates/` directory. The server loads templates from there at startup.
 
 **Semantic search not appearing in tool list**
-Set `OPENAI_API_KEY` in your `settings.json` env block. Without it, `vault_semantic_search` and `vault_suggest_links` are hidden entirely.
+Set `OPENAI_API_KEY` in your MCP server registration. See [Enable Semantic Search](#3-enable-semantic-search-optional). Without it, `vault_semantic_search` and `vault_suggest_links` are hidden entirely.
+
+**Server not showing up in Claude Code after install**
+Run `claude mcp list` to check. If `obsidian-pkm` is missing, register it with `claude mcp add` (see [Manual Registration](#2-manual-registration-alternative)). Note: editing `~/.claude/settings.json` directly does **not** register MCP servers — use the CLI.
 
 **Semantic index not updating after file changes**
 Check your Node version with `node -v`. The file watcher uses `fs.watch({ recursive: true })` which requires Node.js >= 18.13 on Linux.
@@ -302,6 +298,8 @@ Check your Node version with `node -v`. The file watcher uses `fs.watch({ recurs
 
 Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style guidelines, and the pull request process before submitting changes.
 
+See [CHANGELOG.md](CHANGELOG.md) for release history and [SECURITY.md](SECURITY.md) to report vulnerabilities.
+
 ## License
 
 MIT

package/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { createRequire } from "module";
+
+const subcommand = process.argv[2];
+
+try {
+  if (subcommand === "init") {
+    const { runInit } = await import("./init.js");
+    await runInit();
+  } else if (subcommand === "--version" || subcommand === "-v") {
+    const require = createRequire(import.meta.url);
+    const { version } = require("./package.json");
+    console.log(`pkm-mcp-server v${version}`);
+  } else if (!subcommand) {
+    const { startServer } = await import("./index.js");
+    await startServer();
+  } else {
+    console.error(`Unknown command: ${subcommand}`);
+    console.error("Usage: pkm-mcp-server [init]");
+    process.exit(1);
+  }
+} catch (e) {
+  console.error(`Fatal: ${e.message}`);
+  process.exit(1);
+}