obsidian-pkm-plugin: Instructions file for Claude Code

PKM: 01-Projects/Obsidian-MCP

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Claude Code plugin that provides an MCP server and supporting tools for bidirectional knowledge flow between Claude Code and an Obsidian vault. It packages 20 MCP tools, Claude Code hooks, and a setup skill under the vault-pkm plugin identity.

Commands

# Install dependencies
npm install

# Run the MCP server (for testing)
VAULT_PATH="/path/to/your/vault" node cli.js

# Vault scaffolding wizard (templates, PARA folders)
node cli.js init

# Start the server
npm start

# Run unit tests
npm test

# Run linter
npm run lint

Architecture

The project consists of three parts:

MCP Server: A Node.js ES module server implementing the Model Context Protocol. The main entry point is index.js (tool definitions and request routing), with pure helper functions extracted to helpers.js. It provides 20 tools for vault interaction:

• vault_read - Read note contents (supports pagination: heading, tail, tail_sections [with optional section_level param, default: 2], chunk, lines; auto-redirects to peek data for files >80k chars; force bypasses redirect)
• vault_peek - Inspect file metadata/structure without reading full content (size, frontmatter, indented heading tree, preview)
• vault_write - Create new notes from templates (enforces frontmatter; settable fields: status, priority, project, deciders, due, source; variables param for custom <%...%> substitution in template body)
• vault_append - Add content to existing files, with optional positional insert (after/before heading, end of section)
• vault_edit - Surgical string replacement (exact match, single occurrence)
• vault_update_frontmatter - Update YAML frontmatter fields atomically (set, create, remove fields)
• vault_search - Full-text search across markdown files
• vault_semantic_search - Semantic similarity search using OpenAI embeddings (requires VAULT_PKM_OPENAI_KEY or OPENAI_API_KEY)
• vault_suggest_links - Suggest relevant notes to link based on content similarity; graph_context: true for graph-semantic blending (requires VAULT_PKM_OPENAI_KEY or OPENAI_API_KEY)
• vault_list / vault_recent - Directory listing and recent files
• vault_links - Wikilink analysis ([[...]] syntax)
• vault_neighborhood - Graph context exploration via BFS wikilink traversal
• vault_query - Query notes by YAML frontmatter (type, status, tags [ALL must match], tags_any [ANY must match], dates, custom_fields for arbitrary field matching, sort_by/sort_order for result ordering)
• vault_tags - Discover all tags with per-note counts; supports folder scoping, glob patterns, inline #tag parsing
• vault_activity - Query/clear activity log (all tool calls with timestamps and session IDs)
• vault_trash - Soft-delete to .trash/ (Obsidian convention), warns about broken incoming links
• vault_move - Move/rename files with automatic wikilink updating across vault (update_links: false to skip)
• vault_add_links - Add annotated wikilinks to a note's section with deduplication (default: ## Related)
• vault_link_health - Graph health report: orphans, broken links, weakly connected notes, ambiguous links