smoking-mirror 1.1.0 → 1.2.0

package/README.md

@@ -1,42 +1,277 @@
 # smoking-mirror
 
-> Obsidian vault intelligence for Claude Code - graph queries, wikilink suggestions, and vault health
+> Your vault's secrets stay yours. Claude sees only what it needs.
 
 [![npm version](https://badge.fury.io/js/smoking-mirror.svg)](https://www.npmjs.com/package/smoking-mirror)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## What is smoking-mirror?
+---
+
+## The Problem with AI + Your Notes
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     THE OLD WAY                                  │
+│                                                                  │
+│   "Claude, find notes about Project X"                          │
+│                                                                  │
+│   ┌──────────┐     ENTIRE VAULT      ┌──────────┐               │
+│   │  Claude  │ ◄──────────────────── │  1,500   │               │
+│   │   Code   │    (~50MB of text)    │  Notes   │               │
+│   └──────────┘                       └──────────┘               │
+│                                                                  │
+│   • Your private journals? Sent.                                 │
+│   • Financial notes? Sent.                                       │
+│   • That embarrassing poetry? Definitely sent.                   │
+│   • Token bill? Astronomical.                                    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                   THE SMOKING-MIRROR WAY                         │
+│                                                                  │
+│   "Claude, find notes about Project X"                          │
+│                                                                  │
+│   ┌──────────┐    STRUCTURED QUERY   ┌──────────┐               │
+│   │  Claude  │ ◄───────────────────► │ smoking  │               │
+│   │   Code   │  { backlinks: [...],  │ -mirror  │               │
+│   └──────────┘    tags: [...] }      └────┬─────┘               │
+│                                           │                      │
+│                    ONLY searches          │                      │
+│                    the index!             ▼                      │
+│                                      ┌──────────┐               │
+│                                      │  1,500   │               │
+│                                      │  Notes   │               │
+│                                      └──────────┘               │
+│                                                                  │
+│   • Your secrets? Never leave your machine.                      │
+│   • Claude sees? Filenames, links, tags. That's it.              │
+│   • Token usage? Minimal. Blazing fast.                          │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## What IS smoking-mirror?
+
+"Smoking mirror" (tezcatl in Nahuatl) is the literal translation of **obsidian**. This MCP server acts as a reflective surface that reveals the *structure* of your vault—without exposing the *content*.
+
+**47 tools** that answer questions like:
+- "What links to this note?" → **Backlinks returned, content untouched**
+- "Find orphan notes" → **Paths only, privacy intact**
+- "Search by #tag or frontmatter" → **Metadata queries, not content dumps**
+
+---
+
+## Privacy Architecture
+
+```
+    YOUR MACHINE                           │    CLOUD
+    ────────────────────────────────────── │ ────────────────
+                                           │
+    ┌─────────────────┐                    │
+    │   Obsidian      │                    │
+    │     Vault       │                    │
+    │  ┌───────────┐  │                    │
+    │  │ 📓 Notes  │  │  NEVER LEAVES      │
+    │  │ 📊 Data   │  │  ───────────►      │   ❌ Blocked
+    │  │ 📝 Journal│  │                    │
+    │  └───────────┘  │                    │
+    └────────┬────────┘                    │
+             │                             │
+             │ Parse locally               │
+             ▼                             │
+    ┌─────────────────┐                    │
+    │  smoking-mirror │                    │
+    │  ┌───────────┐  │                    │
+    │  │  Index    │  │                    │
+    │  │ • links   │  │                    │
+    │  │ • tags    │  │                    │
+    │  │ • paths   │  │                    │
+    │  └───────────┘  │                    │
+    └────────┬────────┘                    │
+             │                             │
+             │ Structured responses only   │
+             ▼                             │
+    ┌─────────────────┐    API calls      ┌─────────────────┐
+    │   Claude Code   │ ───────────────►  │    Claude AI    │
+    │                 │  (metadata only)  │                 │
+    │   "Find hubs"   │ ◄───────────────  │   (processes    │
+    │                 │  { paths, counts }│    structure)   │
+    └─────────────────┘                    └─────────────────┘
+```
+
+**What Claude receives:**
+- File paths and names
+- Link relationships (A → B)
+- Tag lists
+- Frontmatter keys/values
+- Word counts, modification dates
+
+**What Claude NEVER receives:**
+- Your actual note content (unless you explicitly Read it)
+- Personal journals
+- Private thoughts
+- Sensitive data
+
+---
+
+## Speed Demon
+
+Forget waiting for full-vault searches. smoking-mirror pre-indexes everything.
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                    PERFORMANCE BENCHMARKS                       │
+├────────────────┬───────────────┬───────────────┬───────────────┤
+│   Vault Size   │  Index Build  │  Query Time   │    Memory     │
+├────────────────┼───────────────┼───────────────┼───────────────┤
+│    100 notes   │    <200ms     │    <10ms      │    ~20MB      │
+│    500 notes   │    <500ms     │    <10ms      │    ~30MB      │
+│  1,500 notes   │     <2s       │    <10ms      │    ~50MB      │
+│  5,000 notes   │     <5s       │    <10ms      │   ~100MB      │
+└────────────────┴───────────────┴───────────────┴───────────────┘
+                              │
+                              ▼
+              Queries are INSTANT because
+              they hit an in-memory index,
+              not your filesystem.
+```
+
+---
+
+## Token Economy
+
+Every character Claude reads costs you tokens. Here's the math:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     TOKEN COMPARISON                             │
+│                                                                  │
+│   Traditional approach: "Read all notes with #project tag"       │
+│   ─────────────────────────────────────────────────────────     │
+│   📄 50 notes × ~2,000 tokens each = 100,000 tokens              │
+│   💰 Cost: ~$0.30 per query (Claude pricing)                     │
+│                                                                  │
+│   smoking-mirror: search_notes({ has_tag: "project" })           │
+│   ─────────────────────────────────────────────────────────     │
+│   📊 Returns: paths, titles, metadata                            │
+│   🎯 ~500 tokens total                                           │
+│   💰 Cost: ~$0.0015 per query                                    │
+│                                                                  │
+│   ═══════════════════════════════════════════════════════════   │
+│   SAVINGS: 200x fewer tokens per query                           │
+│   ═══════════════════════════════════════════════════════════   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Then Claude can surgically `Read` only the 2-3 notes it actually needs.
+
+---
+
+## 47 Tools at Your Service
 
-"Smoking mirror" (tezcatl in Nahuatl) is the literal translation of "obsidian". This MCP server acts as a reflective surface that reveals the hidden structure of your Obsidian vault to Claude Code.
+### Graph Intelligence
+| Tool | What it does |
+|------|--------------|
+| `get_backlinks` | Who's linking to this note? |
+| `get_forward_links` | What does this note link to? |
+| `find_orphan_notes` | Notes nobody loves (no incoming links) |
+| `find_hub_notes` | Your vault's superstars (highly connected) |
+
+### Wikilink Services
+| Tool | What it does |
+|------|--------------|
+| `suggest_wikilinks` | "You mentioned 'John'—want to link to [[John Smith]]?" |
+| `validate_links` | Find broken links before they embarrass you |
+| `find_broken_links` | [[Dead Note]] → nowhere |
+| `get_unlinked_mentions` | "John" mentioned 47 times, linked 3 times |
 
-**First-to-market** features:
-- **Graph Intelligence** - Backlinks, forward links, orphan detection, hub analysis
-- **Wikilink Services** - Auto-suggest entities, validate links
-- **Vault Health** - Broken link detection, comprehensive statistics
-- **Frontmatter Queries** - Search notes by metadata, tags, folders
+### Vault Health
+| Tool | What it does |
+|------|--------------|
+| `get_vault_stats` | The big picture: notes, links, tags, orphans |
+| `get_folder_structure` | Your vault's anatomy |
+| `get_activity_summary` | What's been happening lately? |
+
+### Smart Search
+| Tool | What it does |
+|------|--------------|
+| `search_notes` | Query by frontmatter, tags, folders—Dataview vibes |
+| `get_recent_notes` | Modified in the last N days |
+| `get_stale_notes` | Important notes gathering dust |
+| `get_notes_modified_on` | What happened on 2024-01-15? |
+| `get_notes_in_range` | Activity between two dates |
+
+### Deep Graph Analysis
+| Tool | What it does |
+|------|--------------|
+| `get_link_path` | How do these two notes connect? (A → B → C → D) |
+| `get_common_neighbors` | What do these notes have in common? |
+| `find_bidirectional_links` | Mutual admirers (A ↔ B) |
+| `find_dead_ends` | Popular notes that link nowhere |
+| `find_sources` | Link-givers, not link-receivers |
+| `get_connection_strength` | How related are these notes, really? |
+
+### Structure Analysis
+| Tool | What it does |
+|------|--------------|
+| `get_note_structure` | Full heading tree and sections |
+| `get_headings` | Just the headings, quick |
+| `get_section_content` | Extract a specific section |
+| `find_sections` | Find all "## References" across the vault |
+
+### Task Management
+| Tool | What it does |
+|------|--------------|
+| `get_all_tasks` | Every `- [ ]` in your vault |
+| `get_tasks_from_note` | Tasks in a specific note |
+| `get_tasks_with_due_dates` | What's due? |
+
+### Frontmatter Intelligence
+| Tool | What it does |
+|------|--------------|
+| `get_frontmatter_schema` | What fields exist across your vault? |
+| `get_field_values` | All unique values for `status` field |
+| `find_frontmatter_inconsistencies` | `status: "done"` vs `status: true` chaos |
+
+### Temporal Analysis
+| Tool | What it does |
+|------|--------------|
+| `get_contemporaneous_notes` | Edited around the same time |
+| `get_note_metadata` | Quick stats without reading content |
+
+### System
+| Tool | What it does |
+|------|--------------|
+| `refresh_index` | Rebuilt after Obsidian changes |
+| `get_all_entities` | Every linkable thing (titles + aliases) |
+
+---
 
 ## Installation
 
 ### Quick Install (Claude Code CLI)
 
 **macOS / Linux:**
-
 ```bash
 claude mcp add smoking-mirror -e OBSIDIAN_VAULT_PATH=/path/to/your/vault -- npx -y smoking-mirror
 ```
 
 **Windows:**
-
 ```bash
 claude mcp add smoking-mirror -e OBSIDIAN_VAULT_PATH=C:\path\to\your\vault -- cmd /c npx -y smoking-mirror
 ```
 
 ### Manual Configuration
 
-Alternatively, add to your `.mcp.json` file:
+Add to your `.mcp.json`:
 
 **Windows:**
-
 ```json
 {
   "mcpServers": {
@@ -52,7 +287,6 @@ Alternatively, add to your `.mcp.json` file:
 ```
 
 **macOS / Linux:**
-
 ```json
 {
   "mcpServers": {
@@ -67,241 +301,147 @@ Alternatively, add to your `.mcp.json` file:
 }
 ```
 
-### Verify Installation
-
-After adding, verify with:
+### Verify
 
 ```bash
 claude mcp list
+# Should show: smoking-mirror ✓
 ```
 
-You should see `smoking-mirror` in the list of configured servers.
-
-## Tools
+---
 
-### Graph Intelligence
-
-#### `get_backlinks`
-Find all notes that link TO a specific note.
+## Real-World Example
 
 ```
-Input: { path: "projects/My Project.md" }
-Output: [{ source: "daily/2024-01-15.md", line: 42, context: "Working on [[My Project]] today" }]
-```
+You: "What are my most connected project notes?"
 
-#### `get_forward_links`
-Find all notes that a specific note links TO.
+Claude uses: find_hub_notes({ min_links: 10 })
 
-```
-Input: { path: "projects/My Project.md" }
-Output: [{ target: "Team Members", exists: true, resolved_path: "people/Team Members.md" }]
-```
-
-#### `find_orphan_notes`
-Find notes with no incoming links (potential cleanup candidates).
-
-```
-Input: { folder: "archive" }  // optional folder filter
-Output: [{ path: "archive/old-idea.md", title: "old-idea", modified: "2024-01-01" }]
-```
-
-#### `find_hub_notes`
-Find highly connected notes (potential MOCs or index notes).
-
-```
-Input: { min_links: 10 }  // minimum total connections
-Output: [{ path: "MOC.md", backlink_count: 45, forward_link_count: 23, total_connections: 68 }]
-```
-
-### Wikilink Services
-
-#### `suggest_wikilinks`
-Analyze text and suggest where wikilinks could be added based on existing notes.
-
-```
-Input: { text: "Meeting with John about the API project" }
-Output: [
-  { entity: "John", start: 13, end: 17, target: "people/John Smith.md" },
-  { entity: "API project", start: 28, end: 39, target: "projects/API Project.md" }
-]
-```
-
-#### `validate_links`
-Check wikilinks in a note (or all notes) and report broken links.
-
-```
-Input: { path: "projects/My Project.md" }  // optional, validates all if omitted
-Output: [{ source: "projects/My Project.md", target: "Missing Note", line: 15, exists: false }]
-```
-
-### Vault Health
-
-#### `get_vault_stats`
-Get comprehensive statistics about your vault.
-
-```
-Output: {
-  total_notes: 1444,
-  total_links: 20373,
-  total_tags: 431,
-  orphan_notes: 971,
-  broken_links: 8565,
-  average_links_per_note: 14.11,
-  most_linked_notes: [...],
-  top_tags: [...],
-  folders: [...]
+Response (what Claude actually sees):
+{
+  "hubs": [
+    { "path": "projects/Main Project.md", "connections": 47 },
+    { "path": "areas/Work.md", "connections": 34 },
+    { "path": "resources/API Docs.md", "connections": 28 }
+  ]
 }
-```
-
-#### `find_broken_links`
-Find all wikilinks that point to non-existent notes.
-
-```
-Input: { folder: "projects" }  // optional folder filter
-Output: [{ source: "projects/Old.md", target: "Deleted Note", line: 5 }]
-```
-
-### Query
-
-#### `search_notes`
-Search notes by frontmatter fields, tags, folders, or title. Covers ~80% of Dataview use cases.
 
+Your actual note content? Still safely on your disk.
+Claude knows the STRUCTURE, not the SECRETS.
 ```
-Input: {
-  has_tag: "project",
-  where: { status: "active" },
-  folder: "work",
-  sort_by: "modified",
-  limit: 10
-}
-Output: [{ path: "work/Current.md", title: "Current", frontmatter: {...}, tags: [...] }]
-```
-
-**Parameters:**
-- `where` - Frontmatter key-value filters (e.g., `{ type: "book", rating: 5 }`)
-- `has_tag` - Filter by single tag
-- `has_any_tag` - Filter by any of these tags
-- `has_all_tags` - Filter by all of these tags
-- `folder` - Limit to notes in this folder
-- `title_contains` - Filter by title substring
-- `sort_by` - Sort by "modified", "created", or "title"
-- `order` - "asc" or "desc"
-- `limit` - Maximum results to return
 
-### System (v1.1)
-
-#### `refresh_index`
-Rebuild the vault index without restarting the server.
-
-```
-Output: { success: true, notes_count: 1444, entities_count: 3421, duration_ms: 1823 }
-```
-
-#### `get_all_entities`
-Get all linkable entities (note titles and aliases).
-
-```
-Input: { include_aliases: true, limit: 100 }
-Output: { entity_count: 100, entities: [{ name: "John Smith", path: "people/John Smith.md", is_alias: false }] }
-```
-
-#### `get_recent_notes`
-Get notes modified within the last N days.
-
-```
-Input: { days: 7, limit: 50 }
-Output: { count: 23, days: 7, notes: [{ path: "daily/2024-01-15.md", title: "2024-01-15", modified: "...", tags: [...] }] }
-```
-
-#### `get_unlinked_mentions`
-Find mentions of an entity that aren't linked (linking opportunities).
-
-```
-Input: { entity: "John Smith", limit: 50 }
-Output: { entity: "John Smith", mention_count: 12, mentions: [{ path: "meetings/standup.md", line: 5, context: "Talked to John Smith about..." }] }
-```
-
-#### `get_note_metadata`
-Get metadata about a note without reading full content.
-
-```
-Input: { path: "projects/API.md", include_word_count: true }
-Output: { path: "...", title: "API", frontmatter: {...}, tags: [...], outlink_count: 15, backlink_count: 8, word_count: 2340 }
-```
-
-#### `get_folder_structure`
-Get the folder structure of the vault with note counts.
-
-```
-Output: { folder_count: 12, folders: [{ path: "daily", note_count: 365, subfolder_count: 0 }] }
-```
+---
 
 ## Architecture
 
-- **File-first**: Parses markdown directly, no database required
-- **Works offline**: No connection to Obsidian needed
-- **Fast startup**: <2s for 1500+ notes
-- **Memory efficient**: ~50MB for large vaults
-- **Parallel parsing**: Processes files in batches for speed
+```
+                    ┌────────────────────────────────┐
+                    │         smoking-mirror         │
+                    │                                │
+┌──────────┐        │  ┌──────────────────────────┐  │
+│          │        │  │       VaultIndex         │  │
+│ Obsidian │  scan  │  │                          │  │
+│  Vault   │───────►│  │  notes: Map<path, Note>  │  │
+│          │        │  │  backlinks: Map<→Set>    │  │
+│  📁 .md  │        │  │  entities: Map<name→path>│  │
+│  files   │        │  │  tags: Map<tag→Set>      │  │
+│          │        │  │                          │  │
+└──────────┘        │  └──────────────────────────┘  │
+                    │              │                  │
+                    │              ▼                  │
+                    │  ┌──────────────────────────┐  │
+                    │  │      47 MCP Tools        │  │
+                    │  │                          │  │
+                    │  │  Queries return          │  │
+                    │  │  STRUCTURE not CONTENT   │  │
+                    │  │                          │  │
+                    │  └──────────────────────────┘  │
+                    │                                │
+                    └────────────────────────────────┘
+                                   │
+                                   │ MCP Protocol
+                                   ▼
+                           ┌──────────────┐
+                           │ Claude Code  │
+                           └──────────────┘
+```
+
+**Key Design Decisions:**
+- **File-first**: Parses markdown directly, no database
+- **Works offline**: No connection to Obsidian app needed
+- **Eager loading**: Full index on startup (fine for <5000 notes)
+- **In-memory graph**: Lightning-fast queries
+- **Privacy by design**: Content stays local
+
+---
+
+## Error Handling
+
+| Situation | Behavior |
+|-----------|----------|
+| Malformed YAML | Gracefully skipped, file treated as content |
+| Binary files | Detected and skipped |
+| Empty files | Indexed with no links/tags |
+| Large files (>10MB) | Skipped with warning |
+| Missing files | Graceful degradation |
+
+---
 
-### Performance
+## Why not Dataview?
 
-| Vault Size | Startup Time | Memory |
-|------------|--------------|--------|
-| 100 notes  | <200ms       | ~20MB  |
-| 500 notes  | <500ms       | ~30MB  |
-| 1500 notes | <2s          | ~50MB  |
-| 5000 notes | <5s          | ~100MB |
+We wanted to use `obsidian-dataview` as a library, but it requires Obsidian's internal `CachedMetadata` API and cannot run standalone. See [this discussion](https://github.com/blacksmithgu/obsidian-dataview/discussions/1811).
 
-### Error Handling
+Instead, smoking-mirror:
+- Parses markdown directly using `gray-matter`
+- Builds its own in-memory graph index
+- Provides ~80% of Dataview functionality with simpler syntax
+- And does it all **without exposing your content to AI**
 
-- Malformed YAML frontmatter: Gracefully skipped, file treated as content
-- Binary files: Detected and skipped
-- Empty files: Indexed with no links/tags
-- Large files (>10MB): Skipped with warning
-- Timeout protection: 5-minute default for vault indexing
+---
 
 ## Development
 
 ```bash
-# Install dependencies
 bun install
-
-# Run in development mode
 OBSIDIAN_VAULT_PATH=/path/to/vault bun run dev
-
-# Build for distribution
 bun run build
-
-# Test with MCP inspector
 bun run inspect
-
-# Run tests
 bun test
 ```
 
-## Why not Dataview?
-
-We initially planned to use `obsidian-dataview` as a library, but discovered it requires Obsidian's internal `CachedMetadata` API and cannot run standalone. See [this discussion](https://github.com/blacksmithgu/obsidian-dataview/discussions/1811).
-
-Instead, smoking-mirror:
-- Parses markdown files directly using `gray-matter`
-- Builds its own in-memory graph index
-- Provides ~80% of Dataview functionality with simpler syntax
+---
 
 ## Roadmap
 
-- [ ] MarkdownDB integration for SQL-like queries
 - [ ] Watch mode for incremental updates
 - [ ] `rename_with_links` - Safe note renaming with reference updates
-- [ ] Obsidian REST API integration for live Dataview queries
+- [ ] MarkdownDB integration for SQL-like queries
+- [ ] Semantic search via local embeddings
+
+---
 
 ## License
 
 MIT - Ben Cassie
 
+---
+
+## The Philosophy
+
+> Your notes are yours. Your thoughts are private. Your vault is sacred.
+>
+> AI should help you navigate your knowledge—not consume it.
+>
+> smoking-mirror gives Claude the **map**, not the **territory**.
+
+---
+
 ## Related
 
 - [Model Context Protocol](https://modelcontextprotocol.io/)
 - [Claude Code](https://claude.ai/code)
 - [Obsidian](https://obsidian.md/)
+
+---
+
+*"tezcatl" — the obsidian mirror that reveals truth without taking it*