smoking-mirror 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ben Cassie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,259 @@
+# smoking-mirror
+
+> Obsidian vault intelligence for Claude Code - graph queries, wikilink suggestions, and vault health
+
+[![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.
+
+**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
+
+## 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:
+
+**Windows:**
+
+```json
+{
+  "mcpServers": {
+    "smoking-mirror": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "smoking-mirror"],
+      "env": {
+        "OBSIDIAN_VAULT_PATH": "C:\\Users\\you\\Documents\\MyVault"
+      }
+    }
+  }
+}
+```
+
+**macOS / Linux:**
+
+```json
+{
+  "mcpServers": {
+    "smoking-mirror": {
+      "command": "npx",
+      "args": ["-y", "smoking-mirror"],
+      "env": {
+        "OBSIDIAN_VAULT_PATH": "/Users/you/Documents/MyVault"
+      }
+    }
+  }
+}
+```
+
+### Verify Installation
+
+After adding, verify with:
+
+```bash
+claude mcp list
+```
+
+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.
+
+```
+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: [...]
+}
+```
+
+#### `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.
+
+```
+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
+
+## 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
+
+### Performance
+
+| Vault Size | Startup Time | Memory |
+|------------|--------------|--------|
+| 100 notes  | <200ms       | ~20MB  |
+| 500 notes  | <500ms       | ~30MB  |
+| 1500 notes | <2s          | ~50MB  |
+| 5000 notes | <5s          | ~100MB |
+
+### Error Handling
+
+- 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
+
+## License
+
+MIT - Ben Cassie
+
+## Related
+
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Claude Code](https://claude.ai/code)
+- [Obsidian](https://obsidian.md/)