npm - smoking-mirror - Versions diffs - 1.0.0 → 1.2.0 - Mend

smoking-mirror 1.0.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -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?
+---
-"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.
+## The Problem with AI + Your Notes
-**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
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     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
+### 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 |
+### 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,193 +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.
-```
-Input: { path: "projects/My Project.md" }
-Output: [{ source: "daily/2024-01-15.md", line: 42, context: "Working on [[My Project]] today" }]
-```
+---
-#### `get_forward_links`
-Find all notes that a specific note links TO.
+## Real-World Example
 ```
-Input: { path: "projects/My Project.md" }
-Output: [{ target: "Team Members", exists: true, resolved_path: "people/Team Members.md" }]
-```
+You: "What are my most connected project notes?"
-#### `find_orphan_notes`
-Find notes with no incoming links (potential cleanup candidates).
+Claude uses: find_hub_notes({ min_links: 10 })
-```
-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.
+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 }
+  ]
+}
+Your actual note content? Still safely on your disk.
+Claude knows the STRUCTURE, not the SECRETS.
 ```
-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: [...]
-}
-```
+---
-#### `find_broken_links`
-Find all wikilinks that point to non-existent notes.
+## Architecture
 ```
-Input: { folder: "projects" }  // optional folder filter
-Output: [{ source: "projects/Old.md", target: "Deleted Note", line: 5 }]
+                    ┌────────────────────────────────┐
+                    │         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  │
+                           └──────────────┘
 ```
-### Query
+**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
-#### `search_notes`
-Search notes by frontmatter fields, tags, folders, or title. Covers ~80% of Dataview use cases.
-```
-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
+## Error Handling
-## Architecture
+| 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 |
-- **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
+---
-### 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*