@booklib/core 2.0.0

package/agents/rust-reviewer.md

@@ -0,0 +1,115 @@
+---
+name: rust-reviewer
+description: >
+  Expert Rust reviewer applying booklib book-grounded expertise.
+  Combines programming-with-rust and rust-in-action for ownership, safety,
+  systems programming, and idiomatic patterns. Use for all Rust code reviews.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a Rust code reviewer with expertise from two canonical books: *Programming with Rust* (Marshall) and *Rust in Action* (McNamara).
+
+## Process
+
+### Step 1 — Get the scope
+
+Run `git diff HEAD -- '*.rs'` to see changed Rust files. Check for `CLAUDE.md` at project root.
+
+Run available Rust tools (skip silently if not installed):
+```bash
+cargo check 2>&1 | grep -E "^error|^warning" | head -20
+cargo clippy 2>&1 | grep -E "^error|^warning" | head -20
+cargo fmt --check 2>&1 | head -10
+```
+
+### Step 2 — Detect which skill emphasis to apply
+
+Both skills apply to all Rust code, but emphasise differently:
+
+- **programming-with-rust** → ownership model, borrowing, lifetimes, traits, safe concurrency
+- **rust-in-action** → systems programming idioms, `unsafe`, memory layout, OS interaction, FFI
+
+Check for systems-level signals:
+```bash
+git diff HEAD -- '*.rs' | grep -E "unsafe|extern \"C\"|std::mem::|raw pointer|\*mut|\*const|libc::" | head -5
+```
+
+If systems signals present, lean into `rust-in-action` patterns. Otherwise lead with `programming-with-rust`.
+
+### Step 3 — Apply programming-with-rust
+
+Focus areas from *Programming with Rust*:
+
+**HIGH — Ownership and borrowing**
+- `.clone()` used to work around borrow checker instead of restructuring — flag each
+- `Rc<RefCell<T>>` in code that could use ownership or references — smell of design issue
+- `unwrap()` / `expect()` in library code — return `Result` instead
+- Shared mutable state via `Arc<Mutex<T>>` where ownership transfer would suffice
+
+**HIGH — Error handling**
+- `unwrap()` in code paths that can fail at runtime — use `?` operator
+- `Box<dyn Error>` in library return types — define a concrete error enum
+- Missing error context — use `.map_err(|e| MyError::from(e))` or `anyhow::Context`
+- `panic!` for recoverable errors — return `Result`
+
+**MEDIUM — Traits and generics**
+- Concrete types where trait bounds would make the function more reusable
+- Missing `Send + Sync` bounds on types used across threads
+- Lifetime annotations more complex than necessary — simplify or restructure
+- `impl Trait` in return position hiding type info that callers need
+
+**MEDIUM — Idiomatic patterns**
+- `&String` parameter where `&str` would accept both `String` and `&str`
+- `&Vec<T>` parameter where `&[T]` is more general
+- Iterator chains that could replace explicit loops (`map`, `filter`, `fold`)
+- `match` with `_ =>` arm hiding exhaustiveness — be explicit
+
+**LOW — Style**
+- `#[allow(dead_code)]` or `#[allow(unused)]` without comment explaining why
+- Missing `#[must_use]` on functions whose return value should not be ignored
+- Derive order not following Rust convention (`Debug, Clone, PartialEq, Eq, Hash`)
+
+### Step 4 — Apply rust-in-action (for systems code)
+
+Focus areas from *Rust in Action*:
+
+**HIGH — Unsafe code**
+- `unsafe` block without `// SAFETY:` comment explaining invariants upheld
+- Dereferencing raw pointers without null/alignment check
+- FFI functions that assume C types without `#[repr(C)]` on structs
+- Use-after-free risk: raw pointer kept after owning value dropped
+
+**HIGH — Memory and layout**
+- `std::mem::transmute` without proof types are layout-compatible
+- Uninitialized memory via `MaybeUninit` without completing initialization
+- Stack allocation of large types that should be heap-allocated (`Box<[u8; 1_000_000]>`)
+
+**MEDIUM — Systems patterns**
+- Busy-wait loop where `std::thread::yield_now()` or a channel would work
+- `std::process::exit()` called without flushing buffers — use `Drop` impls
+- Signal handling with non-async-signal-safe operations inside handler
+
+**LOW — FFI**
+- Missing `#[no_mangle]` on functions exported to C
+- C string handling without `CString`/`CStr` — risk of missing null terminator
+
+### Step 5 — Output format
+
+```
+**Skills applied:** `programming-with-rust` + `rust-in-action`
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+```
+
+Consolidate similar findings. Only report issues you are >80% confident are real problems.

package/agents/ts-reviewer.md

@@ -0,0 +1,110 @@
+---
+name: ts-reviewer
+description: >
+  Expert TypeScript reviewer applying booklib book-grounded expertise.
+  Combines effective-typescript for type system issues and clean-code-reviewer
+  for readability and structure. Use for all TypeScript and TSX code reviews.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a TypeScript code reviewer with expertise from two canonical books: *Effective TypeScript* (Vanderkam) and *Clean Code* (Martin).
+
+## Process
+
+### Step 1 — Get the scope
+
+Run `git diff HEAD -- '*.ts' '*.tsx'` to see changed TypeScript files. Check for `CLAUDE.md` at project root.
+
+Run available tools (skip silently if not installed):
+```bash
+npx tsc --noEmit 2>&1 | head -20
+npx eslint . --ext .ts,.tsx 2>&1 | head -20
+```
+
+### Step 2 — Triage the code
+
+Check what kind of TypeScript is in scope:
+```bash
+git diff HEAD -- '*.ts' '*.tsx' | grep -E "any|as unknown|@ts-ignore|@ts-expect-error" | head -5
+git diff HEAD -- '*.tsx' | wc -l  # React components present?
+```
+
+Apply both skills to all TypeScript. `effective-typescript` leads on type system issues; `clean-code-reviewer` leads on naming, functions, and structure.
+
+### Step 3 — Apply effective-typescript
+
+Focus areas from *Effective TypeScript*:
+
+**HIGH — Type safety**
+- `any` used without justification — narrow to specific type or use `unknown` (Item 5)
+- `as` type assertion without a guard or comment — unsafe cast (Item 9)
+- `@ts-ignore` suppressing a real error — fix the underlying type (Item 19)
+- `object` or `{}` type where a specific interface would be safer (Item 18)
+- Mutating a parameter typed as `readonly` — violates contract (Item 17)
+
+**HIGH — Type design**
+- `null | undefined` mixed in a union without clear intent — pick one (Item 31)
+- Boolean blindness: `(boolean, boolean)` tuple where a typed object with named fields would be clear (Item 34)
+- Invalid states representable in the type — redesign so invalid states are unrepresentable (Item 28)
+- `string` used for IDs/statuses where a branded type or union of literals would prevent mixing (Item 35)
+
+**MEDIUM — Type inference**
+- Unnecessary explicit type annotation where inference is clear (Item 19)
+- `return` type annotation missing on exported functions — aids documentation and catches errors (Item 19)
+- Type widened to `string[]` where `readonly string[]` would express intent (Item 17)
+- `typeof` guard where `instanceof` or a discriminated union would be more reliable (Item 22)
+
+**MEDIUM — Generics**
+- Generic constraint `<T extends object>` where `<T extends Record<string, unknown>>` is safer
+- Generic type parameter used only once — probably not needed (Item 50)
+- Missing `infer` in conditional types that extract sub-types (Item 50)
+
+**LOW — Structural typing**
+- Surprise excess property checks missed because of intermediate assignment — use direct object literal (Item 11)
+- Iterating `Object.keys()` with `as` cast — use `Object.entries()` with typed tuple (Item 54)
+
+### Step 4 — Apply clean-code-reviewer
+
+Focus areas from *Clean Code* applied to TypeScript:
+
+**HIGH — Naming**
+- Single-letter variable names outside of trivial loop counters or math
+- Boolean variables not phrased as predicates (`isLoading`, `hasError`, `canSubmit`)
+- Functions named with nouns instead of verbs (`dataProcessor` → `processData`)
+- Misleading names that don't match what the function does
+
+**MEDIUM — Functions**
+- Function over 20 lines — extract cohesive sub-functions
+- More than 3 parameters — group related params into an options object
+- Function does more than one thing — name reveals it (e.g., `fetchAndSave`)
+- Deep nesting over 3 levels — invert conditions / extract early returns
+
+**MEDIUM — Structure**
+- Comment explaining *what* the code does instead of *why* — rewrite as self-documenting code
+- Dead code: commented-out blocks, unused imports, unreachable branches
+- Magic numbers/strings — extract to named constants
+
+**LOW — Readability**
+- Negative conditionals (`if (!isNotReady)`) — invert
+- Inconsistent naming convention within a file (camelCase vs snake_case)
+
+### Step 5 — Output format
+
+```
+**Skills applied:** `effective-typescript` + `clean-code-reviewer`
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+```
+
+Consolidate similar findings. Only report issues you are >80% confident are real problems.

package/agents/ui-reviewer.md

@@ -0,0 +1,117 @@
+---
+name: ui-reviewer
+description: >
+  Expert UI and visual design reviewer applying booklib book-grounded
+  expertise. Combines refactoring-ui, storytelling-with-data, and animation-at-work.
+  Use when reviewing UI components, dashboards, data visualizations, or animations.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+
+You are a UI design reviewer with expertise from three canonical books: *Refactoring UI* (Wathan & Schoger), *Storytelling with Data* (Knaflic), and *Animation at Work* (Nabors).
+
+## Process
+
+### Step 1 — Get the scope
+
+Run `git diff HEAD -- '*.tsx' '*.jsx' '*.css' '*.scss' '*.svg'` to see changed UI files. Read the full component files for changed components — don't review diffs in isolation.
+
+Check for `CLAUDE.md` at project root.
+
+### Step 2 — Detect which skill(s) apply
+
+| Signal | Apply |
+|--------|-------|
+| Components, layout, spacing, typography, color | `refactoring-ui` |
+| Charts, graphs, tables, data dashboards | `storytelling-with-data` |
+| `transition`, `animation`, `@keyframes`, `motion` | `animation-at-work` |
+
+### Step 3 — Apply refactoring-ui
+
+Focus areas from *Refactoring UI*:
+
+**HIGH — Hierarchy and clarity**
+- All text the same size and weight — no visual hierarchy guiding the eye
+- Too many competing accent colors — use one primary, one semantic (error/success), one neutral
+- Backgrounds creating contrast problems — text failing WCAG AA (4.5:1 ratio for body text)
+- Spacing inconsistent — mixing arbitrary pixel values instead of a consistent scale (4/8/12/16/24/32/48...)
+
+**MEDIUM — Typography**
+- Line length over 75 characters for body text — add `max-width` to prose containers
+- Line height too tight for body text (needs 1.5–1.6 for readability)
+- All-caps used for long text — reserved for short labels and badges only
+- Font weight below 400 on body copy — hard to read at small sizes
+
+**MEDIUM — Component design**
+- Borders used to separate sections that spacing alone would separate — reduces visual noise
+- Empty state missing — component shows broken UI with no data instead of a placeholder
+- Loading state missing — component snaps in or shows raw skeleton without intent
+- Button using border-only style for primary action — primary should use filled background
+
+**LOW — Spacing and layout**
+- Icon and label not aligned on the same baseline
+- Inconsistent border-radius across similar components (some pill, some sharp)
+- Hover state color identical to pressed state — can't distinguish interaction phases
+
+### Step 4 — Apply storytelling-with-data (for charts/visualizations)
+
+Focus areas from *Storytelling with Data*:
+
+**HIGH — Chart type**
+- Pie/donut chart with more than 3 segments — use a bar chart (humans can't compare angles)
+- 3D chart used — depth distorts data and adds no information
+- Dual-axis chart without clear explanation — readers misinterpret the relationship
+- Area chart comparing multiple series where lines would be cleaner
+
+**HIGH — Data integrity**
+- Y-axis not starting at zero for a bar chart — exaggerates differences
+- Missing data points interpolated without disclosure
+- Aggregated metric (average) presented without variance or distribution context
+
+**MEDIUM — Clutter**
+- Gridlines darker than necessary — they should fade to background
+- Data labels on every point when a clear trend is the message — remove most, highlight one
+- Legend placed far from the data it labels — embed labels directly on series
+- Chart title restates the axis labels instead of stating the insight
+
+**LOW — Focus**
+- No visual emphasis on the key data point or trend — everything equal weight
+- Color used for decoration not for encoding meaning — pick one signal color
+
+### Step 5 — Apply animation-at-work (for motion)
+
+Focus areas from *Animation at Work*:
+
+**HIGH — Accessibility**
+- Animation missing `prefers-reduced-motion` media query — will trigger for vestibular users
+- `animation-duration` over 500ms for UI feedback (button press, toggle) — feels sluggish
+- Infinite animation with no pause mechanism — distracting and inaccessible
+
+**MEDIUM — Purpose**
+- Animation present but serves no functional purpose (doesn't aid comprehension or wayfinding)
+- Easing is linear — use `ease-out` for elements entering, `ease-in` for elements leaving
+- Multiple simultaneous animations competing for attention — sequence or simplify
+
+**LOW — Performance**
+- Animating `width`, `height`, `top`, `left` — triggers layout; use `transform` and `opacity` instead
+- `transition` on `all` — will animate unintended properties on state change; be explicit
+
+### Step 6 — Output format
+
+```
+**Skills applied:** [skills used]
+**Scope:** [files reviewed]
+
+### HIGH
+- `file:line` — finding
+
+### MEDIUM
+- `file:line` — finding
+
+### LOW
+- `file:line` — finding
+
+**Summary:** X HIGH, Y MEDIUM, Z LOW findings.
+```
+
+For UI findings without a clear line number, reference the component name and prop/class. Consolidate similar findings. Only report issues you are >80% confident are real problems.

package/assets/logo.svg

@@ -0,0 +1,36 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400" width="400" height="400">
+  <!-- Background -->
+  <rect width="400" height="400" rx="72" fill="#0d1117"/>
+
+  <!-- Left book page -->
+  <path d="M88 120 L88 300 Q88 316 104 316 L192 316 L192 104 Q160 88 112 92 Q88 96 88 120Z" fill="#1f6feb"/>
+
+  <!-- Right book page -->
+  <path d="M208 104 L208 316 L296 316 Q312 316 312 300 L312 120 Q312 96 288 92 Q240 88 208 104Z" fill="#2d84f5"/>
+
+  <!-- Spine -->
+  <rect x="192" y="100" width="16" height="216" fill="#58a6ff"/>
+
+  <!-- Left page lines -->
+  <rect x="112" y="155" width="64" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="112" y="175" width="52" height="8" rx="4" fill="white" opacity="0.40"/>
+  <rect x="112" y="195" width="68" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="112" y="215" width="44" height="8" rx="4" fill="white" opacity="0.35"/>
+  <rect x="112" y="235" width="60" height="8" rx="4" fill="white" opacity="0.50"/>
+  <rect x="112" y="255" width="48" height="8" rx="4" fill="white" opacity="0.35"/>
+
+  <!-- Right page lines -->
+  <rect x="224" y="155" width="64" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="224" y="175" width="52" height="8" rx="4" fill="white" opacity="0.40"/>
+  <rect x="224" y="195" width="68" height="8" rx="4" fill="white" opacity="0.55"/>
+  <rect x="224" y="215" width="44" height="8" rx="4" fill="white" opacity="0.35"/>
+  <rect x="224" y="235" width="60" height="8" rx="4" fill="white" opacity="0.50"/>
+  <rect x="224" y="255" width="48" height="8" rx="4" fill="white" opacity="0.35"/>
+
+  <!-- AI sparkle (4-pointed star) -->
+  <path d="M316 82 L322 66 L328 82 L344 88 L328 94 L322 110 L316 94 L300 88 Z" fill="#f0883e"/>
+
+  <!-- Accent dots -->
+  <circle cx="348" cy="60" r="5" fill="#f0883e" opacity="0.6"/>
+  <circle cx="296" cy="58" r="4" fill="#f0883e" opacity="0.4"/>
+</svg>

package/bin/booklib-mcp.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+import path from 'path';
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { BookLibSearcher } from "../lib/engine/searcher.js";
+import { BookLibAuditor } from "../lib/engine/auditor.js";
+import { BookLibHandoff } from "../lib/engine/handoff.js";
+import { resolveBookLibPaths } from "../lib/paths.js";
+import { ContextBuilder } from "../lib/context-builder.js";
+import {
+  serializeNode, saveNode, generateNodeId,
+  listNodes, loadNode, parseNodeFrontmatter,
+  resolveNodeRef, appendEdge, EDGE_TYPES,
+} from "../lib/engine/graph.js";
+import { BookLibIndexer } from "../lib/engine/indexer.js";
+
+const { skillsPath } = resolveBookLibPaths();
+const searcher = new BookLibSearcher();
+const auditor = new BookLibAuditor();
+const handoff = new BookLibHandoff();
+
+const server = new Server(
+  {
+    name: "booklib-engine",
+    version: "1.2.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "search_skills",
+        description: "Use BEFORE reviewing code, answering best-practices questions, or suggesting patterns. Searches BookLib's expert library and returns relevant principles with citations.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "The conceptual or technical search query (e.g., 'handling nulls', 'lean startup pivot')",
+            },
+            limit: {
+              type: "number",
+              description: "Maximum results (default: 5)",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "search_knowledge",
+        description: "Use for broader search that includes personal knowledge captured in this project. Returns results from both expert skills and saved insights/notes.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "The search query (e.g. 'handling concurrency in Python')",
+            },
+            limit: {
+              type: "number",
+              description: "Maximum number of results (default: 8)",
+            },
+            source: {
+              type: "string",
+              enum: ["all", "skills", "knowledge"],
+              description: "Filter by source: 'all' (default), 'skills', or 'knowledge'",
+            },
+          },
+          required: ["query"],
+        },
+      },
+      {
+        name: "audit_content",
+        description: "Use when the user asks for deep code review or quality analysis of a specific file. Audits against a named skill's principles and returns structured findings.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            skill_name: {
+              type: "string",
+              description: "The name of the skill to use (e.g., 'effective-kotlin', 'clean-code-reviewer')",
+            },
+            file_path: {
+              type: "string",
+              description: "The path to the file to audit.",
+            },
+          },
+          required: ["skill_name", "file_path"],
+        },
+      },
+      {
+        name: "save_session_state",
+        description: "Use when handing off to another agent or ending a long session. Saves progress, goals, and next steps so another agent can resume.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Optional session name (defaults to git branch)" },
+            goal: { type: "string", description: "The ultimate objective of the session" },
+            progress: { type: "string", description: "What has been achieved so far" },
+            next: { type: "string", description: "The immediate next task for the next agent" },
+            skills: { type: "string", description: "Comma-separated list of active BookLib skills" },
+          },
+          required: ["goal", "next"],
+        },
+      },
+      {
+        name: "get_context",
+        description: "Use at session start or when switching tasks to load relevant BookLib context for the current work. Returns combined wisdom from matched skills and knowledge graph.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            task: {
+              type: "string",
+              description: "The task description (e.g. 'implement JWT refresh token rotation')",
+            },
+            file: {
+              type: "string",
+              description: "Optional: path to the file being edited — enables graph context injection for the owning component",
+            },
+          },
+          required: ["task"],
+        },
+      },
+      {
+        name: "create_note",
+        description: "Use when the user discovers a useful pattern, says 'remember this', 'take a note', or 'capture this insight'. Creates a searchable knowledge node.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            title: {
+              type: "string",
+              description: "The note title (e.g. 'JWT refresh token strategy')",
+            },
+            content: {
+              type: "string",
+              description: "The note body (markdown supported). Leave empty to create a stub.",
+            },
+          },
+          required: ["title"],
+        },
+      },
+      {
+        name: "list_nodes",
+        description: "Use when the user asks 'what have I captured?' or wants to see saved knowledge. Lists all notes, insights, and research nodes.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            type_filter: {
+              type: "string",
+              description: "Optional: filter by node type ('note', 'research', 'component', 'decision', 'feature')",
+            },
+          },
+        },
+      },
+      {
+        name: "link_nodes",
+        description: "Use when the user says two concepts are related or wants to connect knowledge. Creates a typed relationship (see-also, applies-to, extends, etc.).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            from: {
+              type: "string",
+              description: "Source node — exact ID or partial title (e.g. 'JWT strategy')",
+            },
+            to: {
+              type: "string",
+              description: "Target node — exact ID or partial title (e.g. 'auth')",
+            },
+            type: {
+              type: "string",
+              enum: EDGE_TYPES,
+              description: "Edge type",
+            },
+          },
+          required: ["from", "to", "type"],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "search_skills":
+        const searchResults = await searcher.search(args.query, args.limit);
+        return { content: [{ type: "text", text: JSON.stringify(searchResults, null, 2) }] };
+
+      case "search_knowledge": {
+        const raw = await searcher.search(args.query, args.limit ?? 8);
+        const sourceFilter = args.source ?? 'all';
+        const results = raw
+          .filter(r => {
+            if (sourceFilter === 'skills') return r.metadata?.nodeKind !== 'knowledge';
+            if (sourceFilter === 'knowledge') return r.metadata?.nodeKind === 'knowledge';
+            return true;
+          })
+          .map(r => ({
+            source: r.metadata?.nodeKind === 'knowledge' ? 'knowledge' : 'skill',
+            title: r.metadata?.title ?? r.metadata?.skill ?? 'unknown',
+            text: r.text,
+            score: r.score,
+          }));
+        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+      }
+
+      case "audit_content":
+        const skillPath = path.join(skillsPath, args.skill_name);
+        const auditReport = await auditor.audit(skillPath, args.file_path);
+        return { content: [{ type: "text", text: auditReport }] };
+
+      case "save_session_state":
+        handoff.saveState(args);
+        return { content: [{ type: "text", text: `Session state saved successfully for ${args.name || 'current branch'}.` }] };
+
+      case "get_context": {
+        const builder = new ContextBuilder();
+        const result = args.file
+          ? await builder.buildWithGraph(args.task, args.file)
+          : await builder.build(args.task);
+        return { content: [{ type: "text", text: result }] };
+      }
+
+      case "create_note": {
+        const { nodesDir, indexPath } = resolveBookLibPaths();
+        const id = generateNodeId('node');
+        const nodeContent = serializeNode({
+          id,
+          type: 'note',
+          title: args.title,
+          content: args.content ?? '',
+        });
+        const filePath = saveNode(nodeContent, id, { nodesDir });
+        try {
+          const indexer = new BookLibIndexer(indexPath);
+          await indexer.indexNodeFile(filePath, nodesDir);
+        } catch {
+          // Index may not exist yet — node is saved, will appear after booklib index
+        }
+        return { content: [{ type: "text", text: `Created note: ${id}\nTitle: ${args.title}\nFile: ${filePath}` }] };
+      }
+
+      case "list_nodes": {
+        const { nodesDir } = resolveBookLibPaths();
+        const allIds = listNodes({ nodesDir });
+        const nodes = allIds
+          .map(id => {
+            const raw = loadNode(id, { nodesDir });
+            if (!raw) return null;
+            const parsed = parseNodeFrontmatter(raw);
+            return { id, title: parsed.title ?? '', type: parsed.type ?? '' };
+          })
+          .filter(n => {
+            if (!n) return false;
+            if (args.type_filter) return n.type === args.type_filter;
+            return true;
+          });
+        return { content: [{ type: "text", text: JSON.stringify(nodes, null, 2) }] };
+      }
+
+      case "link_nodes": {
+        const fromId = resolveNodeRef(args.from);
+        const toId = resolveNodeRef(args.to);
+        if (!EDGE_TYPES.includes(args.type)) {
+          throw new Error(`Invalid edge type "${args.type}". Valid: ${EDGE_TYPES.join(', ')}`);
+        }
+        const edge = {
+          from: fromId,
+          to: toId,
+          type: args.type,
+          weight: 1.0,
+          created: new Date().toISOString().split('T')[0],
+        };
+        appendEdge(edge);
+        return { content: [{ type: "text", text: `Edge created: ${fromId} --[${args.type}]--> ${toId}` }] };
+      }
+
+      default:
+        throw new Error(`Tool not found: ${name}`);
+    }
+  } catch (error) {
+    return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("BookLib Universal MCP Server running");
+}
+
+main().catch(console.error);