seekstone 0.2.1 → 0.4.0

package/README.md

@@ -1,54 +1,75 @@
-# seekstone
+# seekstone / obsidian-mcp-seekstone
 
-**An Obsidian MCP server — filesystem-direct, low context-tax.**
+**The Obsidian MCP server for Claude — search and edit your vault without burning context.**
 
-Seekstone reads your Obsidian vault **directly from disk** instead of routing through the Obsidian Local REST API plugin. The practical difference: a search that returns ~1.75 MB / ~459,000 tokens via the REST plugin returns **~3 KB / ~800 tokens** via seekstone — a ~575× reduction. Claude can search and read notes without burning its context window on a single tool call.
+Seekstone is an Obsidian MCP server that gives Claude (and any [Model Context Protocol](https://modelcontextprotocol.io) client) direct read and write access to your Obsidian vault. No Obsidian app needs to be running, no plugins are required, and nothing leaves your machine.
 
-It runs as a standard [MCP](https://modelcontextprotocol.io) stdio server with no Obsidian app or plugin required — just point it at a vault directory.
+It reads your vault **directly from disk** instead of routing through the Obsidian Local REST API plugin. The practical difference: a search that returns ~1.75 MB and ~459,000 tokens via the REST plugin returns **~3 KB and ~800 tokens** via Seekstone — a **~575× reduction**. Claude can search and read your entire note library without burning most of its context window on a single tool call.
+
+**Two npm names, one server:**
+
+| Package | Best for |
+|---|---|
+| [`obsidian-mcp-seekstone`](https://www.npmjs.com/package/obsidian-mcp-seekstone) | Searching npm for "obsidian mcp" |
+| [`seekstone`](https://www.npmjs.com/package/seekstone) | Shorter name if you already know it |
+
+---
 
 ## Install
 
-```jsonc
-// Claude Desktop — claude_desktop_config.json
+Choose the method that suits you best.
+
+### Option 1 — One-click (Claude Desktop, no terminal needed)
+
+Download `seekstone.mcpb` from [GitHub Releases](https://github.com/shaqmughal/seekstone/releases/latest), double-click it in Claude Desktop, and pick your Obsidian vault folder when prompted. No JSON editing, no terminal, no Node.js setup required.
+
+### Option 2 — Guided setup (recommended for CLI users)
+
+Run the setup helper and let Seekstone find your vault automatically:
+
+```bash
+npx -y obsidian-mcp-seekstone init
+```
+
+Seekstone reads Obsidian's own vault registry to detect your vault, validates it, and either prints the config to paste or patches Claude Desktop directly:
+
+```bash
+# Auto-detect vault, print config to paste
+npx -y obsidian-mcp-seekstone init
+
+# Auto-detect vault, patch Claude Desktop in place (with backup)
+npx -y obsidian-mcp-seekstone init --write
+
+# Specify vault explicitly if you have multiple
+npx -y obsidian-mcp-seekstone init --vault "/path/to/vault"
+
+# Generate the Claude Code command instead
+npx -y obsidian-mcp-seekstone init --client code
+```
+
+### Option 3 — Manual config (Claude Desktop)
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
 {
   "mcpServers": {
     "seekstone": {
       "command": "npx",
-      "args": ["-y", "seekstone"],
+      "args": ["-y", "obsidian-mcp-seekstone"],
       "env": { "SEEKSTONE_VAULT": "/absolute/path/to/your/vault" }
     }
   }
 }
 ```
 
-Or with Claude Code:
+### Option 4 — Claude Code
 
 ```bash
-claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y seekstone
+claude mcp add seekstone --env SEEKSTONE_VAULT=/absolute/path/to/your/vault -- npx -y obsidian-mcp-seekstone
 ```
 
-Restart the client. On startup seekstone walks the vault and builds an in-memory full-text index (a couple of seconds for a few thousand notes), then keeps it in sync as notes change.
-
-### Guided setup
-
-`seekstone init` validates your vault and prints the config to paste, or patches the Claude Desktop config for you (with a backup, leaving other MCP servers untouched):
-
-```bash
-npx -y seekstone init --vault "/absolute/path/to/your/vault"          # print config
-npx -y seekstone init --vault "/absolute/path/to/your/vault" --write  # patch Claude Desktop
-npx -y seekstone init --vault "/absolute/path/to/your/vault" --client code  # print Claude Code command
-```
-
-## Configuration
-
-| Env var | Required | Description |
-|---|---|---|
-| `SEEKSTONE_VAULT` | yes | Absolute path to the Obsidian vault. |
-| `SEEKSTONE_LOG_LEVEL` | no | `error` \| `warn` \| `info` (default) \| `debug`. |
-| `SEEKSTONE_LOG_FILE` | no | Absolute path; when set, JSON-line logs are appended here (size-rotated). |
-| `SEEKSTONE_WATCH_POLL` | no | Set to `1` to stat-poll for changes instead of native OS events — slower but reliable on network drives, WSL, and some containers. |
-
-Works on macOS, Linux, and Windows.
+---
 
 ## Tools
 
@@ -63,10 +84,51 @@ Works on macOS, Linux, and Windows.
 | `append_note` | Append to a note body without touching frontmatter. |
 | `patch_frontmatter` | Set/update/delete frontmatter keys without reordering existing keys or changing quote style. |
 
+---
+
+## Configuration
+
+| Env var | Required | Description |
+|---|---|---|
+| `SEEKSTONE_VAULT` | yes | Absolute path to your Obsidian vault. |
+| `SEEKSTONE_LOG_LEVEL` | no | `error` \| `warn` \| `info` (default) \| `debug`. |
+| `SEEKSTONE_LOG_FILE` | no | Absolute path; when set, JSON-line logs are appended here (size-rotated). |
+| `SEEKSTONE_WATCH_POLL` | no | Set to `1` to stat-poll for changes instead of native OS events — reliable on network drives, WSL, containers. |
+
+---
+
+## Frequently asked questions
+
+**Does the Obsidian app need to be running?**
+No — Seekstone reads the vault folder from disk directly.
+
+**Do I need the Local REST API plugin?**
+No — Seekstone bypasses it entirely (that's where the 575× reduction comes from).
+
+**How does `seekstone init` find my vault automatically?**
+It reads Obsidian's own vault registry (`obsidian.json`) — the same file Obsidian uses to track your known vaults. One vault → auto-selected. Multiple → lists them and asks you to pick with `--vault`.
+
+**What is the `.mcpb` file?**
+An MCP Bundle — a zip containing the server and its manifest. Claude Desktop installs it with a double-click, no terminal required.
+
+**Which AI clients does it support?**
+Any MCP-over-stdio client: Claude Desktop, Claude Code, Cursor, Windsurf, Continue, and others.
+
+**Does it work on Windows?**
+Yes — tested on macOS, Linux, and Windows in CI on every commit.
+
+**Is it safe?**
+No network calls, no telemetry. The vault path is sandboxed — no tool reads or writes outside it.
+
+---
+
 ## Requirements
 
-- Node.js ≥ 22
+- Node.js ≥ 22 (for CLI install options; the `.mcpb` bundle has no external requirements)
+- macOS, Linux, or Windows
+
+---
 
 ## License
 
-MIT © Shaq Mughal. Source and issues: <https://github.com/shaqmughal/seekstone>
+MIT © Shaq Mughal · [GitHub](https://github.com/shaqmughal/seekstone) · [Issues](https://github.com/shaqmughal/seekstone/issues)