内容
# obsidian-tc
> Obsidian Turbocharged — 受控、代理就绪的库访问，适用于MCP。
[](https://www.gnu.org/licenses/agpl-3.0)
```bash
npm install -g obsidian-tc # Node >= 24 or Bun >= 1.1
```
同时作为Docker镜像（`ghcr.io/the-40-thieves/obsidian-tc`）、一键`.mcpb`包和独立二进制文件发布。
## 为什么存在
具有原始文件系统访问权限的AI代理可以对Obsidian库造成实际损害：覆盖多年的笔记、删除错误的文件夹、读取从未打算公开的日记或静默泄露`.obsidian/`中的插件API密钥。 大多数Obsidian MCP服务器提供给代理的访问权限仅受API密钥保护，而几乎没有任何其他限制。
obsidian-tc提供**受控**的访问权限。 所有工具调用 - 无例外 - 都通过一个调度管道：身份验证 → 范围 → 文件夹ACL → 只读开关 →幂等性 → 限流 → 人机确认 → 处理程序 → 响应监管 → 审计日志。 您可以决定代理可以读取、写入或删除哪些文件夹（每个库、每个调用者）；破坏性操作在人类批准之前会失败并关闭；每个调用都会被审计。
新来者？从 [5分钟快速入门](./docs/QUICKSTART.md) 或 [威胁模型和设计原理](./docs/WHY.md) 开始。
## 接口：3种工具，~105种受控功能
默认情况下，服务器会宣传 **三种元工具** 而不是一堆~105种：
- **`find_capability`** — 调用者可见的功能目录的BM25搜索（“如何移动笔记？”）
- **`describe_capability`** — 某个功能的结构、所需范围和安全提示
- **`call_capability`** — 调用命名功能；调用通过与直接调用相同的身份验证/范围/ACL/HITL/幂等性/限流管道，并由目标自身的结构验证参数
这使得代理上下文保持精简，同时完整的曲面 - 28个域中的105种工具 - 仍然可访问，并且每个工具仍然可以直接按名称调用。 `toolFacade.mode` 选择形状： `triad` （默认）， `domain` （~ dozen 域元工具，如 `notes` ， `search` ， `vault` ），或 `flat` （完整的广告曲面，即预曲面行为）。 外观仅限于边界：无论选择哪种模式，都不会绕过任何门。
## 它是什么
obsidian-tc是一个适用于 [Obsidian](https://obsidian.md) 的综合Model Context Protocol（MCP）服务器，适用于人类和自主代理。 多库原生。 可插拔嵌入。 与本地Ollama或云模型配合使用。
三个支柱：
1. **广泛。** 涵盖有意义的Obsidian操作的105种工具，包括原生库（`.base`）支持，带有真正的表达式DSL评估器 - 我们所知的最广泛的开源Obsidian MCP曲面（调查2026-07）。
2. **默认受控。** JWT身份验证（HS256或非对称RS256/ES256/EdDSA通过本地JWKS，带有`kid`轮换），文件夹ACL（每个库），只读开关，人机确认破坏性操作，写入比较和交换，幂等性密钥，大批量限流。
3. **从第一天起可观察。** OpenTelemetry跟踪，Prometheus指标，每个工具调用的结构化CloudEvents发射 - 所有可选导出流都软失败。
除了工具之外，服务器还将您的库公开为MCP **资源** （`resources/list` + `resources/read`，使用`obsidian-tc://<vault>/<path>` URIs，强制执行读取范围和文件夹ACL）和一组内置 **提示** （`prompts/list` + `prompts/get`）。
## 状态
✅ **已发布 - v1.3.4** （2026-07-03）。 发布到npm为源验证签名包，容器镜像位于 `ghcr.io/the-40-thieves/obsidian-tc:1.3.4` 。 曲面为 **28个域中的105种工具** ，默认通过上述三元组门面呈现。 v1.3.x新增功能（参见 [CHANGELOG](./CHANGELOG.md) ）：每个库的ACL，根ACL作为继承的默认设置，强制执行符号链接规范的ACL，笔记元数据表 + trigram FTS5搜索基质，索引写入范围覆盖每个笔记突变（磁盘扫描在FTS不可用时回退），vec0 KNN库推断，Obsidian库表达式DSL子集评估器与重新对齐的视图键，计算滥用预算（正则表达式工作超时，JSONLogic操作预算），周期性缓存维护扫描，单序列化调度， `server_health` 索引/ `notes_ready` / `fts_enabled` 报告和配置键同价，对称JWT通过本地JWKS，睡眠时间整合调度器和AGPL-3.0重新许可。
| 里程碑 | 范围 | 状态 |
|---|---|---|
| M0 | 行走骨架：调度管道，文件夹ACL，人机确认，迁移 | ✅ 已合并 |
| M1 | 核心库访问 - 30种工具（CRUD，frontmatter，标签，链接） | ✅ 已合并 |
| M2 | 搜索 + 嵌入 - 6种工具 +检索基质 | ✅ 已合并 |
| M3 | 结构化格式 - 23种工具（库，Canvas，周期性，附件，书签，工作区） | ✅ 已合并 |
| M4 | 插件桥 + 配套插件 - 20种工具，跨9个域 | ✅ 已合并 |
| M5 | 内存 + 捕获基质 - 15种工具（捕获队列，内存实体 + `[[link]]` 图，工作区会话 + JSONL跟踪，多读代理） | ✅ 已合并 |
| M6 | 批量 + 管理 + URI - 7种工具 | ✅ 已合并 |
| M7 | 硬化和发布：OpenTelemetry跟踪，Prometheus `/metrics`，CloudEvents队列，速率限制器，8三元组原生预构建，发布工作流 | ✅ 已发布（v1.0.2） |
该存储库在 [`The-40-Thieves`](https://github.com/The-40-Thieves) 下公开，许可为AGPL-3.0。
## 架构
多语言单体仓库:
| 包 | 语言 | 目的 |
|---|---|---|
| `packages/server` | TypeScript (Bun) | MCP协议层，身份验证，路由，工具实现，插件桥 |
| `packages/plugin` | TypeScript | 配套Obsidian插件，扩展本地REST API |
| `packages/shared` | TypeScript | 共享Zod模式和类型 |
| `packages/native` | Rust (via napi-rs) | 可选加速，数值相同的纯JS回退 - 参见下文 |
**原生模块实际生效的地方：** 原生模块的主要优势在于**余弦相似度**在暴力向量路径上（当捆绑的`sqlite-vec`扩展无法加载时使用）。 原生代币 + BM25记分器为**回退**词汇排名器（用于亚三元查询或FTS索引丢失/不健康时使用的详尽磁盘扫描）和`find_capability`目录搜索 - `search_text`的主要词汇排名是SQLite FTS5自己的`bm25()`，基于三元组的`notes_fts`索引。 所有功能无需预构建即可使用；原生模块使某些冷路径更快。
obsidian-tc是**融合内存引擎**：库读写，搜索和控制，以及折叠的检索智能：GraphRAG图遍历通过`vault_graph_search`（矢量种子+维基链接扩展，与RRF融合），FTS5 BM25文本搜索和密集矢量搜索作为单独的检索模式，网关可选重排序和`knowledge_challenge`决策红队。 RRF融合GraphRAG的种子/扩展流 - 目前尚没有通用的BM25+矢量混合检索器用于库搜索（`search_vault`自动运行文本，然后在零命中时运行语义，跟踪为THE-196）；GraphRAG边目前是单个库（THE-233）。 环境整合（每周综合+决策审计）在推理网关配置时在睡眠时间平面运行；GraphRAG船闸评估（召回@10 vs 基线）仍需要对活动嵌入后端进行单独运行 - 机械设备存在且已安排，标题检索数字待定（THE-296）。 这取代了早期的“访问MCP，检索范围外”框架（2026-06-25单一融合产品决策；参见`ARCHITECTURE.md`）。 预留的“V2 ML侧车”（以及原生`kmeansAssign` / `actrDecayScore`钩子）已被删除；类型原子MemIR基质是下游引擎构建阶段，而不是此v1.x线。
## 快速入门
完整演练（Claude Desktop / Claude Code布线，首次查询，受控写入）： [docs/QUICKSTART.md](./docs/QUICKSTART.md)。
安装，然后将obsidian-tc指向JSON配置文件 - 库`id`和`path`是最小的（其他每个字段都有默认值）：
```bash
npm install -g obsidian-tc
```
obsidian-tc在 **Node (>= 24)** 或 **[Bun](https://bun.sh) (>= 1.1)** 上运行 - `npm` / `npx`安装程序在Node下运行（使用`better-sqlite3`，回退到内置`node:sqlite`）；在Bun下使用`bun:sqlite`。 运行时会自动检测，因此相同的安装程序无论哪种方式都有效。
最快的启动方式是零配置：将它指向一个库文件夹，它将启动一个名为`main`的库，并具有合理的默认值。
```bash
obsidian-tc /path/to/your/vault
```
对于多库，身份验证，ACL或自定义嵌入，请传递配置文件：
`obsidian-tc.config.json`:
```json
{
"vaults": [{ "id": "main", "path": "/path/to/your/vault" }]
}
```
```bash
obsidian-tc ./obsidian-tc.config.json
# 或在环境中设置路径：
OBSIDIAN_TC_CONFIG=./obsidian-tc.config.json obsidian-tc
# 检查有效配置（机密被遮蔽），或打印版本：
obsidian-tc config show ./obsidian-tc.config.json
obsidian-tc version
# 将配套Obsidian插件安装到您的库中（然后在Obsidian中启用它）：
obsidian-tc plugin install --vault /path/to/your/vault
```
### 默认情况下在本地运行
不需要云账户或API密钥。 默认情况下，所有内容都在您的机器上运行：通过本地 [Ollama](https://ollama.com) 模型（`nomic-embed-text`，768-dim）进行嵌入，通过捆绑的`sqlite-vec`进行矢量搜索（带有纯JS余弦回退），以及每个库的SQLite缓存。 拉取模型一次，然后启动：
```bash
ollama pull nomic-embed-text # 默认嵌入模型
obsidian-tc /path/to/your/vault # 启动本地，仅需配置文件
```
可选推理网关（`OBSIDIAN_TC_GATEWAY_URL`）支持重新排序和`knowledge_challenge`红队；如果不设置，则会降低但仍然有效，而其他功能保持正常工作。 云嵌入提供商（OpenAI，Voyage，Cohere）通过配置文件按需选择。
## 在Cursor / VS Code中安装
一键安装（通过`npx`启动；安装后，设置配置文件路径到您自己的obsidian-tc JSON配置文件）：
[](cursor://anysphere.cursor-deeplink/mcp/install?name=obsidian-tc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm9ic2lkaWFuLXRjIl0sImVudiI6eyJPQlNJRElBTl9UQ19DT05GSUciOiIvQUJTT0xVVEUvUEFUSC9UTy9vYnNpZGlhbi10Yy5jb25maWcuanNvbiJ9fQ==)
[](vscode:mcp/install?%7B%22name%22%3A%22obsidian-tc%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22obsidian-tc%22%5D%2C%22env%22%3A%7B%22OBSIDIAN_TC_CONFIG%22%3A%22%2FABSOLUTE%2FPATH%2FTO%2Fobsidian-tc.config.json%22%7D%7D)
或手动添加。 服务器对象相同；仅包装器密钥不同 - Cursor（`~/.cursor/mcp.json`）使用`mcpServers`，VS Code（`.vscode/mcp.json`）使用`servers`：
```json
{
"mcpServers": {
"obsidian-tc": {
"command": "npx",
"args": ["-y", "obsidian-tc"],
"env": { "OBSIDIAN_TC_CONFIG": "/ABSOLUTE/PATH/TO/obsidian-tc.config.json" }
}
}
}
```
`OBSIDIAN_TC_CONFIG`是obsidian-tc JSON配置（库，ACL，传输）的绝对路径；它也可以作为第一个CLI参数传递。 还提供了一个预构建的MCPB包（`bun run bundle` → `dist/obsidian-tc.mcpb`），用于在Claude Desktop和其他MCPB主机上一键安装。
## 比较
大多数Obsidian MCP服务器是本地REST API上的薄访问包装器。 obsidian-tc是一个服务器级产品：一个集中式调度管道（身份验证 -> 范围 -> 文件夹ACL -> 只读 -> 幂等性 -> 限流 -> 人机确认 -> 处理程序 -> 响应监管 -> 审计），混合检索基质和可观察性。 粗略比较开源服务器（工具数量和功能截至2026-07 - 这些项目会变动；请查看他们的存储库）：
| | 工具 | 搜索 | 身份验证/ACL/HITL | 可观察性 |
|---|---|---|---|---|
| **obsidian-tc** | ~105（3工具门面） | FTS5 BM25 · 矢量（vec0）· GraphRAG RRF | JWT（HS256/JWKS）+ 每库文件夹ACL + HITL引发 | OTel + Prometheus + CloudEvents |
| [cyanheads/obsidian-mcp-server](https://github.com/cyanheads/obsidian-mcp-server) | ~14 | 文本/正则 | JWT/OAuth + 文件夹范围路径 + 只读模式 + HITL；MCP 2025-11-25分页 | 控制台日志 |
| [MarkusPfundstein/mcp-obsidian](https://github.com/MarkusPfundstein/mcp-obsidian) | ~13 | 文本 + JsonLogic / DQL | 本地REST API密钥 | 控制台日志 |
| [StevenStavrakis/obsidian-mcp](https://github.com/StevenStavrakis/obsidian-mcp) | ~11 | 文本 | 路径验证，无身份验证层 | 控制台日志 |
obsidian-tc的进一步扩展：具有每库ACL的多库进程内，一个混合词汇+矢量+图检索，写入比较和交换以及幂等性，每个调用的审计轨迹和生产可观察性。 社区服务器赢得：占用空间和简单性 - 参见下一节。
## 何时不使用obsidian-tc
诚实的指导 - obsidian-tc故意是一个较重的产品：
- **您想要尽可能小的占用空间。** 单个受信任的人通过聊天客户端驱动一个库，对于上面的简单社区服务器来说，治理管道的收益大多只在自主或多代理访问时才有意义。
- **您只需要读取访问权限。** 只读包装器（或cyanheads的只读模式）对于类似的安全结果来说，类似的机制更少。
- **您希望所有内容都在Obsidian内。** obsidian-tc是一个独立的服务器，而不是Obsidian插件 - 可选的配套插件仅桥接插件特定功能。 如果您从不离开应用程序，社区插件可能是您需要的全部。
- **您根本不需要MCP。** Obsidian URI或本地REST API插件可以涵盖简单的直接脚本编写。
从另一个方向迁移 - 将现有的Obsidian MCP设置替换为obsidian-tc - 涵盖在 [docs/CUTOVER.md](./docs/CUTOVER.md)。
## 文档
- [docs/QUICKSTART.md](./docs/QUICKSTART.md) - 安装到5分钟内的受控写入
- [docs/WHY.md](./docs/WHY.md) - 威胁模型、什么是治理意味着什么，什么不是obsidian-tc
- [docs/COHERENCE.md](./docs/COHERENCE.md) - 写作时Obsidian是打开的：一致性契约
- [docs/CUTOVER.md](./docs/CUTOVER.md) - 从另一个Obsidian MCP服务器迁移
- [ARCHITECTURE.md](./ARCHITECTURE.md) - 调度管道和包布局
- [SECURITY.md](./docs/SECURITY.md) - 威胁模型、保护措施、报告
## 商標
obsidian-tc是一个独立的、社区建设的开源项目。 它不是由Obsidian或其制造商Dynalist Inc. 赞助、认可或支持的。 “Obsidian”是一个商标，由Dynalist Inc. 拥有；它在这里仅用于描述此MCP服务器互操作的应用程序 - 包括包、图像和插件名称，它们表示兼容性，而不是源或认可。 有关官方应用程序，请访问 [obsidian.md](https://obsidian.md)。
## 许可
GNU Affero通用公共许可证v3.0（AGPL-3.0-only）。 参见 [LICENSE](./LICENSE)。 商业例外许可证也可能适用于无法满足AGPL的网络互惠条款的使用情况 - 请开启 [讨论](https://github.com/The-40-Thieves/obsidian-tc/discussions) 进行查询。 贡献者根据 [开发者确认书](https://developercertificate.org/) 接受贡献； 参见 [CONTRIBUTING.md](./CONTRIBUTING.md#license-and-sign-off-dco) 了解如何签署提交。
## 贡献
参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 所有贡献者同意 [行为准则](./CODE_OF_CONDUCT.md)。
有关安全问题，请参见 [SECURITY.md](./SECURITY.md)。
