pkm-mcp-server 1.0.0

package/sample-project/CLAUDE.md

@@ -0,0 +1,193 @@
+# Project: [Your Project Name]
+
+> Place this file in your code repository root. It configures Claude Code to integrate with your Obsidian PKM system via the `obsidian-pkm` MCP server.
+
+## PKM Integration
+
+- **Vault project path**: `01-Projects/[YourProjectName]/`
+- **MCP Server**: `obsidian-pkm` (configured in `~/.claude/settings.json`)
+
+### Session Start: Load Context
+
+Before starting work, load project context:
+
+```
+vault_read("01-Projects/[YourProjectName]/_index.md")
+vault_recent({ folder: "01-Projects/[YourProjectName]", limit: 5 })
+vault_activity({ path: "01-Projects/[YourProjectName]", limit: 10 })
+```
+
+Use `vault_activity` to recall what was done in previous sessions (files read, written, searched). This gives continuity across conversations.
+
+### Before Creating or Researching
+
+Always search before creating new notes to avoid duplication:
+
+```
+vault_search({ query: "your topic" })
+vault_semantic_search({ query: "your concept", folder: "01-Projects/[YourProjectName]" })
+vault_query({ tags: ["relevant-tag"], folder: "01-Projects/[YourProjectName]" })
+```
+
+`vault_semantic_search` finds conceptually related notes even when different words are used (e.g., searching "managing overwhelm" finds notes about "cognitive load"). Use it for discovery alongside exact-text `vault_search`.
+
+## Documentation Rules
+
+### Metadata
+
+All notes MUST include YAML frontmatter. See `06-System/metadata-schema.md` for the full schema.
+
+```yaml
+---
+type: <type>        # Required
+created: YYYY-MM-DD # Required (auto-filled by vault_write)
+tags: [...]         # Required: at least one tag
+status: <status>    # If applicable
+---
+```
+
+**Never create notes without frontmatter** — use `vault_write` with a template.
+
+### Architecture Decisions
+
+When a significant technical decision is made:
+
+1. Create an ADR using `vault_write` with the `adr` template:
+   ```
+   vault_write({
+     template: "adr",
+     path: "01-Projects/[YourProjectName]/development/decisions/ADR-{NNN}-{kebab-title}.md",
+     frontmatter: { tags: ["decision", "relevant-topic"], deciders: "Team" }
+   })
+   ```
+2. Fill in Context, Decision, Options Considered, and Consequences sections
+3. Update `_index.md` to link the new ADR:
+   ```
+   vault_append({
+     path: "01-Projects/[YourProjectName]/_index.md",
+     heading: "## Architecture Decisions",
+     position: "end_of_section",
+     content: "- [[ADR-{NNN}-{kebab-title}]]"
+   })
+   ```
+
+### Development Progress
+
+After implementing features or making significant progress, append to the devlog:
+
+```
+vault_append({
+  path: "01-Projects/[YourProjectName]/development/devlog.md",
+  heading: "## Recent Activity",
+  position: "after_heading",
+  content: "## YYYY-MM-DD\n\n### Session Summary\n- What was done\n\n### Key Decisions\n- Decisions made (link to ADRs)\n\n### Next Steps\n- What's next\n\n---\n"
+})
+```
+
+Use `position: "after_heading"` to prepend new entries (most recent first) or `position: "end_of_section"` to append.
+
+### Reusable Knowledge
+
+When solving a problem that has general applicability:
+
+1. Search for existing related notes first:
+   ```
+   vault_semantic_search({ query: "the concept you learned" })
+   ```
+2. Create a permanent note if nothing exists:
+   ```
+   vault_write({
+     template: "permanent-note",
+     path: "03-Resources/Development/{topic-name}.md",
+     frontmatter: { tags: ["relevant-tags"] }
+   })
+   ```
+3. Find and add bidirectional links:
+   ```
+   vault_suggest_links({ path: "03-Resources/Development/{topic-name}.md" })
+   ```
+
+`vault_suggest_links` uses semantic similarity to find notes worth linking to, and excludes notes already linked via `[[wikilinks]]`.
+
+### Troubleshooting
+
+When debugging a complex issue, create a troubleshooting log:
+
+```
+vault_write({
+  template: "troubleshooting-log",
+  path: "01-Projects/[YourProjectName]/development/debug/{issue-name}.md",
+  frontmatter: { tags: ["debugging", "relevant-topic"] }
+})
+```
+
+Fill in: Problem, Symptoms, Root Cause, Solution, Prevention.
+
+## Context Queries
+
+### Find Related Notes
+
+```
+vault_search({ query: "keywords", folder: "01-Projects/[YourProjectName]" })
+vault_semantic_search({ query: "concept description" })
+vault_query({ type: "adr", folder: "01-Projects/[YourProjectName]" })
+vault_tags({ folder: "01-Projects/[YourProjectName]" })
+```
+
+### Explore Connections
+
+```
+vault_neighborhood({ path: "01-Projects/[YourProjectName]/_index.md", depth: 2 })
+vault_links({ path: "path/to/note.md", direction: "both" })
+```
+
+`vault_neighborhood` traverses wikilinks via BFS and returns notes grouped by hop distance — useful for understanding how notes relate to each other.
+
+### Cross-Session Memory
+
+```
+vault_activity({ path: "01-Projects/[YourProjectName]" })
+vault_activity({ tool: "vault_write", since: "2026-01-01" })
+```
+
+Check what was done in previous sessions to maintain continuity.
+
+## Available Templates
+
+Use these with `vault_write({ template: "name", path: "...", frontmatter: { tags: [...] } })`:
+
+| Template | Use For |
+|---|---|
+| `project-index` | Project overview (`_index.md`) |
+| `adr` | Architecture Decision Records |
+| `devlog` | Development logs |
+| `permanent-note` | Atomic evergreen knowledge notes |
+| `research-note` | Research findings and analysis |
+| `troubleshooting-log` | Bug investigations and fixes |
+| `fleeting-note` | Quick captures and temporary thoughts |
+| `literature-note` | Notes on articles, books, talks |
+| `meeting-notes` | Meeting records |
+| `moc` | Maps of Content (index/hub notes) |
+| `daily-note` | Daily notes |
+| `task` | Structured task notes with status, priority, due date |
+
+## Session End
+
+Before ending a development session:
+
+1. Append a summary to the devlog
+2. Update project status in `_index.md` if changed
+3. Note any created files for future reference
+
+## Project-Specific Notes
+
+<!-- Customize the sections below for your project -->
+
+### Tech Stack
+-
+
+### Key Patterns
+-
+
+### Important Constraints
+-

package/templates/adr.md

@@ -0,0 +1,52 @@
+---
+type: adr
+status: proposed
+created: <% tp.date.now("YYYY-MM-DD") %>
+deciders: 
+tags:
+  - decision
+  - architecture
+---
+
+# ADR-XXX: <% tp.file.title %>
+
+## Context
+<!-- What is the issue that we're seeing that motivates this decision? -->
+
+
+## Decision
+<!-- What is the change that we're proposing and/or doing? -->
+
+
+## Options Considered
+
+### Option 1: 
+**Pros:**
+- 
+
+**Cons:**
+- 
+
+### Option 2: 
+**Pros:**
+- 
+
+**Cons:**
+- 
+
+## Consequences
+<!-- What becomes easier or more difficult because of this change? -->
+
+### Positive
+- 
+
+### Negative
+- 
+
+### Risks
+- 
+
+## Related
+<!-- Links to related notes, prior decisions, or research -->
+- 
+

package/templates/daily-note.md

@@ -0,0 +1,19 @@
+---
+type: daily
+created: <% tp.date.now("YYYY-MM-DD") %>
+tags:
+  - daily
+---
+
+# <% tp.file.title %>
+
+## Tasks
+- [ ]
+
+## Notes
+<!-- Thoughts, observations, quick captures -->
+
+
+## Log
+<!-- What happened today -->
+

package/templates/devlog.md

@@ -0,0 +1,35 @@
+---
+type: devlog
+project: 
+created: <% tp.date.now("YYYY-MM-DD") %>
+tags:
+  - devlog
+---
+
+# Development Log
+
+This log tracks development progress, decisions made, and lessons learned.
+
+---
+
+## <% tp.date.now("YYYY-MM-DD") %>
+
+### Session Summary
+<!-- What was accomplished in this session? -->
+
+
+### Key Decisions
+<!-- Any decisions made (link to ADRs if created) -->
+
+
+### Blockers / Issues
+<!-- What problems were encountered? -->
+
+
+### Next Steps
+<!-- What should be done in the next session? -->
+
+
+---
+
+<!-- New entries are added above this line -->

package/templates/fleeting-note.md

@@ -0,0 +1,11 @@
+---
+type: fleeting
+created: <% tp.date.now("YYYY-MM-DD") %>
+tags:
+  - inbox
+---
+
+# <% tp.file.title %>
+
+<!-- Quick capture. Process later: refine into a permanent note, or archive. -->
+

package/templates/literature-note.md

@@ -0,0 +1,25 @@
+---
+type: literature
+created: <% tp.date.now("YYYY-MM-DD") %>
+source:
+tags:
+  - literature
+---
+
+# <% tp.file.title %>
+
+## Summary
+<!-- Key points from the source material -->
+
+
+## Notes
+<!-- Your own thoughts and reactions -->
+
+
+## Quotes
+<!-- Notable passages (with page/section references) -->
+-
+
+## Related
+<!-- Links to related notes or concepts -->
+-

package/templates/meeting-notes.md

@@ -0,0 +1,28 @@
+---
+type: meeting
+created: <% tp.date.now("YYYY-MM-DD") %>
+attendees:
+tags:
+  - meeting
+---
+
+# Meeting: <% tp.file.title %>
+
+## Agenda
+-
+
+## Discussion
+<!-- Key points discussed -->
+
+
+## Decisions
+<!-- What was decided -->
+-
+
+## Action Items
+<!-- Who does what by when -->
+- [ ]
+
+## Related
+<!-- Links to relevant notes, projects, or prior meetings -->
+-

package/templates/moc.md

@@ -0,0 +1,22 @@
+---
+type: moc
+created: <% tp.date.now("YYYY-MM-DD") %>
+tags:
+  - moc
+---
+
+# <% tp.file.title %>
+
+<!-- Map of Content: an index/hub that organizes notes around a topic. -->
+
+## Overview
+<!-- Brief description of what this MOC covers -->
+
+
+## Core Notes
+<!-- Primary notes on this topic -->
+-
+
+## Related Topics
+<!-- Links to other MOCs or areas -->
+-

package/templates/permanent-note.md

@@ -0,0 +1,26 @@
+---
+type: permanent
+created: <% tp.date.now("YYYY-MM-DD") %>
+tags: [permanent]
+---
+
+# <% tp.file.title %>
+
+<!-- 
+This is a permanent/evergreen note. Guidelines:
+- One idea per note (atomic)
+- Written in your own words
+- Should make sense on its own
+- Link liberally to related notes
+-->
+
+
+
+## Related
+<!-- Links to related concepts, source materials, projects where this was learned -->
+- 
+
+## References
+<!-- If this came from a specific source -->
+- 
+

package/templates/project-index.md

@@ -0,0 +1,38 @@
+---
+type: project-index
+status: active
+created: <% tp.date.now("YYYY-MM-DD") %>
+updated: <% tp.date.now("YYYY-MM-DD") %>
+tags:
+  - project
+---
+
+# <% tp.file.title %>
+
+## Overview
+<!-- Brief description of what this project is and why it exists -->
+
+
+## Objectives
+<!-- What does success look like? What are we trying to achieve? -->
+- [ ] 
+
+
+## Key Links
+<!-- Important documents, external resources, related projects -->
+- **Repository**: 
+- **Requirements**: [[<% tp.file.title %>/planning/requirements|Requirements]]
+- **Roadmap**: [[<% tp.file.title %>/planning/roadmap|Roadmap]]
+- **Dev Log**: [[<% tp.file.title %>/development/devlog|Development Log]]
+
+## Architecture Decisions
+<!-- Links to ADRs as they're created -->
+
+
+## Current Status
+<!-- What's the current state? What's being worked on? -->
+
+
+## Recent Activity
+<!-- Auto-updated by Claude Code during sessions -->
+

package/templates/research-note.md

@@ -0,0 +1,35 @@
+---
+type: research
+created: <% tp.date.now("YYYY-MM-DD") %>
+status: active
+tags:
+  - research
+---
+
+# <% tp.file.title %>
+
+## What It Is
+<!-- Brief description of the topic or technology -->
+
+
+## Why Consider It
+<!-- What problem does it solve? Why is it relevant? -->
+
+
+## Pros
+-
+
+## Cons
+-
+
+## Key Findings
+<!-- Important details, benchmarks, or observations -->
+
+
+## Links
+<!-- External references: docs, articles, repos -->
+-
+
+## Verdict
+<!-- Summary assessment and recommendation -->
+

package/templates/task.md

@@ -0,0 +1,22 @@
+---
+type: task
+created: <% tp.date.now("YYYY-MM-DD") %>
+status: pending
+priority: normal
+due: null
+project: null
+source: null
+tags:
+  - task
+---
+
+# <% tp.file.title %>
+
+## Description
+
+
+## Context
+
+
+## Acceptance Criteria
+

package/templates/troubleshooting-log.md

@@ -0,0 +1,32 @@
+---
+type: bug
+created: <% tp.date.now("YYYY-MM-DD") %>
+status: investigating
+tags:
+  - debugging
+---
+
+# <% tp.file.title %>
+
+## Problem
+<!-- What went wrong? -->
+
+
+## Symptoms
+<!-- Observable behavior, error messages, logs -->
+
+
+## Root Cause
+<!-- What actually caused the issue -->
+
+
+## Solution
+<!-- How it was fixed -->
+
+
+## Prevention
+<!-- How to avoid this in the future -->
+
+## Related
+<!-- Links to related notes, ADRs, or issues -->
+-

package/utils.js

@@ -0,0 +1,31 @@
+import fs from "fs/promises";
+import path from "path";
+import yaml from "js-yaml";
+
+/** Extract YAML frontmatter from markdown content. */
+export function extractFrontmatter(content) {
+  if (!content.startsWith("---")) return null;
+  const endIndex = content.indexOf("\n---", 3);
+  if (endIndex === -1) return null;
+  const yamlContent = content.slice(4, endIndex);
+  try {
+    return yaml.load(yamlContent, { schema: yaml.JSON_SCHEMA });
+  } catch {
+    return null;
+  }
+}
+
+/** Recursively get all markdown files in a directory (skips dotfiles/dirs). */
+export async function getAllMarkdownFiles(dir, baseDir = dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith(".")) {
+      files.push(...await getAllMarkdownFiles(fullPath, baseDir));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      files.push(path.relative(baseDir, fullPath));
+    }
+  }
+  return files;
+}