obsidian-vault-bridge 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 Strange Leo
+
+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.
+
+---
+
+本包依赖并打包分发 obsidian-mcp：
+https://github.com/StevenStavrakis/obsidian-mcp
+MIT License, Copyright (c) 2024 Steven Stavrakis
+上游的许可证条款同样适用于其自身代码。

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# obsidian-vault-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让 AI 助手读写你的 Obsidian 笔记库 —— **不用手填路径**，装好就能用。
+
+它是 [obsidian-mcp](https://github.com/StevenStavrakis/obsidian-mcp) 的启动适配层。
+真正的笔记读写能力全部来自上游；本包只解决一个问题：**库在哪**。
+
+## 为什么需要它
+
+`obsidian-mcp` 只接受命令行参数指定库：
+
+```
+obsidian-mcp serve --vault notes=/absolute/path/to/vault
+```
+
+它不读环境变量。而 MCP 连接器的表单只能把用户填的值注入 `env`，塞不进命令行参数。
+于是每个人库路径不同这件事，就卡死了开箱即用。
+
+本包负责：自动找到你机器上的 Obsidian 库 → 生成合法参数 → 启动上游，stdio 原样透传。
+
+## 库是怎么找的
+
+1. 环境变量 `OBSIDIAN_VAULT_PATH` 优先（多个库用 `;` 分隔）；
+2. 没设就读 Obsidian 自己的库注册表：
+   - Windows：`%APPDATA%\obsidian\obsidian.json`
+   - macOS：`~/Library/Application Support/obsidian/obsidian.json`
+   - Linux：`~/.config/obsidian/obsidian.json`
+
+只要你在 Obsidian 里打开过库，它就被登记在注册表里，本包能直接找到，一个字都不用填。
+
+## 用法
+
+作为 MCP server（由客户端拉起，不用手动跑）：
+
+```bash
+npx -y obsidian-vault-bridge
+```
+
+配置示例：
+
+```json
+{
+  "mcpServers": {
+    "obsidian": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "obsidian-vault-bridge"],
+      "runtime": { "type": "node", "version": "22" }
+    }
+  }
+}
+```
+
+显式指定库（可选）：
+
+```json
+"env": {
+  "OBSIDIAN_VAULT_PATH": "D:\\Obsidian-Vault",
+  "OBSIDIAN_VAULT_IDS": "notes"
+}
+```
+
+看诊断信息（会打印找到了哪些库，不启动服务）：
+
+```bash
+npx -y obsidian-vault-bridge --doctor
+```
+
+## 环境变量
+
+| 变量 | 说明 |
+| --- | --- |
+| `OBSIDIAN_VAULT_PATH` | 库绝对路径，多个用 `;` 分隔。不设则自动探测 |
+| `OBSIDIAN_VAULT_IDS` | 自定义库 id，逗号分隔，与上面一一对应。不设则按目录名自动生成 |
+
+## 能力与边界
+
+上游提供 12 个工具：列库、读笔记、新建、编辑、删除、移动、建目录、搜索、加标签、删标签、改标签、统一管理标签。
+
+- 直接读写 Markdown 文件，**不需要 Obsidian 保持运行**
+- 写操作带事务日志，删除默认进 `.obsidian-mcp/trash` 可恢复
+- 编辑可用 etag 做并发冲突检测
+
+## 许可
+
+本包：MIT，Copyright (c) 2026 Strange Leo。
+上游 `obsidian-mcp`：MIT，Copyright (c) 2024 Steven Stavrakis —— 见 LICENSE 末段。

package/bin/bridge.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// obsidian-vault-bridge —— 自动定位本机 Obsidian 库，再交给 obsidian-mcp 提供服务。
+//
+// 为什么需要这一层：obsidian-mcp 只接受 `--vault <id>=<绝对路径>` 命令行参数、不读环境变量，
+// 而 MCP 连接器的「用户自填」只能把值注入 env。所以本包负责定位库、拼出参数，
+// 然后把 stdio 原样透传给真正的 MCP 服务端。
+//
+// 上游实现与全部笔记读写能力来自 obsidian-mcp
+//   https://github.com/StevenStavrakis/obsidian-mcp  (MIT, Copyright (c) 2024 Steven Stavrakis)
+// 本包只是启动参数的适配层。
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+
+const log = (msg) => process.stderr.write(msg + '\n');
+
+// ---------- 定位 Obsidian 的库注册表 ----------
+function registryPath() {
+  const home = os.homedir();
+  if (process.platform === 'win32') {
+    const appdata = process.env.APPDATA || path.join(home, 'AppData', 'Roaming');
+    return path.join(appdata, 'obsidian', 'obsidian.json');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'obsidian', 'obsidian.json');
+  }
+  const xdg = process.env.XDG_CONFIG_HOME || path.join(home, '.config');
+  return path.join(xdg, 'obsidian', 'obsidian.json');
+}
+
+// 读注册表里登记过的库。Obsidian 打开过的库都会留在这里。
+function detectVaults() {
+  const rp = registryPath();
+  if (!fs.existsSync(rp)) return { file: rp, paths: [] };
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(rp, 'utf8').replace(/^\uFEFF/, ''));
+  } catch {
+    return { file: rp, paths: [] };
+  }
+  const paths = [];
+  for (const v of Object.values(parsed?.vaults || {})) {
+    if (v && typeof v.path === 'string') paths.push(v.path);
+  }
+  return { file: rp, paths: [...new Set(paths)] };
+}
+
+// ---------- 生成合法 vault id ----------
+// obsidian-mcp 要求：小写字母开头，只含小写字母、数字、下划线、连字符。
+function makeId(vaultPath, index, used) {
+  const base = path.basename(vaultPath.replace(/[\\/]+$/, '')) || 'vault';
+  let id = base.toLowerCase().replace(/[^a-z0-9_-]/g, '-').replace(/^-+|-+$/g, '');
+  if (!/^[a-z]/.test(id)) id = 'v' + id;
+  if (!id) id = 'vault';
+  let candidate = id;
+  let n = 2;
+  while (used.has(candidate)) candidate = id + '-' + n++;
+  used.add(candidate);
+  return candidate;
+}
+
+// ---------- 决定最终用哪些库 ----------
+function resolveVaults() {
+  const explicit = (process.env.OBSIDIAN_VAULT_PATH || '').trim();
+  const customIds = (process.env.OBSIDIAN_VAULT_IDS || '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+  let dirs;
+  if (explicit) {
+    dirs = explicit.split(';').map((s) => s.trim()).filter(Boolean);
+  } else {
+    dirs = detectVaults().paths;
+  }
+
+  const used = new Set();
+  return dirs.map((p, i) => {
+    const abs = path.resolve(p);
+    const id = customIds[i] || makeId(abs, i, used);
+    return { id, path: abs, exists: fs.existsSync(abs), hasObsidianDir: fs.existsSync(path.join(abs, '.obsidian')) };
+  });
+}
+
+// ---------- 入口 ----------
+const argv = process.argv.slice(2);
+const doctor = argv.includes('--doctor');
+const passthrough = argv.filter((a) => a !== '--doctor');
+
+const vaults = resolveVaults();
+
+if (doctor) {
+  const reg = detectVaults();
+  log('obsidian-vault-bridge 诊断');
+  log('  平台: ' + process.platform);
+  log('  注册表: ' + reg.file + (fs.existsSync(reg.file) ? '（存在）' : '（不存在）'));
+  log('  注册表内的库: ' + (reg.paths.length ? reg.paths.join(' , ') : '无'));
+  log('  最终使用的库:');
+  for (const v of vaults) {
+    log('    ' + v.id + ' = ' + v.path + (v.exists ? '' : '  [不存在]') + (v.hasObsidianDir ? '' : '  [缺少 .obsidian 目录]'));
+  }
+  if (!vaults.length) log('  -> 没找到任何库，请设置 OBSIDIAN_VAULT_PATH');
+  process.exit(vaults.length ? 0 : 1);
+}
+
+if (!vaults.length) {
+  log('obsidian-vault-bridge: 没找到 Obsidian 库。');
+  log('  请至少打开一次 Obsidian 让它登记库，或设置环境变量 OBSIDIAN_VAULT_PATH 指向库目录。');
+  log('  多个库用英文分号分隔，例如 OBSIDIAN_VAULT_PATH=D:\\MyVault;D:\\WorkVault');
+  process.exit(1);
+}
+
+for (const v of vaults) {
+  if (!v.exists) {
+    log('obsidian-vault-bridge: 库路径不存在 -> ' + v.path);
+    process.exit(1);
+  }
+  if (!v.hasObsidianDir) {
+    log('obsidian-vault-bridge: 该目录不是 Obsidian 库（缺少 .obsidian）-> ' + v.path);
+    process.exit(1);
+  }
+}
+
+let mainJs;
+try {
+  mainJs = require.resolve('obsidian-mcp');
+} catch {
+  log('obsidian-vault-bridge: 未能定位 obsidian-mcp，请重新安装本包。');
+  process.exit(1);
+}
+
+const args = [mainJs, 'serve', ...passthrough];
+for (const v of vaults) args.push('--vault', v.id + '=' + v.path);
+
+log('obsidian-vault-bridge: 启动 ' + vaults.map((v) => v.id + '=' + v.path).join(' , '));
+
+const child = spawn(process.execPath, args, { stdio: 'inherit' });
+child.on('error', (err) => {
+  log('obsidian-vault-bridge: 启动 obsidian-mcp 失败 -> ' + err.message);
+  process.exit(1);
+});
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "obsidian-vault-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "MCP bridge that auto-detects your Obsidian vaults and serves them to AI assistants",
+  "type": "module",
+  "bin": {
+    "obsidian-vault-bridge": "./bin/bridge.mjs"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "doctor": "node bin/bridge.mjs --doctor"
+  },
+  "dependencies": {
+    "obsidian-mcp": "^2.0.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "obsidian",
+    "mcp",
+    "model-context-protocol",
+    "vault",
+    "notes",
+    "pkm"
+  ],
+  "author": "Strange Leo <strangeyu911@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/strangeyu911-tech/obsidian-vault-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/strangeyu911-tech/obsidian-vault-bridge/issues"
+  },
+  "homepage": "https://github.com/strangeyu911-tech/obsidian-vault-bridge#readme"
+}