@nathanld/obsidian-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Duarte
+
+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,149 @@
+# @nathanld/obsidian-server
+
+Point it at any [Obsidian](https://obsidian.md) vault and get, out of the box:
+
+- an **MCP server** (Streamable HTTP, `/mcp`) exposing your vault's commands as tools to Claude and other MCP clients
+- a **REST API** (`/api/*`) over the same commands
+- **Bearer-token auth** (via [better-auth](https://www.better-auth.com/)'s API key plugin) protecting everything except a bare `/health` check
+
+It works by driving the official Obsidian CLI companion binary under the hood, then classifying and gating every command by how safe it is to expose to an LLM.
+
+## Requirements
+
+- **Bun >= 1.2** — the server is Bun-only (it uses `bun:sqlite`, `Bun.serve`, and `Bun.spawn` directly; it will not run under Node).
+- The **Obsidian desktop app** must be running, with its official CLI companion installed and on `PATH` (or pass `--binary <path>` to point at it explicitly). If the CLI can't be reached, `serve` exits with an error explaining how to fix it.
+
+## Install / run
+
+Run it without installing anything:
+
+```sh
+bunx @nathanld/obsidian-server serve
+```
+
+Or install it globally:
+
+```sh
+bun add -g @nathanld/obsidian-server
+obsidian-server serve
+```
+
+## First run: the token flow
+
+The first time `serve` starts, it bootstraps a single local "owner" account and mints an API key automatically. That key is printed **exactly once**, in the startup banner:
+
+```
+obsidian-server is running
+  vault:        my-vault
+  REST base:    http://127.0.0.1:3000
+  MCP endpoint: http://127.0.0.1:3000/mcp
+
+  commands exposed: 65/102
+    read: 54
+    write: 11
+    destructive: 0 (disabled - pass --allow destructive)
+    app-control: 0 (disabled - pass --allow app-control)
+
+  A new API key was minted (shown ONLY ONCE - copy it now):
+    <secret key>
+
+  Add this server to an MCP client:
+    claude mcp add --transport http obsidian http://127.0.0.1:3000/mcp --header "Authorization: Bearer <secret key>"
+```
+
+Copy the key now — it's hashed at rest and cannot be recovered later. On every subsequent `serve`, the existing key is reused and the banner just reminds you to mint a new one if you need it:
+
+```sh
+obsidian-server token mint --name my-new-key
+```
+
+### Connecting Claude Code
+
+```sh
+claude mcp add --transport http obsidian http://127.0.0.1:3000/mcp --header "Authorization: Bearer <token>"
+```
+
+(the exact command, with your real token filled in, is printed in the startup banner on first run).
+
+## CLI reference
+
+```
+obsidian-server <command> [flags]
+```
+
+| Flag | Global |
+|---|---|
+| `--version`, `-v` | Print the version and exit. |
+| `--help`, `-h` | Print usage and exit. |
+
+### `serve`
+
+```
+obsidian-server serve [--vault <name>] [--port 3000] [--host 127.0.0.1]
+                       [--allow destructive] [--allow app-control]
+                       [--data-dir <path>] [--binary <path>] [--timeout-ms <n>]
+```
+
+| Flag | Meaning |
+|---|---|
+| `--vault <name>` | Target a specific vault by name. Omit to use whatever vault is currently active in the running Obsidian app. |
+| `--port <n>` | Port to bind (default `3000`). |
+| `--host <host>` | Host/interface to bind (default `127.0.0.1`). See [Security](#security) before binding beyond localhost. |
+| `--allow destructive` | Also expose commands classified `destructive` (repeatable/combinable with `--allow app-control`). |
+| `--allow app-control` | Also expose commands classified `app-control`. |
+| `--data-dir <path>` | Override where the auth SQLite database lives. Defaults to `$XDG_DATA_HOME/obsidian-server`, or `~/.local/share/obsidian-server`. |
+| `--binary <path>` | Explicit path to the `obsidian` CLI binary, if it isn't on `PATH`. |
+| `--timeout-ms <n>` | Timeout for each underlying `obsidian` CLI invocation. |
+
+### `token`
+
+```
+obsidian-server token mint --name <label> [--expires-days <n>] [--data-dir <path>]
+obsidian-server token list [--data-dir <path>]
+obsidian-server token revoke --id <id> [--data-dir <path>]
+```
+
+- `mint` prints the new key's plaintext **once** — it is hashed before being stored and cannot be displayed again.
+- `list` prints metadata only (id, name, enabled, created/expires/last-used timestamps) — never a key's secret or hash.
+- `revoke` disables a key by id (soft-delete; it stays in `list` for an audit trail, just as `enabled=false`).
+
+## REST endpoints
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/health` | open | `{ ok, obsidian, vault }` — whether the server is up and whether the Obsidian CLI is currently reachable. |
+| `GET` | `/api/commands` | Bearer | List every exposed command (name, description, classification, options), given the current `--allow` flags. |
+| `POST` | `/api/commands/:name` | Bearer | Run one command. JSON body is a flat object of option values (string/number/boolean); empty body is fine for commands that take no options. Returns `{ ok: true, stdout }`, or `{ ok: false, error }` with `404` (unknown command or gated-off), `400` (bad body/options), `504` (the CLI call timed out), or `502` (the CLI call itself failed). |
+
+Every route under `/api/*` (and `/mcp`, below) requires `Authorization: Bearer <token>`; a missing, malformed, unknown, expired, or disabled key all get an identical `401 { "error": "unauthorized" }` — see [Security](#security).
+
+## MCP
+
+`/mcp` (Bearer-protected, Streamable HTTP) exposes one MCP tool per exposed Obsidian CLI command, plus one discovery tool:
+
+- **`obsidian_<command>`** — one tool per exposed command, named by replacing `:` with `_` and prefixing `obsidian_` (e.g. the `daily:append` command becomes the `obsidian_daily_append` tool). Commands that aren't currently allowed (see gating, below) are never registered as tools at all — they don't exist, rather than existing and refusing.
+- **`server_commands`** — lists every currently-exposed command along with its MCP tool name, description, classification, and options, as JSON. Useful for a client to discover what's available without guessing tool names.
+
+## Safety gating model
+
+The Obsidian CLI exposes a **102-command surface**. Every command is hand-classified into one of four tiers (`packages/obsidian-cli`'s `classify.ts`):
+
+| Classification | Exposed by default? | Meaning |
+|---|---|---|
+| `read` | Yes | Pure queries — no side effects on vault content or the app. |
+| `write` | Yes | Mutates vault note content (create/append/prepend a note, set a property, insert a template, toggle a task, ...). |
+| `destructive` | No — needs `--allow destructive` | Irreversibly removes or overwrites vault content (delete, remove a property, restore an older version over the current one). |
+| `app-control` | No — needs `--allow app-control` | Affects the running app/workspace rather than vault content: opening panes/tabs, plugin/theme/snippet management, sync pause/resume, restart/reload, running an arbitrary registered command by id, and the entire `Developer:` surface (DevTools protocol access, arbitrary `eval`). Treated as the most restricted tier even where an individual verb only reads data, because the blast radius or opacity is high. An unrecognized/future command name also defaults here. |
+
+`read` and `write` are always exposed; `destructive` and `app-control` are opt-in per `serve` invocation via `--allow`, and only take effect for that run — nothing is ever persisted as "allowed" across restarts.
+
+## Security
+
+- **Binds to `127.0.0.1` by default.** Only requests from the same machine can reach it.
+- **Binding beyond localhost is not fully wired up yet.** Passing `--host 0.0.0.0` (or any non-localhost address) prints a startup warning that DNS-rebinding protection is disabled for that bind, because the underlying MCP transport only auto-enables its Host/Origin allowlist for localhost-class binds and this CLI does not yet expose flags to configure `allowedHosts`/`allowedOrigins` itself. Treat any non-localhost bind as unprotected against DNS rebinding until that's addressed, and prefer an SSH tunnel or reverse proxy you control instead of binding a public interface directly.
+- **Keys are hashed at rest.** better-auth's API key plugin hashes stored keys (SHA-256); the plaintext is only ever shown once, at mint time.
+- **Uniform 401s.** A missing header, malformed header, unknown key, expired key, or disabled key are all indistinguishable from the outside — every failure mode returns the same `401 { "error": "unauthorized" }` with a `WWW-Authenticate: Bearer` challenge, so nothing about *why* auth failed is observable.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/cli.js

@@ -0,0 +1,1090 @@
+#!/usr/bin/env bun
+// @bun
+
+// apps/server/src/cli.ts
+import { parseArgs } from "util";
+
+// apps/server/src/gating.ts
+var DEFAULT_CLASSIFICATIONS = ["read", "write"];
+var GATED_CLASSIFICATIONS = ["destructive", "app-control"];
+
+class UnknownAllowFlagError extends Error {
+  value;
+  constructor(value) {
+    super(`Unknown --allow value "${value}" (expected one of: ${GATED_CLASSIFICATIONS.join(", ")})`);
+    this.value = value;
+    this.name = "UnknownAllowFlagError";
+  }
+}
+function isGatedClassification(value) {
+  return GATED_CLASSIFICATIONS.includes(value);
+}
+function computeAllowedClassifications(allowFlags) {
+  const allowed = new Set(DEFAULT_CLASSIFICATIONS);
+  for (const flag of allowFlags) {
+    if (!isGatedClassification(flag))
+      throw new UnknownAllowFlagError(flag);
+    allowed.add(flag);
+  }
+  return allowed;
+}
+
+// apps/server/src/serve.ts
+import { mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+
+// packages/auth/src/config.ts
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import { Database } from "bun:sqlite";
+import { betterAuth } from "better-auth";
+import { apiKey } from "@better-auth/api-key";
+
+// packages/auth/src/bearer.ts
+var BEARER_PATTERN = /^Bearer\s+(.+)$/i;
+function extractBearerToken(headerValue) {
+  if (!headerValue)
+    return null;
+  const match = BEARER_PATTERN.exec(headerValue.trim());
+  const token = match?.[1]?.trim();
+  return token ? token : null;
+}
+
+// packages/auth/src/config.ts
+function ensureParentDirExists(dbPath) {
+  if (dbPath === ":memory:" || dbPath.startsWith("file::memory:"))
+    return;
+  mkdirSync(dirname(dbPath), { recursive: true });
+}
+function createAuth(options) {
+  ensureParentDirExists(options.dbPath);
+  const database = new Database(options.dbPath, { create: true });
+  return betterAuth({
+    database,
+    baseURL: options.baseURL,
+    secret: options.secret,
+    emailAndPassword: {
+      enabled: false,
+      disableSignUp: true
+    },
+    plugins: [
+      apiKey({
+        requireName: true,
+        rateLimit: { enabled: false },
+        customAPIKeyGetter: (ctx) => extractBearerToken(ctx.headers?.get("authorization") ?? null)
+      })
+    ]
+  });
+}
+// packages/auth/src/migrate.ts
+async function migrate(auth) {
+  const ctx = await auth.$context;
+  await ctx.runMigrations();
+}
+// packages/auth/src/owner.ts
+var DEFAULT_OWNER_EMAIL = "owner@obsidian-server.local";
+var DEFAULT_OWNER_NAME = "Owner";
+async function bootstrap(auth, options = {}) {
+  await migrate(auth);
+  const ctx = await auth.$context;
+  const existing = await ctx.adapter.findMany({ model: "user", limit: 1 });
+  const existingUser = existing[0];
+  if (existingUser) {
+    return { id: existingUser.id, email: existingUser.email, name: existingUser.name, created: false };
+  }
+  const email = options.email ?? DEFAULT_OWNER_EMAIL;
+  const name = options.name ?? DEFAULT_OWNER_NAME;
+  const user = await ctx.internalAdapter.createUser({
+    email,
+    name,
+    emailVerified: true
+  });
+  return { id: user.id, email: user.email, name: user.name, created: true };
+}
+async function resolveOwnerId(auth) {
+  const ctx = await auth.$context;
+  const existing = await ctx.adapter.findMany({ model: "user", limit: 1 });
+  const owner = existing[0];
+  if (!owner) {
+    throw new Error("No owner user found. Run bootstrap() (or the `bootstrap` CLI command) first.");
+  }
+  return owner.id;
+}
+// packages/auth/src/keys.ts
+var SECONDS_PER_DAY = 24 * 60 * 60;
+async function mintKey(auth, options) {
+  const userId = options.userId ?? await resolveOwnerId(auth);
+  const expiresIn = options.expiresDays !== undefined ? options.expiresDays * SECONDS_PER_DAY : undefined;
+  const created = await auth.api.createApiKey({
+    body: {
+      userId,
+      name: options.name,
+      expiresIn
+    }
+  });
+  return {
+    id: created.id,
+    key: created.key,
+    name: created.name,
+    expiresAt: created.expiresAt
+  };
+}
+var SAFE_KEY_COLUMNS = ["id", "name", "start", "enabled", "createdAt", "expiresAt", "lastRequest", "referenceId"];
+async function listKeys(auth, options = {}) {
+  const userId = options.userId ?? await resolveOwnerId(auth);
+  const ctx = await auth.$context;
+  const rows = await ctx.adapter.findMany({
+    model: "apikey",
+    where: [{ field: "referenceId", value: userId }],
+    sortBy: { field: "createdAt", direction: "desc" },
+    select: SAFE_KEY_COLUMNS
+  });
+  return rows.map((row) => ({
+    id: row.id,
+    name: row.name,
+    start: row.start,
+    enabled: row.enabled,
+    createdAt: row.createdAt,
+    expiresAt: row.expiresAt,
+    lastRequest: row.lastRequest
+  }));
+}
+async function revokeKey(auth, options) {
+  const ctx = await auth.$context;
+  const updated = await ctx.adapter.update({
+    model: "apikey",
+    where: [{ field: "id", value: options.id }],
+    update: { enabled: false }
+  });
+  if (!updated) {
+    throw new Error(`No API key found with id "${options.id}".`);
+  }
+  return { id: options.id, revoked: true };
+}
+async function ensureOwnerAndKey(auth, options = {}) {
+  const owner = await bootstrap(auth, { name: options.name, email: options.email });
+  const existingKeys = await listKeys(auth, { userId: owner.id });
+  const now = Date.now();
+  const active = existingKeys.find((k) => k.enabled && (k.expiresAt === null || k.expiresAt.getTime() > now));
+  if (active) {
+    return { created: false, keyId: active.id };
+  }
+  const minted = await mintKey(auth, { userId: owner.id, name: options.keyName ?? "bootstrap" });
+  return { created: true, key: minted.key, keyId: minted.id };
+}
+// packages/auth/src/middleware.ts
+function unauthorized(c) {
+  c.header("WWW-Authenticate", "Bearer");
+  return c.json({ error: "unauthorized" }, 401);
+}
+function requireAuth(auth) {
+  return async (c, next) => {
+    const token = extractBearerToken(c.req.header("authorization"));
+    if (!token) {
+      return unauthorized(c);
+    }
+    let result;
+    try {
+      result = await auth.api.verifyApiKey({ body: { key: token } });
+    } catch {
+      return unauthorized(c);
+    }
+    if (!result.valid || !result.key) {
+      return unauthorized(c);
+    }
+    const ctx = await auth.$context;
+    const user = await ctx.internalAdapter.findUserById(result.key.referenceId);
+    if (!user) {
+      return unauthorized(c);
+    }
+    c.set("user", { id: user.id, email: user.email, name: user.name });
+    c.set("apiKey", { id: result.key.id, name: result.key.name });
+    await next();
+  };
+}
+// packages/obsidian-cli/src/classify.ts
+var CLASSIFICATION = {
+  aliases: "read",
+  backlinks: "read",
+  "base:query": "read",
+  "base:views": "read",
+  bases: "read",
+  bookmarks: "read",
+  commands: "read",
+  "daily:path": "read",
+  "daily:read": "read",
+  deadends: "read",
+  diff: "read",
+  file: "read",
+  files: "read",
+  folder: "read",
+  folders: "read",
+  help: "read",
+  history: "read",
+  "history:list": "read",
+  "history:read": "read",
+  hotkey: "read",
+  hotkeys: "read",
+  links: "read",
+  orphans: "read",
+  outline: "read",
+  plugin: "read",
+  plugins: "read",
+  "plugins:enabled": "read",
+  properties: "read",
+  "property:read": "read",
+  "random:read": "read",
+  read: "read",
+  recents: "read",
+  search: "read",
+  "search:context": "read",
+  snippets: "read",
+  "snippets:enabled": "read",
+  "sync:deleted": "read",
+  "sync:history": "read",
+  "sync:read": "read",
+  "sync:status": "read",
+  tabs: "read",
+  tag: "read",
+  tags: "read",
+  tasks: "read",
+  "template:read": "read",
+  templates: "read",
+  theme: "read",
+  themes: "read",
+  unresolved: "read",
+  vault: "read",
+  vaults: "read",
+  version: "read",
+  wordcount: "read",
+  workspace: "read",
+  append: "write",
+  "base:create": "write",
+  create: "write",
+  "daily:append": "write",
+  "daily:prepend": "write",
+  move: "write",
+  prepend: "write",
+  "property:set": "write",
+  rename: "write",
+  task: "write",
+  "template:insert": "write",
+  delete: "destructive",
+  "history:restore": "destructive",
+  "property:remove": "destructive",
+  "sync:restore": "destructive",
+  bookmark: "app-control",
+  command: "app-control",
+  daily: "app-control",
+  "history:open": "app-control",
+  open: "app-control",
+  "plugin:disable": "app-control",
+  "plugin:enable": "app-control",
+  "plugin:install": "app-control",
+  "plugin:reload": "app-control",
+  "plugin:uninstall": "app-control",
+  "plugins:restrict": "app-control",
+  random: "app-control",
+  reload: "app-control",
+  restart: "app-control",
+  "search:open": "app-control",
+  "snippet:disable": "app-control",
+  "snippet:enable": "app-control",
+  sync: "app-control",
+  "sync:open": "app-control",
+  "tab:open": "app-control",
+  "theme:install": "app-control",
+  "theme:set": "app-control",
+  "theme:uninstall": "app-control",
+  "dev:cdp": "app-control",
+  "dev:console": "app-control",
+  "dev:css": "app-control",
+  "dev:debug": "app-control",
+  "dev:dom": "app-control",
+  "dev:errors": "app-control",
+  "dev:mobile": "app-control",
+  "dev:screenshot": "app-control",
+  devtools: "app-control",
+  eval: "app-control"
+};
+function classifyCommand(name) {
+  return CLASSIFICATION[name] ?? "app-control";
+}
+// packages/obsidian-cli/src/help-parser.ts
+function parseOptionToken(token) {
+  const kv = /^([^\s=]+)=(.+)$/.exec(token);
+  if (kv) {
+    const name = kv[1] ?? "";
+    const hintRaw = kv[2] ?? "";
+    const quoted = /^"(.*)"$/.exec(hintRaw);
+    const valueHint = quoted ? quoted[1] ?? "" : hintRaw;
+    return { name, kind: "string", valueHint };
+  }
+  const positional = /^<(.+)>$/.exec(token);
+  if (positional) {
+    return { name: positional[1] ?? "", kind: "string", valueHint: token };
+  }
+  return { name: token, kind: "boolean" };
+}
+function splitRequired(rawDescription) {
+  const trimmed = rawDescription.trim();
+  const match = /^(.*?)\s*\(required\)\s*$/.exec(trimmed);
+  if (match) {
+    return { description: (match[1] ?? "").trim(), required: true };
+  }
+  return { description: trimmed, required: false };
+}
+function parseLabeledLine(trimmedLine, dashSeparated) {
+  const pattern = dashSeparated ? /^(\S+)\s+-\s+(.*)$/ : /^(\S+)\s{2,}(.*)$/;
+  const match = pattern.exec(trimmedLine);
+  if (!match)
+    return null;
+  return { token: match[1] ?? "", rest: match[2] ?? "" };
+}
+function parseHelp(helpText) {
+  const lines = helpText.split(/\r?\n/);
+  const globalOptions = [];
+  const commands = [];
+  let section = "none";
+  let current = null;
+  for (const rawLine of lines) {
+    if (rawLine.trim() === "")
+      continue;
+    const leading = rawLine.length - rawLine.trimStart().length;
+    const trimmed = rawLine.trim();
+    if (leading === 0) {
+      if (trimmed === "Options:")
+        section = "options";
+      else if (trimmed === "Notes:")
+        section = "notes";
+      else if (trimmed === "Commands:")
+        section = "commands";
+      else if (trimmed === "Developer:")
+        section = "commands";
+      else
+        section = "none";
+      current = null;
+      continue;
+    }
+    if (section === "options" && leading === 2) {
+      const parsed = parseLabeledLine(trimmed, false);
+      if (!parsed)
+        continue;
+      const { description, required } = splitRequired(parsed.rest);
+      globalOptions.push({ ...parseOptionToken(parsed.token), description, required });
+      continue;
+    }
+    if (section !== "commands")
+      continue;
+    if (leading === 2) {
+      const parsed = parseLabeledLine(trimmed, false);
+      if (!parsed)
+        continue;
+      const { description } = splitRequired(parsed.rest);
+      current = { name: parsed.token, description, options: [] };
+      commands.push(current);
+      continue;
+    }
+    if (leading >= 4 && current) {
+      const parsed = parseLabeledLine(trimmed, true);
+      if (!parsed)
+        continue;
+      const { description, required } = splitRequired(parsed.rest);
+      current.options.push({ ...parseOptionToken(parsed.token), description, required });
+    }
+  }
+  return { commands, globalOptions };
+}
+
+// packages/obsidian-cli/src/errors.ts
+class ObsidianNotFoundError extends Error {
+  binary;
+  constructor(binary, cause) {
+    super(`Obsidian CLI binary not found or not executable: ${binary}`);
+    this.name = "ObsidianNotFoundError";
+    this.binary = binary;
+    if (cause !== undefined)
+      this.cause = cause;
+  }
+}
+
+class ObsidianCommandError extends Error {
+  command;
+  argv;
+  exitCode;
+  stdout;
+  stderr;
+  constructor(command, argv, exitCode, stdout, stderr) {
+    const detail = (stderr.trim() || stdout.trim() || "no output").slice(0, 500);
+    super(`obsidian ${command} failed (exit ${exitCode}): ${detail}`);
+    this.name = "ObsidianCommandError";
+    this.command = command;
+    this.argv = argv;
+    this.exitCode = exitCode;
+    this.stdout = stdout;
+    this.stderr = stderr;
+  }
+}
+
+class ObsidianTimeoutError extends Error {
+  command;
+  timeoutMs;
+  constructor(command, timeoutMs) {
+    super(`obsidian ${command} timed out after ${timeoutMs}ms`);
+    this.name = "ObsidianTimeoutError";
+    this.command = command;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class UnknownCommandError extends Error {
+  command;
+  constructor(command) {
+    super(`Unknown obsidian command: ${command}`);
+    this.name = "UnknownCommandError";
+    this.command = command;
+  }
+}
+
+class UnknownOptionError extends Error {
+  command;
+  option;
+  constructor(command, option) {
+    super(`Unknown option "${option}" for command "${command}"`);
+    this.name = "UnknownOptionError";
+    this.command = command;
+    this.option = option;
+  }
+}
+
+class MissingRequiredOptionError extends Error {
+  command;
+  option;
+  constructor(command, option) {
+    super(`Missing required option "${option}" for command "${command}"`);
+    this.name = "MissingRequiredOptionError";
+    this.command = command;
+    this.option = option;
+  }
+}
+
+// packages/obsidian-cli/src/serialize.ts
+function escapeValue(value) {
+  return value.replace(/\n/g, "\\n").replace(/\t/g, "\\t");
+}
+function serializeOption(opt, value) {
+  if (typeof value === "boolean") {
+    return value ? opt.name : null;
+  }
+  const stringValue = typeof value === "number" ? String(value) : escapeValue(value);
+  if (opt.valueHint === `<${opt.name}>`) {
+    return stringValue;
+  }
+  return `${opt.name}=${stringValue}`;
+}
+function buildArgv(cmd, options = {}, opts = {}) {
+  const optionsByName = new Map(cmd.options.map((option) => [option.name, option]));
+  for (const key of Object.keys(options)) {
+    if (!optionsByName.has(key)) {
+      throw new UnknownOptionError(cmd.name, key);
+    }
+  }
+  for (const option of cmd.options) {
+    if (option.required && options[option.name] === undefined) {
+      throw new MissingRequiredOptionError(cmd.name, option.name);
+    }
+  }
+  const argv = [cmd.name];
+  if (opts.vault !== undefined) {
+    argv.push(`vault=${escapeValue(opts.vault)}`);
+  }
+  for (const [key, value] of Object.entries(options)) {
+    const option = optionsByName.get(key);
+    if (!option)
+      continue;
+    const serialized = serializeOption(option, value);
+    if (serialized !== null)
+      argv.push(serialized);
+  }
+  return argv;
+}
+
+// packages/obsidian-cli/src/client.ts
+var DEFAULT_BINARY = "obsidian";
+var DEFAULT_TIMEOUT_MS = 15000;
+var schemaCache = new Map;
+async function spawnObsidian(binary, argv, timeoutMs) {
+  let proc;
+  try {
+    proc = Bun.spawn([binary, ...argv], { stdout: "pipe", stderr: "pipe", stdin: "ignore" });
+  } catch (err) {
+    throw new ObsidianNotFoundError(binary, err);
+  }
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill();
+  }, timeoutMs);
+  let stdout;
+  let stderr;
+  let exitCode;
+  try {
+    [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+  const label = argv[0] ?? binary;
+  if (timedOut) {
+    throw new ObsidianTimeoutError(label, timeoutMs);
+  }
+  if (exitCode !== 0) {
+    throw new ObsidianCommandError(label, argv, exitCode, stdout, stderr);
+  }
+  if (stdout.trimStart().startsWith("Error:")) {
+    throw new ObsidianCommandError(label, argv, exitCode, stdout, stderr);
+  }
+  return { stdout, stderr, exitCode };
+}
+async function loadSchema(binary = DEFAULT_BINARY, opts = {}) {
+  if (!opts.fresh) {
+    const cached = schemaCache.get(binary);
+    if (cached)
+      return cached;
+  }
+  const { stdout } = await spawnObsidian(binary, ["help"], DEFAULT_TIMEOUT_MS);
+  const schema = parseHelp(stdout);
+  schemaCache.set(binary, schema);
+  return schema;
+}
+async function createObsidianClient(opts = {}) {
+  const binary = opts.binary ?? DEFAULT_BINARY;
+  const vault = opts.vault;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  let schema = await loadSchema(binary);
+  async function refreshSchema() {
+    schema = await loadSchema(binary, { fresh: true });
+    return schema;
+  }
+  async function run(command, options = {}) {
+    const cmd = schema.commands.find((candidate) => candidate.name === command);
+    if (!cmd)
+      throw new UnknownCommandError(command);
+    const argv = buildArgv(cmd, options, { vault });
+    return spawnObsidian(binary, argv, timeoutMs);
+  }
+  return {
+    binary,
+    vault,
+    get schema() {
+      return schema;
+    },
+    refreshSchema,
+    run
+  };
+}
+// packages/obsidian-cli/src/zod.ts
+import { z } from "zod";
+function zodForOption(option) {
+  const base = option.kind === "boolean" ? z.boolean() : z.string();
+  const described = option.description ? base.describe(option.description) : base;
+  return option.required ? described : described.optional();
+}
+function commandToZodShape(cmd) {
+  const shape = {};
+  for (const option of cmd.options) {
+    shape[option.name] = zodForOption(option);
+  }
+  return z.object(shape);
+}
+// apps/server/src/app.ts
+import { createMcpHonoApp } from "@modelcontextprotocol/hono";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/server";
+
+// apps/server/src/exposed-commands.ts
+function exposedCommands(commands, allowed) {
+  return commands.map((command) => ({ command, classification: classifyCommand(command.name) })).filter((entry) => allowed.has(entry.classification));
+}
+function countExposedByClassification(commands, allowed) {
+  const counts = { read: 0, write: 0, destructive: 0, "app-control": 0 };
+  for (const entry of exposedCommands(commands, allowed)) {
+    counts[entry.classification] += 1;
+  }
+  return counts;
+}
+
+// apps/server/src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import { z as z2 } from "zod";
+
+// apps/server/src/naming.ts
+function commandToToolName(command) {
+  return `obsidian_${command.replace(/:/g, "_")}`;
+}
+
+// apps/server/src/mcp.ts
+var SERVER_NAME = "obsidian-server";
+var SERVER_VERSION = "0.1.0";
+function buildMcpServer(options) {
+  const { client, allowed } = options;
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  const registered = new Set;
+  for (const { command, classification } of exposedCommands(client.schema.commands, allowed)) {
+    const toolName = commandToToolName(command.name);
+    if (registered.has(toolName)) {
+      console.warn(`skipping command "${command.name}": tool name ${toolName} already registered`);
+      continue;
+    }
+    registered.add(toolName);
+    const description = `${command.description} [${classification}]`;
+    const inputSchema = commandToZodShape(command);
+    server.registerTool(toolName, { title: command.name, description, inputSchema }, async (args) => {
+      try {
+        const result = await client.run(command.name, args);
+        return { content: [{ type: "text", text: result.stdout || "(empty)" }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: message }], isError: true };
+      }
+    });
+  }
+  server.registerTool("server_commands", {
+    title: "server_commands",
+    description: "List every obsidian command exposed by this server, with its classification and options.",
+    inputSchema: z2.object({})
+  }, async () => {
+    const commands = exposedCommands(client.schema.commands, allowed).map(({ command, classification }) => ({
+      name: command.name,
+      toolName: commandToToolName(command.name),
+      description: command.description,
+      classification,
+      options: command.options
+    }));
+    return {
+      content: [{ type: "text", text: JSON.stringify({ vault: client.vault, commands }, null, 2) }]
+    };
+  });
+  return server;
+}
+
+// apps/server/src/network.ts
+var LOCALHOST_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+function isLocalhostClass(host) {
+  return LOCALHOST_HOSTS.has(host);
+}
+function needsDnsRebindingWarning(host, allowedHosts) {
+  return !isLocalhostClass(host) && (!allowedHosts || allowedHosts.length === 0);
+}
+
+// apps/server/src/app.ts
+function isOptionValue(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+async function parseCommandBody(req) {
+  const raw = await req.text();
+  if (raw.trim().length === 0)
+    return { ok: true, body: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ok: false, error: "Invalid JSON body" };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, error: "Request body must be a JSON object of option values" };
+  }
+  const body = {};
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!isOptionValue(value)) {
+      return { ok: false, error: `Option "${key}" must be a string, number, or boolean` };
+    }
+    body[key] = value;
+  }
+  return { ok: true, body };
+}
+async function buildApp(options) {
+  const { client, auth, allowed } = options;
+  const warnings = [];
+  if (needsDnsRebindingWarning(options.host, options.allowedHosts)) {
+    warnings.push(`Binding to "${options.host}" without --allow-hosts/--allow-origins leaves DNS-rebinding protection ` + "disabled. Pass allowedHosts/allowedOrigins when binding beyond localhost.");
+  }
+  const app = createMcpHonoApp({
+    host: options.host,
+    allowedHosts: options.allowedHosts,
+    allowedOrigins: options.allowedOrigins
+  });
+  app.get("/health", async (c) => {
+    let reachable = true;
+    try {
+      await client.refreshSchema();
+    } catch {
+      reachable = false;
+    }
+    return c.json({ ok: true, obsidian: reachable, vault: client.vault ?? null });
+  });
+  const authMiddleware = requireAuth(auth);
+  app.use("/api/*", authMiddleware);
+  app.use("/mcp", authMiddleware);
+  app.get("/api/commands", (c) => {
+    const commands = exposedCommands(client.schema.commands, allowed).map(({ command, classification }) => ({
+      name: command.name,
+      description: command.description,
+      classification,
+      options: command.options
+    }));
+    return c.json({
+      total: client.schema.commands.length,
+      exposed: commands.length,
+      commands
+    });
+  });
+  app.post("/api/commands/:name", async (c) => {
+    const name = c.req.param("name");
+    const command = client.schema.commands.find((candidate) => candidate.name === name);
+    if (!command) {
+      return c.json({ ok: false, error: `Unknown obsidian command: ${name}` }, 404);
+    }
+    const classification = classifyCommand(name);
+    if (!allowed.has(classification)) {
+      return c.json({
+        ok: false,
+        error: `Command "${name}" is classified "${classification}" and is not exposed. Restart the server with --allow ${classification} to enable it.`
+      }, 403);
+    }
+    const parsedBody = await parseCommandBody(c.req.raw);
+    if (!parsedBody.ok) {
+      return c.json({ ok: false, error: parsedBody.error }, 400);
+    }
+    try {
+      const result = await client.run(name, parsedBody.body);
+      return c.json({ ok: true, stdout: result.stdout });
+    } catch (err) {
+      if (err instanceof UnknownCommandError) {
+        return c.json({ ok: false, error: err.message }, 404);
+      }
+      if (err instanceof UnknownOptionError || err instanceof MissingRequiredOptionError) {
+        return c.json({ ok: false, error: err.message }, 400);
+      }
+      if (err instanceof ObsidianTimeoutError) {
+        return c.json({ ok: false, error: err.message }, 504);
+      }
+      if (err instanceof ObsidianCommandError) {
+        return c.json({ ok: false, error: err.message }, 502);
+      }
+      throw err;
+    }
+  });
+  const mcpServer = buildMcpServer({ client, allowed });
+  const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  await mcpServer.connect(transport);
+  app.all("/mcp", async (c) => {
+    const user = c.get("user");
+    const apiKey2 = c.get("apiKey");
+    const authInfo = {
+      token: apiKey2?.id ?? "",
+      clientId: apiKey2?.id ?? "unknown",
+      scopes: [],
+      extra: { user, apiKey: apiKey2 }
+    };
+    return transport.handleRequest(c.req.raw, { parsedBody: c.get("parsedBody"), authInfo });
+  });
+  return { app, warnings };
+}
+
+// apps/server/src/banner.ts
+function restBaseUrl(host, port) {
+  return `http://${host}:${port}`;
+}
+function mcpUrl(host, port) {
+  return `${restBaseUrl(host, port)}/mcp`;
+}
+function renderMcpAddCommand(host, port, freshToken) {
+  const tokenPlaceholder = freshToken ?? "<token>";
+  return `claude mcp add --transport http obsidian ${mcpUrl(host, port)} --header "Authorization: Bearer ${tokenPlaceholder}"`;
+}
+var CLASSIFICATION_ORDER = [
+  "read",
+  "write",
+  "destructive",
+  "app-control"
+];
+function renderStartupBanner(input) {
+  const lines = [];
+  lines.push("obsidian-server is running");
+  lines.push(`  vault:        ${input.vault ?? "(active vault in the running Obsidian app)"}`);
+  lines.push(`  REST base:    ${restBaseUrl(input.host, input.port)}`);
+  lines.push(`  MCP endpoint: ${mcpUrl(input.host, input.port)}`);
+  lines.push("");
+  lines.push(`  commands exposed: ${input.totalExposed}/${input.totalCommands}`);
+  for (const classification of CLASSIFICATION_ORDER) {
+    const allowedMark = input.allowed.has(classification) ? "" : " (disabled - pass --allow " + classification + ")";
+    lines.push(`    ${classification}: ${input.exposedCounts[classification]}${allowedMark}`);
+  }
+  lines.push("");
+  if (input.freshToken) {
+    lines.push("  A new API key was minted (shown ONLY ONCE - copy it now):");
+    lines.push(`    ${input.freshToken}`);
+  } else {
+    lines.push("  Using an existing API key. Run `obsidian-server token mint --name <label>` for a new one.");
+  }
+  lines.push("");
+  lines.push("  Add this server to an MCP client:");
+  lines.push(`    ${renderMcpAddCommand(input.host, input.port, input.freshToken)}`);
+  return lines.join(`
+`);
+}
+
+// apps/server/src/paths.ts
+import { join } from "path";
+function resolveDataDir(env, override) {
+  if (override)
+    return override;
+  if (env.XDG_DATA_HOME)
+    return join(env.XDG_DATA_HOME, "obsidian-server");
+  if (!env.HOME) {
+    throw new Error("Cannot resolve a data directory: neither --data-dir, $XDG_DATA_HOME, nor $HOME is set.");
+  }
+  return join(env.HOME, ".local", "share", "obsidian-server");
+}
+
+// apps/server/src/serve.ts
+var OBSIDIAN_NOT_FOUND_HINT = "Could not run the `obsidian` CLI. Make sure the Obsidian desktop app is running and its CLI companion " + "is installed and on PATH (or pass --binary <path>). See https://obsidian.md for the CLI plugin/binary.";
+async function runServe(options) {
+  const dataDir = resolveDataDir(process.env, options.dataDir);
+  mkdirSync2(dataDir, { recursive: true });
+  const auth = createAuth({ dbPath: join2(dataDir, "auth.db"), baseURL: `http://${options.host}:${options.port}` });
+  await migrate(auth);
+  const ensured = await ensureOwnerAndKey(auth);
+  let client;
+  try {
+    client = await createObsidianClient({
+      binary: options.binary,
+      vault: options.vault,
+      timeoutMs: options.timeoutMs
+    });
+  } catch (err) {
+    if (err instanceof ObsidianNotFoundError) {
+      console.error(OBSIDIAN_NOT_FOUND_HINT);
+      process.exitCode = 1;
+      throw err;
+    }
+    throw err;
+  }
+  const allowed = computeAllowedClassifications(options.allow);
+  const { app, warnings } = await buildApp({
+    client,
+    auth,
+    allowed,
+    host: options.host,
+    allowedHosts: options.allowedHosts,
+    allowedOrigins: options.allowedOrigins
+  });
+  for (const warning of warnings)
+    console.warn(`warning: ${warning}`);
+  const banner = renderStartupBanner({
+    vault: client.vault,
+    host: options.host,
+    port: options.port,
+    allowed,
+    exposedCounts: countExposedByClassification(client.schema.commands, allowed),
+    totalExposed: exposedCommands(client.schema.commands, allowed).length,
+    totalCommands: client.schema.commands.length,
+    freshToken: ensured.created ? ensured.key : undefined
+  });
+  console.log(banner);
+  const server = Bun.serve({ fetch: app.fetch, port: options.port, hostname: options.host });
+  return { server, app, client, auth };
+}
+
+// apps/server/src/token.ts
+import { join as join3 } from "path";
+function authForDataDir(dataDir) {
+  const dir = resolveDataDir(process.env, dataDir);
+  return createAuth({ dbPath: join3(dir, "auth.db"), baseURL: "http://localhost" });
+}
+async function tokenMint(options) {
+  const auth = authForDataDir(options.dataDir);
+  await migrate(auth);
+  const owner = await bootstrap(auth);
+  const minted = await mintKey(auth, { name: options.name, expiresDays: options.expiresDays, userId: owner.id });
+  return { id: minted.id, key: minted.key, expiresAt: minted.expiresAt };
+}
+async function tokenList(options = {}) {
+  const auth = authForDataDir(options.dataDir);
+  await migrate(auth);
+  await bootstrap(auth);
+  return listKeys(auth);
+}
+async function tokenRevoke(options) {
+  const auth = authForDataDir(options.dataDir);
+  await migrate(auth);
+  const result = await revokeKey(auth, { id: options.id });
+  return { id: result.id };
+}
+function formatKeySummary(key) {
+  return [
+    `id=${key.id}`,
+    `name=${key.name ?? "(unnamed)"}`,
+    `enabled=${key.enabled}`,
+    `created=${key.createdAt.toISOString()}`,
+    `expires=${key.expiresAt ? key.expiresAt.toISOString() : "never"}`,
+    `lastUsed=${key.lastRequest ? key.lastRequest.toISOString() : "never"}`
+  ].join("\t");
+}
+
+// apps/server/src/version.ts
+var VERSION = "0.0.1";
+
+// apps/server/src/cli.ts
+var USAGE = [
+  "Usage: obsidian-server <command> [flags]",
+  "",
+  "Commands:",
+  "  serve [--vault <name>] [--port 3000] [--host 127.0.0.1]",
+  "        [--allow destructive] [--allow app-control]",
+  "        [--data-dir <path>] [--binary <path>] [--timeout-ms <n>]",
+  "    Start the MCP + REST server for a vault.",
+  "",
+  "  token mint --name <label> [--expires-days <n>] [--data-dir <path>]",
+  "    Mint a new API key (printed once).",
+  "  token list [--data-dir <path>]",
+  "    List API keys (no secrets).",
+  "  token revoke --id <id> [--data-dir <path>]",
+  "    Revoke (disable) an API key.",
+  "",
+  "  --version, -v       Print the obsidian-server version.",
+  "  --help, -h          Show this help."
+].join(`
+`);
+function printUsage(stream = "stderr") {
+  if (stream === "stdout")
+    console.log(USAGE);
+  else
+    console.error(USAGE);
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  if (command === "--version" || command === "-v") {
+    console.log(VERSION);
+    return;
+  }
+  if (command === "--help" || command === "-h" || command === "help") {
+    printUsage("stdout");
+    return;
+  }
+  if (command === "serve") {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        vault: { type: "string" },
+        port: { type: "string", default: "3000" },
+        host: { type: "string", default: "127.0.0.1" },
+        allow: { type: "string", multiple: true, default: [] },
+        "data-dir": { type: "string" },
+        binary: { type: "string" },
+        "timeout-ms": { type: "string" }
+      },
+      allowPositionals: false
+    });
+    const port = Number(values.port);
+    if (!Number.isInteger(port) || port < 0) {
+      console.error(`--port must be a non-negative integer, got "${values.port}"`);
+      process.exitCode = 1;
+      return;
+    }
+    let timeoutMs;
+    if (values["timeout-ms"] !== undefined) {
+      timeoutMs = Number(values["timeout-ms"]);
+      if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        console.error(`--timeout-ms must be a positive number, got "${values["timeout-ms"]}"`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    for (const flag of values.allow ?? []) {
+      if (!GATED_CLASSIFICATIONS.includes(flag)) {
+        console.error(`--allow must be one of: ${GATED_CLASSIFICATIONS.join(", ")} (got "${flag}")`);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    await runServe({
+      vault: values.vault,
+      port,
+      host: values.host ?? "127.0.0.1",
+      allow: values.allow ?? [],
+      dataDir: values["data-dir"],
+      binary: values.binary,
+      timeoutMs
+    });
+    return;
+  }
+  if (command === "token") {
+    const [action, ...tokenRest] = rest;
+    const { values } = parseArgs({
+      args: tokenRest,
+      options: {
+        name: { type: "string" },
+        "expires-days": { type: "string" },
+        "data-dir": { type: "string" },
+        id: { type: "string" }
+      },
+      allowPositionals: false
+    });
+    switch (action) {
+      case "mint": {
+        if (!values.name) {
+          console.error("token mint requires --name <label>");
+          process.exitCode = 1;
+          return;
+        }
+        const expiresDays = values["expires-days"] !== undefined ? Number(values["expires-days"]) : undefined;
+        if (expiresDays !== undefined && !Number.isFinite(expiresDays)) {
+          console.error("--expires-days must be a number");
+          process.exitCode = 1;
+          return;
+        }
+        const minted = await tokenMint({ name: values.name, expiresDays, dataDir: values["data-dir"] });
+        console.log("API key (shown once - it cannot be recovered later):");
+        console.log(minted.key);
+        console.log(`id: ${minted.id}`);
+        console.log(`expires: ${minted.expiresAt ? minted.expiresAt.toISOString() : "never"}`);
+        return;
+      }
+      case "list": {
+        const keys = await tokenList({ dataDir: values["data-dir"] });
+        if (keys.length === 0) {
+          console.log("No API keys.");
+          return;
+        }
+        for (const key of keys)
+          console.log(formatKeySummary(key));
+        return;
+      }
+      case "revoke": {
+        if (!values.id) {
+          console.error("token revoke requires --id <keyId>");
+          process.exitCode = 1;
+          return;
+        }
+        const revoked = await tokenRevoke({ id: values.id, dataDir: values["data-dir"] });
+        console.log(`Revoked key ${revoked.id}`);
+        return;
+      }
+      default: {
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+  }
+  printUsage();
+  process.exitCode = command ? 1 : 0;
+}
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nathanld/obsidian-server",
+  "version": "0.0.1",
+  "description": "Point any Obsidian vault at an MCP server + REST API with Bearer-token auth out of the box, backed by the official Obsidian CLI.",
+  "type": "module",
+  "bin": {
+    "obsidian-server": "cli.js"
+  },
+  "dependencies": {
+    "@better-auth/api-key": "1.6.23",
+    "@modelcontextprotocol/hono": "^2.0.0-beta.2",
+    "@modelcontextprotocol/server": "^2.0.0-beta.3",
+    "better-auth": "^1.6.23",
+    "hono": "^4.12.29",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nathanld/obsidian-server.git"
+  },
+  "homepage": "https://github.com/nathanld/obsidian-server#readme",
+  "bugs": {
+    "url": "https://github.com/nathanld/obsidian-server/issues"
+  },
+  "license": "MIT",
+  "keywords": [
+    "obsidian",
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "rest-api",
+    "cli",
+    "bun"
+  ],
+  "files": [
+    "cli.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}