# Obsidian MCP — hardened Codex integration

Obsidian Local REST API 5.2.0 的隐私安全发行版，包含原生 Streamable HTTP MCP 服务、可移植 Codex 插件清单和默认只读工具配置。它适合让 Codex 在本机检索、读取和理解 Obsidian Vault，同时把认证信息与 Vault 内容保留在用户设备中。

**English summary:** a privacy-sanitized, read-first Codex package for Obsidian Local REST API with MCP. The public repository contains source and configuration templates only—never a user's vault, API key, certificates or plugin `data.json`.

## 为什么需要这个发行版

上游插件提供成熟的 REST/MCP 能力。本仓库在固定上游版本之上增加公开部署所需的安全层：

- Codex 标准 `.codex-plugin/plugin.json` 与 `.mcp.json`；
- API key 仅通过 `OBSIDIAN_MCP_API_KEY` 注入；
- MCP 地址固定为 `127.0.0.1` 回环接口；
- 默认只开放 8 个读取、检索和结构查看工具；
- 不分发 `data.json`、证书、私钥、Vault 内容或用户路径；
- 删除自动发布/文档部署工作流，只保留只读权限 CI；
- 明确记录上游版本、commit、改动与许可证归属。

## 默认工具

| 工具 | 用途 |
| --- | --- |
| `vault_list` | 列出 Vault 路径 |
| `vault_read` | 读取文本笔记 |
| `vault_get_document_map` | 获取文档结构 |
| `active_file_get_path` | 获取当前文件路径 |
| `search_query` | 结构化搜索 |
| `search_simple` | 简单文本搜索 |
| `tag_list` | 列出标签 |
| `command_list` | 只读取可用命令列表 |

写入、移动、删除、命令执行、二进制上传和签名 URL 工具不在默认 allowlist。需要这些能力时，应逐项审查、由用户明确授权后再单独启用。

## 架构

```text
Codex / MCP client
       │  Bearer token from environment
       ▼
http://127.0.0.1:27123/mcp/
       │
       ▼
Obsidian desktop plugin
       │
       ├── authentication
       ├── vault path containment
       ├── MCP annotations
       └── Obsidian vault adapter
```

详见 [docs/architecture.md](docs/architecture.md)。

## 项目结构

```text
obsidian/
├── .codex-plugin/plugin.json  # Codex 插件元数据
├── .mcp.json                  # 不含密钥的回环 MCP 配置
├── skills/obsidian/SKILL.md   # 读取优先的使用规则
├── src/                       # 上游 TypeScript 插件源码
├── scripts/                   # 构建、文档与安装辅助脚本
├── docs/                      # API 与安全架构文档
├── manifest.json              # Obsidian 插件清单
├── package.json               # Node 22 构建与测试入口
└── LICENSE / NOTICE.md
```

## 环境要求

- Obsidian Desktop 1.13.1 或更新版本；
- Node.js 22；
- Codex 插件环境或其他支持 Streamable HTTP MCP 的客户端；
- Windows、macOS 或 Linux 本机环境。

## 构建与安装

```powershell
git clone https://github.com/ZNaiGaomu/obsidian.git
Set-Location .\obsidian
npm ci
npm run build
```

把 `main.js`、`manifest.json` 和 `styles.css` 放入目标 Vault 的：

```text
.obsidian/plugins/obsidian-local-rest-api/
```

Windows 用户也可以明确指定测试 Vault：

```powershell
pwsh -File .\scripts\install-codex-build.ps1 -VaultPath 'D:\Obsidian\DisposableVault'
```

脚本不会读取或写入 API key。启用插件后，在 Obsidian 设置中生成自己的 key，并把它放入当前用户环境，而不是项目文件：

```powershell
$env:OBSIDIAN_MCP_API_KEY='<your-own-key>'
```

不要把真实值写入 `.env.example`、`.mcp.json`、Codex 技能或 Git 提交。

## Codex 配置

仓库中的 `.mcp.json` 默认 `enabled: false`。完成以下检查后再启用：

1. Obsidian 插件版本为 `5.2.0-hardened.1`；
2. 服务仅监听 `127.0.0.1:27123`；
3. `OBSIDIAN_MCP_API_KEY` 已在本机设置；
4. 使用 disposable Vault 验证读取工具；
5. 确认没有额外写入工具被意外加入 allowlist。

## 测试

```powershell
npm ci
npm run lint
npm test
npm run typecheck
npm run build
```

本发行基线曾通过 822 项测试、TypeScript 类型检查、生产构建及零生产依赖漏洞审计。该记录描述固定源码快照，不替代下载者在自身 Node/Obsidian 环境中的复测。

## 上游与版本

- Upstream: `coddingtonbear/obsidian-local-rest-api`
- Tag: `5.2.0`
- Commit: `ca20f7d783c191e2ea8a3474b99de9f175e9f219`
- Hardened release: `5.2.0-hardened.1`

上游完整说明保存在 [docs/upstream-readme.md](docs/upstream-readme.md)。修改记录见 [CHANGELOG.md](CHANGELOG.md)。

## 安全与许可证

源码遵循上游 [MIT License](LICENSE)，归属说明见 [NOTICE.md](NOTICE.md)。安全报告和默认权限边界见 [SECURITY.md](SECURITY.md)。本项目不是 Obsidian 官方产品。