pkm-mcp-server 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-02-11
+
+### Added
+- MCP server with 18 tools for Obsidian vault interaction
+- `vault_read` with pagination support (heading-based, tail lines, tail sections, chunk, line range); auto-redirects large files (>80k chars) to peek data; `force` param to bypass redirect (hard-capped at ~400k chars)
+- `vault_peek` for inspecting file metadata and structure without reading full content (size, frontmatter, heading outline with line numbers, preview)
+- `vault_write` with template-based note creation enforcing YAML frontmatter
+- `vault_append` with positional insert (after heading, before heading, end of section)
+- `vault_edit` for surgical single-occurrence string replacement
+- `vault_update_frontmatter` — safe, atomic YAML frontmatter field updates (set, create, delete fields with protected required fields)
+- `vault_search` for full-text search across markdown files
+- `vault_semantic_search` using OpenAI `text-embedding-3-large` embeddings with SQLite-vec storage
+- `vault_suggest_links` for smart link discovery based on content similarity
+- `vault_list` and `vault_recent` for directory listing and recently modified files
+- `vault_links` for wikilink analysis (`[[...]]` syntax)
+- `vault_neighborhood` for graph context exploration via BFS wikilink traversal
+- `vault_query` for querying notes by YAML frontmatter metadata (type, status, tags, dates, custom fields, sorting)
+- `vault_tags` for tag discovery with per-note counts, folder scoping, and glob patterns
+- `vault_activity` for cross-session memory via activity logging with session IDs
+- `vault_trash` — soft-delete to `.trash/` (Obsidian convention) with broken incoming link warnings
+- `vault_move` — move/rename files with automatic wikilink updating across vault
+- Fuzzy path resolution for read-only tools (resolve by basename, `.md` extension optional)
+- Fuzzy folder resolution for search/query/tags/recent tools (partial name matching)
+- 12 Obsidian note templates (project index, ADR, devlog, permanent note, research note, troubleshooting log, fleeting note, literature note, meeting notes, map of content, daily note, task)
+- Sample `CLAUDE.md` for integrating PKM workflows into code repositories
+- Background `fs.watch` indexer for keeping semantic search index fresh
+- Metadata schema documentation (`06-System/metadata-schema.md`)
+- GitHub Actions CI workflow
+- Comprehensive test suite (417 tests) for helpers, handlers, graph module, and activity log
+- ESLint configuration for code quality
+- EditorConfig for consistent formatting
+- Community files: CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE (MIT)
+
+### Security
+- Path traversal prevention on all vault operations
+- Write tools require exact paths to prevent accidental modifications
+- Ambiguous fuzzy path matches return errors instead of guessing
+- Prototype pollution protection on frontmatter key validation (`__proto__`, `constructor`, `prototype` blocked)
+- ReDoS vulnerability prevention in `vault_list` glob pattern — linear-time glob matching
+- 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.0.0...HEAD
+[1.0.0]: https://github.com/AdrianV101/Obsidian-MCP/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Verhoosel Azpiroz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,246 @@
+# Obsidian PKM MCP Server
+
+[![npm version](https://img.shields.io/npm/v/pkm-mcp-server)](https://www.npmjs.com/package/pkm-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![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).
+
+## Why
+
+Claude Code is powerful for writing code, but it forgets everything between sessions. This server turns your Obsidian vault into persistent, structured memory that Claude can read and write natively.
+
+- **Session continuity** - Claude logs what it did and can pick up where it left off
+- **Structured knowledge** - ADRs, research notes, devlogs created from enforced templates, not freeform text dumps
+- **Semantic recall** - "find my notes about caching strategies" works even if you never used the word "caching"
+- **Graph context** - Claude can explore related notes by following wikilinks, not just keyword matches
+
+Without this, every Claude Code session starts from scratch. With it, your AI assistant has a working memory that compounds over time.
+
+https://github.com/user-attachments/assets/58ad9c9b-d987-4728-89e7-33de20b73a38
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `vault_read` | Read note contents (pagination by heading, tail, chunk, line range; auto-redirects large files to peek data) |
+| `vault_peek` | Inspect file metadata and structure without reading full content |
+| `vault_write` | Create notes from templates (enforces frontmatter) |
+| `vault_append` | Append to notes, with positional insert (after/before heading, end of section) |
+| `vault_edit` | Surgical string replacement |
+| `vault_search` | Full-text search across markdown files |
+| `vault_semantic_search` | Semantic similarity search via OpenAI embeddings |
+| `vault_suggest_links` | Suggest relevant notes to link based on content similarity |
+| `vault_list` | List files and folders |
+| `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_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) |
+
+### Fuzzy Path Resolution
+
+Read-only tools accept short names that resolve to full vault paths:
+
+```javascript
+vault_read({ path: "devlog" })
+// Resolves to: 01-Projects/Obsidian-MCP/development/devlog.md
+
+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
+```
+
+Folder-scoped tools accept partial folder names:
+
+```javascript
+vault_search({ query: "API design", folder: "Obsidian-MCP" })
+// Resolves folder to: 01-Projects/Obsidian-MCP
+
+vault_tags({ folder: "Obsidian-MCP" })
+// Works on vault_search, vault_query, vault_tags, vault_recent
+```
+
+Ambiguous matches return an error listing candidates. Exact paths always work unchanged.
+
+## Prerequisites
+
+- **Node.js >= 20** (Node 18 is EOL; uses native `fetch` and ES modules)
+- **An MCP-compatible client** such as [Claude Code](https://claude.ai/code)
+- **C++ build tools** for `better-sqlite3` native addon:
+  - **macOS**: `xcode-select --install`
+  - **Linux**: `sudo apt install build-essential python3` (Debian/Ubuntu) or equivalent
+  - **Windows**: Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) with the "Desktop development with C++" workload
+
+## Quick Start
+
+### 1. Install
+
+**From npm** (recommended):
+
+```bash
+npm install -g pkm-mcp-server
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/AdrianV101/Obsidian-MCP.git
+cd Obsidian-MCP
+npm install
+```
+
+### 2. Register with Claude Code
+
+Add to `~/.claude/settings.json`:
+
+**If installed from npm:**
+
+```json
+{
+  "mcpServers": {
+    "obsidian-pkm": {
+      "command": "npx",
+      "args": ["-y", "pkm-mcp-server"],
+      "env": {
+        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
+      }
+    }
+  }
+}
+```
+
+**If installed from source:**
+
+```json
+{
+  "mcpServers": {
+    "obsidian-pkm": {
+      "command": "node",
+      "args": ["/absolute/path/to/index.js"],
+      "env": {
+        "VAULT_PATH": "/absolute/path/to/your/obsidian/vault"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Code. The server provides all tools except semantic search out of the box.
+
+### 3. Enable Semantic Search (optional)
+
+Add your OpenAI API key to the env block:
+
+```json
+"env": {
+  "VAULT_PATH": "/absolute/path/to/your/obsidian/vault",
+  "OPENAI_API_KEY": "sk-..."
+}
+```
+
+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.
+
+## Vault Structure
+
+The server works with any Obsidian vault. The included templates assume this layout:
+
+```
+Vault/
+├── 00-Inbox/
+├── 01-Projects/
+│   └── ProjectName/
+│       ├── _index.md
+│       ├── planning/
+│       ├── research/
+│       └── development/decisions/
+├── 02-Areas/
+├── 03-Resources/
+├── 04-Archive/
+├── 05-Templates/          # Note templates loaded by vault_write
+└── 06-System/
+```
+
+### Templates
+
+Copy the files from `templates/` into your vault's `05-Templates/` folder. `vault_write` loads all `.md` files from that directory at startup and enforces frontmatter on every note created.
+
+Included templates: `project-index`, `adr`, `devlog`, `permanent-note`, `research-note`, `troubleshooting-log`, `fleeting-note`, `literature-note`, `meeting-notes`, `moc`, `daily-note`, `task`. Add your own templates to `05-Templates/` and they become available to `vault_write` automatically.
+
+### CLAUDE.md for Your Projects
+
+`sample-project/CLAUDE.md` is a template you can drop into any code repository to wire up Claude Code with your vault. It defines context loading, documentation rules, and ADR/devlog conventions.
+
+## Architecture
+
+```mermaid
+graph LR
+    CC[Claude Code] -->|MCP protocol| IDX[index.js]
+    IDX --> HND[handlers.js]
+    HND --> H[helpers.js]
+    HND --> G[graph.js]
+    HND --> E[embeddings.js]
+    HND --> A[activity.js]
+    HND --> U[utils.js]
+    HND -->|read/write| V[(Obsidian Vault)]
+    E -->|embeddings API| OAI[OpenAI]
+    E -->|vector store| DB[(SQLite + sqlite-vec)]
+    A -->|activity log| DB2[(SQLite)]
+```
+
+```
+├── index.js          # MCP server, tool definitions, request routing
+├── handlers.js       # Tool handler implementations
+├── helpers.js        # Pure functions (path security, filtering, templates)
+├── graph.js          # Wikilink resolution and BFS graph traversal
+├── embeddings.js     # Semantic index (OpenAI embeddings, SQLite + sqlite-vec)
+├── activity.js       # Activity log (session tracking, SQLite)
+├── utils.js          # Shared utilities (frontmatter parsing, file listing)
+├── templates/        # Obsidian note templates
+└── sample-project/   # Sample CLAUDE.md for your repos
+```
+
+All paths passed to tools are relative to vault root. The server includes path security to prevent directory traversal.
+
+## 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`).
+
+**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).
+
+**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.
+
+## Troubleshooting
+
+**`better-sqlite3` build fails during install**
+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.
+
+**`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.
+
+**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.
+
+**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.
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style guidelines, and the pull request process before submitting changes.
+
+## License
+
+MIT
+

package/activity.js

@@ -0,0 +1,147 @@
+import Database from "better-sqlite3";
+import fs from "fs/promises";
+import path from "path";
+
+/**
+ * Persistent activity log backed by SQLite.
+ * Records every MCP tool call with timestamps and session IDs,
+ * enabling cross-session memory for Claude conversations.
+ */
+export class ActivityLog {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.vaultPath - absolute path to vault root
+   * @param {string} opts.sessionId - UUID for the current session
+   */
+  constructor({ vaultPath, sessionId }) {
+    this.vaultPath = vaultPath;
+    this.sessionId = sessionId;
+    this.dbPath = path.join(vaultPath, ".obsidian", "activity-log.db");
+    this.db = null;
+  }
+
+  /** Create the SQLite database and activity table if they don't exist. */
+  async initialize() {
+    const dbDir = path.dirname(this.dbPath);
+    await fs.mkdir(dbDir, { recursive: true });
+
+    this.db = new Database(this.dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("journal_size_limit = 32000000");
+
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS activity (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        timestamp TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        args_json TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_activity_session ON activity(session_id);
+      CREATE INDEX IF NOT EXISTS idx_activity_tool ON activity(tool_name);
+      CREATE INDEX IF NOT EXISTS idx_activity_timestamp ON activity(timestamp);
+    `);
+  }
+
+  /**
+   * Record a tool invocation.
+   * @param {string} toolName - MCP tool name
+   * @param {Object} [args] - tool arguments
+   */
+  log(toolName, args) {
+    if (!this.db) return;
+
+    this.db.prepare(
+      "INSERT INTO activity (timestamp, session_id, tool_name, args_json) VALUES (?, ?, ?, ?)"
+    ).run(
+      new Date().toISOString(),
+      this.sessionId,
+      toolName,
+      JSON.stringify(args || {})
+    );
+  }
+
+  /**
+   * Query activity entries with optional filters.
+   * @param {Object} [opts]
+   * @param {number} [opts.limit=50]
+   * @param {string} [opts.tool] - filter by tool name
+   * @param {string} [opts.session] - filter by session ID
+   * @param {string} [opts.since] - ISO timestamp lower bound
+   * @param {string} [opts.before] - ISO timestamp upper bound
+   * @param {string} [opts.path] - substring match on args JSON
+   * @returns {Object[]} matching activity rows
+   */
+  query({ limit = 50, tool, session, since, before, path: pathFilter } = {}) {
+    if (!this.db) return [];
+
+    let sql = "SELECT * FROM activity WHERE 1=1";
+    const params = [];
+
+    if (tool) {
+      sql += " AND tool_name = ?";
+      params.push(tool);
+    }
+    if (session) {
+      sql += " AND session_id = ?";
+      params.push(session);
+    }
+    if (since) {
+      sql += " AND timestamp >= ?";
+      params.push(since);
+    }
+    if (before) {
+      sql += " AND timestamp <= ?";
+      params.push(before);
+    }
+    if (pathFilter) {
+      sql += " AND args_json LIKE ? ESCAPE '\\'";
+      const escaped = pathFilter.replace(/[%_\\]/g, "\\$&");
+      params.push(`%${escaped}%`);
+    }
+
+    sql += " ORDER BY timestamp DESC LIMIT ?";
+    params.push(limit);
+
+    return this.db.prepare(sql).all(...params);
+  }
+
+  /**
+   * Delete activity entries, optionally filtered.
+   * @param {Object} [opts]
+   * @param {string} [opts.session] - delete only this session
+   * @param {string} [opts.tool] - delete only this tool
+   * @param {string} [opts.before] - delete entries before this timestamp
+   * @returns {number} number of deleted rows
+   */
+  clear({ session, tool, before } = {}) {
+    if (!this.db) return 0;
+
+    let sql = "DELETE FROM activity WHERE 1=1";
+    const params = [];
+
+    if (session) {
+      sql += " AND session_id = ?";
+      params.push(session);
+    }
+    if (tool) {
+      sql += " AND tool_name = ?";
+      params.push(tool);
+    }
+    if (before) {
+      sql += " AND timestamp < ?";
+      params.push(before);
+    }
+
+    const result = this.db.prepare(sql).run(...params);
+    return result.changes;
+  }
+
+  /** Close the database connection. */
+  shutdown() {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+}