# Obsidian Scoped-write MCP

访问指定 Obsidian Vault 的 MCP 服务。整个 Vault 可读取；创建和更新 Markdown 只允许两个 ChatGPT 专属目录：

- `00-ChatGPT系统入口`
- `01-ChatGPT策略主脑`

不提供删除、移动、重命名或非 Markdown 写入工具。

## 工具

- `list_directory`：列出目录。
- `read_markdown`：读取 Markdown。
- `search_markdown`：搜索 Markdown；单次最多扫描 1000 个 Markdown、读取 64 MiB，并最多返回 100 条匹配。
- `get_file_info`：查看大小、修改时间、SHA-256 和可写状态。
- `create_directory`：在允许目录内创建一级普通子文件夹；父目录必须已存在。
- `create_markdown`：在允许目录创建新文件，禁止覆盖。
- `update_markdown`：使用预期 SHA-256 更新已有文件，更新前在 Vault 外备份；同一服务进程内对同一文件串行更新。

## 本地验证

```powershell
npm ci
npm test
```

测试默认创建临时 Vault 和临时备份目录，不接触个人 Obsidian 数据。传入真实 Vault 路径时只运行读取测试，不执行写入。

## 安全边界

- 写入目录由服务器端固定白名单控制，工具参数不能扩大范围。
- 创建文件夹只允许一级操作；同名、隐藏目录、缺失父目录、越界和符号链接逃逸均拒绝。
- 创建目标已存在时拒绝。
- 更新前先调用 `get_file_info`，把返回的 `sha256` 作为 `expected_sha256`；检测到版本变化时会拒绝。同一 MCP 进程内的并发更新已串行化；Obsidian、同步软件等外部进程仍存在极小竞争窗口，因此这属于乐观并发保护，并非跨进程原子 CAS。
- 更新前备份到当前 Windows 用户的本地应用数据目录；备份不在 Vault 和 Git 仓库中。
- 绝对路径、越界路径、符号链接逃逸和非 Markdown 均被拒绝。

## 开发流程

- `main` 始终保持可发布。
- 所有仓库变更使用短生命周期分支和 Pull Request。
- CI 通过后才能合并，默认使用 squash merge。
- 架构、安全边界、数据格式、长期依赖或多个独立 PR 的大功能：父 Issue、Sub-issues、ADR、PR、CI 和回滚记录。
- 小补丁：单一 Issue 或 PR、最小改动、最小测试和回滚说明。

### 轻量补丁验收

- 验收：运行 `npm test`，并由 Pull Request 的 CI 检查通过后合并。
- 回滚：在 GitHub 上还原对应的 squash commit。