zhengchen.tao
6c0b9c66af
域名规划统一：MCP 服务子域名与 repo 名一致。 - obs.zhengchentao.win → obsidian-mcp.zhengchentao.win
101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# obsidian-mcp
|
|
|
|
Read and write an Obsidian vault via MCP (Model Context Protocol), with OAuth authentication via nas-auth.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Claude.ai / MCP client
|
|
│
|
|
│ ① GET /.well-known/oauth-authorization-server
|
|
│ ② OAuth Authorization Code + PKCE (via nas-auth)
|
|
│ ③ Bearer JWT (aud=obsidian, scope=read:obsidian | write:obsidian)
|
|
│
|
|
▼
|
|
obsidian-mcp.zhengchentao.win/mcp (this service, port 9090 → 8080)
|
|
│ JWT verify (HS256, shared key with nas-auth)
|
|
│ VaultPathResolver — chroot + blacklist
|
|
│ VaultWriteGuard — whitelist for writes
|
|
│
|
|
▼
|
|
/vault (Docker volume, backed by WebDAV share synced via Remotely Save)
|
|
```
|
|
|
|
## MCP Tools
|
|
|
|
| Tool | Auth required | Description |
|
|
|---|---|---|
|
|
| `list_vault_tree` | read:obsidian | Depth-limited directory tree of the vault |
|
|
| `list_files` | read:obsidian | Files and subdirs in a directory |
|
|
| `read_file` | read:obsidian | Read file content (UTF-8), with optional byte-range params |
|
|
| `search` | read:obsidian | Literal substring search, glob-filterable |
|
|
| `get_metadata` | read:obsidian | Size, modified_at, has_frontmatter |
|
|
| `write_file` | write:obsidian | Overwrite a whitelisted file |
|
|
| `append_file` | write:obsidian | Append to a whitelisted file |
|
|
|
|
## Configuration (environment variables)
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `Vault__Root` | `./test-vault` | Vault root directory inside the container |
|
|
| `Vault__Blacklist__0` | — | Extra blacklist path segments (01-Secret, .obsidian, .trash, .git are hardcoded) |
|
|
| `Vault__WriteWhitelist__0` | — | Extra writable path prefixes |
|
|
| `Jwt__Issuer` | `https://auth.zhengchentao.win` | Expected `iss` claim |
|
|
| `Jwt__Audience` | `obsidian` | Expected `aud` claim |
|
|
| `Jwt__SigningKey__Current` | **required** | HS256 signing key (share with nas-auth) |
|
|
| `Jwt__SigningKey__Previous` | — | Previous key during rotation |
|
|
| `Mcp__OAuthDiscovery__Issuer` | `https://auth.zhengchentao.win` | `/.well-known` issuer field |
|
|
| `AuditLog__Directory` | `/app/logs` | Directory for audit log files |
|
|
| `ASPNETCORE_ENVIRONMENT` | `Production` | Set to `Development` for verbose logs |
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
# 1. Create a test vault
|
|
mkdir -p test-vault/NAS test-vault/Coding
|
|
echo "# Test" > test-vault/NAS/test.md
|
|
|
|
# 2. Set a dev signing key
|
|
export Jwt__SigningKey__Current=dev-secret-key-at-least-32-chars-long
|
|
|
|
# 3. Run
|
|
dotnet run
|
|
|
|
# 4. Generate a test JWT (requires dotnet user-jwts)
|
|
dotnet user-jwts create \
|
|
--issuer https://auth.zhengchentao.win \
|
|
--audience obsidian \
|
|
--name tao \
|
|
--claim sub=tao \
|
|
--claim scope="read:obsidian write:obsidian"
|
|
|
|
# 5. Test with MCP Inspector
|
|
npx @modelcontextprotocol/inspector
|
|
# Transport: Streamable HTTP
|
|
# URL: http://localhost:5000/mcp
|
|
# Bearer Token: <paste JWT from step 4>
|
|
```
|
|
|
|
## Write whitelist
|
|
|
|
Write tools only accept paths matching (hardcoded, extendable via env):
|
|
|
|
- Prefix `02-ShengquGames/logs/`
|
|
- Prefix `Coding/`
|
|
- Exact `NAS/NAS 待办清单.md`
|
|
|
|
Always forbidden (any directory): `AGENTS.md`, `PROFILE.md`, `README.md`, `CLAUDE.md`, `01-Secret/`
|
|
|
|
## Running tests
|
|
|
|
```bash
|
|
cd obsidian-mcp.Tests
|
|
dotnet test
|
|
```
|
|
|
|
## Related docs
|
|
|
|
- [obsidian-mcp 设计](../Obsidian%20Vault/Zhengchen/Coding/obsidian-mcp/obsidian-mcp%20设计.md)
|
|
- [MCP 实现指南](../Obsidian%20Vault/Zhengchen/Coding/obsidian-mcp/MCP%20实现指南.md)
|
|
- [nas-auth 设计](../Obsidian%20Vault/Zhengchen/Coding/nas-auth/nas-auth%20设计.md)
|