obsidian-mcp: 初次落地 Obsidian Vault MCP Server (.NET 10, read+write)

把 Obsidian vault 通过 MCP 暴露给 Claude.ai，OAuth 走 nas-auth。
设计文档见 vault Coding/obsidian-mcp/obsidian-mcp 设计.md。
代码层落地参考 vault Coding/obsidian-mcp/MCP 实现指南.md。

V1+V2 同时实现（用户要求跳过分阶段直接全部）：

读 Tools（需 scope=read:obsidian）：
- list_vault_tree（一次性 vault 地图，限制深度）
- list_files / read_file（含 offset/limit 大文件分页）
- search（子串匹配 + glob 过滤，最多 50 hits）
- get_metadata（size / modified_at / has_frontmatter）

写 Tools（需 scope=write:obsidian）：
- write_file / append_file
- 多重门禁：scope 校验 + 路径黑名单 + 写入白名单 + 永禁文件
  - 永禁写：任意目录的 AGENTS.md / PROFILE.md / README.md / CLAUDE.md / 01-Secret/**
  - 白名单：02-ShengquGames/logs/ + Coding/ + NAS/NAS 待办清单.md
- 写入审计日志按天 rotate（JSON line）

安全：
- VaultPathResolver chroot：path traversal + symlink 双拒绝
- JwtBearer (HS256, Current+Previous fallback, MapInboundClaims=false)
- aud=obsidian, iss=https://auth.zhengchentao.win
- 黑名单：01-Secret / .obsidian / .trash / .git

技术栈：
- .NET 10 + ModelContextProtocol SDK 1.0
- Streamable HTTP transport (POST /mcp)
- JwtBearer 10.0 + IdentityModel.Tokens 8.x

部署：
- Dockerfile multi-stage，runtime 装 ripgrep（V3 备用），non-root user
- .gitea/workflows/build-image.yml：build + deploy 双 job，buildkit v0.13.2
- 容器内 :8080，宿主端口 9090
- 子域名 obs.zhengchentao.win
- vault 挂载 /volume1/docker/webdav/data/Zhengchen:/vault:rw（V2 写入需要 rw）

测试：35/35 单测过（VaultPathResolver path traversal/blacklist/symlink + VaultWriteGuard whitelist/forbidden）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,15 @@
+**/.git
+**/.gitignore
+**/.gitea
+**/bin
+**/obj
+**/*.user
+**/.vs
+**/.vscode
+**/.idea
+**/test-vault
+obsidian-mcp.Tests/
+.dockerignore
+README.md
+*.md
+LICENSE

.gitea/workflows/build-image.yml

@@ -0,0 +1,131 @@
+name: Build Docker Image
+
+on:
+  # 自动触发：push 到 main 分支（纯文档改动跳过）
+  # ⚠️ quirk：git commit --allow-empty 不触发 paths-ignore 过滤的 workflow，
+  # 要强制重新触发必须改一个非 ignore 路径的真实文件（改 build-image.yml 自己最稳）
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.gitignore'
+      - '.dockerignore'
+  # 手动触发：应急通道（重新打包 / 指定自定义 tag）
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: '要打包的分支（仅手动触发生效）'
+        required: true
+        default: 'main'
+      tag:
+        description: '镜像 tag（留空则用 commit short hash）'
+        required: false
+        default: ''
+
+# 同分支连续 push 只跑最新的 run，旧 in-progress run 被取消（build + deploy 一起停）
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout target branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.branch || github.ref_name }}
+          fetch-depth: 0
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          # 钉 v0.13.2（runc 1.1.x）避免 DSM 4.4.x 内核不支持 runc 1.2+ 的
+          # openat2/fsmount syscall 导致 build 失败
+          driver-opts: |
+            image=moby/buildkit:v0.13.2
+
+      - name: Login to Gitea Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.zhengchentao.win
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.PACKAGES_TOKEN }}
+
+      - name: Determine image tag and revision
+        id: meta
+        run: |
+          if [ -n "${{ inputs.tag }}" ]; then
+            IMAGE_TAG="${{ inputs.tag }}"
+          else
+            IMAGE_TAG="$(git rev-parse --short HEAD)"
+          fi
+          echo "image_tag=$IMAGE_TAG" >> $GITHUB_OUTPUT
+          echo "full_sha=$(git rev-parse HEAD)" >> $GITHUB_OUTPUT
+          echo "==> Image tag: $IMAGE_TAG"
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          labels: |
+            org.opencontainers.image.source=https://git.zhengchentao.win/zhengchen.tao/obsidian-mcp
+            org.opencontainers.image.revision=${{ steps.meta.outputs.full_sha }}
+          tags: |
+            git.zhengchentao.win/zhengchen.tao/obsidian-mcp:${{ steps.meta.outputs.image_tag }}
+            git.zhengchentao.win/zhengchen.tao/obsidian-mcp:latest
+
+      - name: Build summary
+        if: always()
+        run: |
+          {
+            echo "## Build Summary"
+            echo ""
+            echo "| 项 | 值 |"
+            echo "|---|---|"
+            echo "| 触发方式 | \`${{ github.event_name }}\` |"
+            echo "| 源分支 | \`${{ inputs.branch || github.ref_name }}\` |"
+            echo "| 源 commit (full) | \`${{ steps.meta.outputs.full_sha }}\` |"
+            echo "| 源 commit (short) | \`${{ steps.meta.outputs.image_tag }}\` |"
+            echo "| 镜像 | \`git.zhengchentao.win/zhengchen.tao/obsidian-mcp:${{ steps.meta.outputs.image_tag }}\` + \`:latest\` |"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  deploy:
+    # needs: build 串起来 —— build 失败则 deploy 自动 skip，无需 if 条件
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      # deploy job 跑在独立 runner 容器上，凭据不从 build job 继承，必须再登一次
+      - name: Login to Gitea Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: git.zhengchentao.win
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.PACKAGES_TOKEN }}
+
+      - name: Pull and restart obsidian-mcp
+        env:
+          NAS_INFRA_TOKEN: ${{ secrets.NAS_INFRA_TOKEN }}
+        run: |
+          set -e
+
+          TMPDIR=$(mktemp -d)
+          trap 'rm -rf "$TMPDIR"' EXIT
+
+          if [ -n "$NAS_INFRA_TOKEN" ]; then
+            CLONE_URL="https://x-access-token:${NAS_INFRA_TOKEN}@git.zhengchentao.win/dev/nas-infra.git"
+          else
+            CLONE_URL="https://git.zhengchentao.win/dev/nas-infra.git"
+          fi
+
+          git clone --depth 1 "$CLONE_URL" "$TMPDIR/nas-infra"
+          cd "$TMPDIR/nas-infra/obsidian-mcp"
+
+          docker compose pull
+          docker compose up -d
+
+          sleep 3
+          docker compose ps
+          docker compose logs --tail=30 obsidian-mcp

.gitignore

@@ -0,0 +1,23 @@
+## .NET
+bin/
+obj/
+*.user
+*.suo
+.vs/
+.vscode/
+
+## 本地测试 vault（不入库）
+test-vault/
+
+## 运行时产物
+/app/logs/
+*.log
+
+## 开发期 JWT（dotnet user-jwts 签的，不入库）
+.jwt/
+
+## 环境变量文件（密钥不入库）
+.env
+.env.local
+appsettings.*.local.json
+secrets.json

Auth/JwtBearerSetup.cs

@@ -0,0 +1,62 @@
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.IdentityModel.Tokens;
+using ObsidianMcp.Config;
+using System.Text;
+
+namespace ObsidianMcp.Auth;
+
+public static class JwtBearerSetup
+{
+    /// <summary>
+    /// 配置 HS256 JWT Bearer 认证。
+    /// 支持 Current + Previous 双密钥，方便密钥轮换过渡期。
+    /// </summary>
+    public static IServiceCollection AddObsidianJwtBearer(
+        this IServiceCollection services,
+        JwtOptions opts)
+    {
+        services
+            .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+            .AddJwtBearer(options =>
+            {
+                // 关闭默认的入站 claim type 映射，否则 "sub"/"scope" 会被改写成
+                // ClaimTypes.NameIdentifier 之类的长 URI，下游 FindFirst("sub") 取不到。
+                options.MapInboundClaims = false;
+
+                options.TokenValidationParameters = new TokenValidationParameters
+                {
+                    ValidateIssuer = true,
+                    ValidIssuer = opts.Issuer,
+
+                    ValidateAudience = true,
+                    ValidAudience = opts.Audience,
+
+                    ValidateIssuerSigningKey = true,
+                    // Current 必须有值；Previous 可选（密钥轮换过渡期）。
+                    // ToList 物化一次，避免每次验签都重建 SymmetricSecurityKey。
+                    IssuerSigningKeys = BuildSigningKeys(opts).ToList(),
+
+                    ValidateLifetime = true,
+                    ClockSkew = TimeSpan.FromMinutes(2),
+
+                    // scope claim 的 claim type 直接保持原样，User.FindAll("scope") 能取到。
+                    NameClaimType = "sub",
+                };
+            });
+
+        return services;
+    }
+
+    private static IEnumerable<SecurityKey> BuildSigningKeys(JwtOptions opts)
+    {
+        if (string.IsNullOrWhiteSpace(opts.SigningKey.Current))
+            throw new InvalidOperationException("Jwt:SigningKey:Current 未配置，服务无法启动。");
+
+        yield return new SymmetricSecurityKey(
+            Encoding.UTF8.GetBytes(opts.SigningKey.Current));
+
+        if (!string.IsNullOrWhiteSpace(opts.SigningKey.Previous))
+            yield return new SymmetricSecurityKey(
+                Encoding.UTF8.GetBytes(opts.SigningKey.Previous));
+    }
+}

Auth/ScopePolicies.cs

@@ -0,0 +1,85 @@
+using Microsoft.AspNetCore.Authorization;
+
+namespace ObsidianMcp.Auth;
+
+/// <summary>
+/// 自定义 scope 校验 Policy：
+///   RequireScope("read:obsidian")
+///   RequireScope("write:obsidian")
+///
+/// JWT 的 scope claim 可能是单个字符串（空格分隔）或多个 claim，两种都处理。
+/// </summary>
+public static class ScopePolicies
+{
+    public const string ReadObsidian = "read:obsidian";
+    public const string WriteObsidian = "write:obsidian";
+
+    /// <summary>注册两条 scope policy 到 AuthorizationOptions。</summary>
+    public static void AddScopePolicies(this AuthorizationOptions opts)
+    {
+        opts.AddPolicy(ReadObsidian, policy =>
+            policy.RequireAuthenticatedUser()
+                  .AddRequirements(new ScopeRequirement(ReadObsidian)));
+
+        opts.AddPolicy(WriteObsidian, policy =>
+            policy.RequireAuthenticatedUser()
+                  .AddRequirements(new ScopeRequirement(WriteObsidian)));
+    }
+}
+
+// ---------- Requirement ----------
+
+public class ScopeRequirement(string scope) : IAuthorizationRequirement
+{
+    public string RequiredScope { get; } = scope;
+}
+
+// ---------- Handler ----------
+
+public class ScopeAuthorizationHandler : AuthorizationHandler<ScopeRequirement>
+{
+    protected override Task HandleRequirementAsync(
+        AuthorizationHandlerContext context,
+        ScopeRequirement requirement)
+    {
+        // scope claim 在 JWT 里可能是一整个空格分隔的字符串，也可能是多个 claim。
+        // OAuth 2.0 (RFC 6749) 规定 scope 大小写敏感，按 Ordinal 比对。
+        var scopes = context.User
+            .FindAll("scope")
+            .SelectMany(c => c.Value.Split(' ', StringSplitOptions.RemoveEmptyEntries))
+            .ToHashSet(StringComparer.Ordinal);
+
+        if (scopes.Contains(requirement.RequiredScope))
+            context.Succeed(requirement);
+
+        return Task.CompletedTask;
+    }
+}
+
+// ---------- Per-tool scope guard helper ----------
+
+/// <summary>
+/// MCP Tool 内部 scope 校验：从当前 HttpContext.User 读 scope claim，
+/// 不包含 requiredScope 时抛 UnauthorizedAccessException。
+///
+/// 用法：在每个读 / 写 Tool 的方法体首行调一下，给客户端可读的失败原因。
+/// 端点级 RequireAuthorization 只确保 JWT 验签通过；scope 颗粒度门禁在这里。
+/// OAuth 2.0 (RFC 6749) 规定 scope 大小写敏感。
+/// </summary>
+public static class ToolScopeGuard
+{
+    public static void EnsureScope(IHttpContextAccessor http, string requiredScope)
+    {
+        var ctx = http.HttpContext
+            ?? throw new InvalidOperationException("无 HttpContext，无法校验 scope。");
+
+        var scopes = ctx.User
+            .FindAll("scope")
+            .SelectMany(c => c.Value.Split(' ', StringSplitOptions.RemoveEmptyEntries))
+            .ToHashSet(StringComparer.Ordinal);
+
+        if (!scopes.Contains(requiredScope))
+            throw new UnauthorizedAccessException(
+                $"当前 Token 缺少所需 scope：{requiredScope}");
+    }
+}

Config/JwtOptions.cs

@@ -0,0 +1,27 @@
+namespace ObsidianMcp.Config;
+
+/// <summary>
+/// JWT 验签配置。
+/// 环境变量：Jwt__Issuer, Jwt__Audience, Jwt__SigningKey__Current, Jwt__SigningKey__Previous
+/// </summary>
+public class JwtOptions
+{
+    public const string Section = "Jwt";
+
+    /// <summary>期望的 iss claim，生产：https://auth.zhengchentao.win</summary>
+    public string Issuer { get; set; } = "https://auth.zhengchentao.win";
+
+    /// <summary>期望的 aud claim，生产：obsidian</summary>
+    public string Audience { get; set; } = "obsidian";
+
+    public SigningKeyPair SigningKey { get; set; } = new();
+
+    public class SigningKeyPair
+    {
+        /// <summary>当前签名密钥（HS256 对称密钥），env: Jwt__SigningKey__Current</summary>
+        public string Current { get; set; } = string.Empty;
+
+        /// <summary>上一轮密钥，密钥轮换过渡期用，env: Jwt__SigningKey__Previous（可为空）</summary>
+        public string? Previous { get; set; }
+    }
+}

Config/McpDiscoveryOptions.cs

@@ -0,0 +1,15 @@
+namespace ObsidianMcp.Config;
+
+/// <summary>
+/// /.well-known/oauth-authorization-server 返回的元数据配置。
+/// 环境变量前缀 Mcp__OAuthDiscovery__，例如 Mcp__OAuthDiscovery__Issuer=...
+/// </summary>
+public class McpDiscoveryOptions
+{
+    public const string Section = "Mcp:OAuthDiscovery";
+
+    public string Issuer { get; set; } = "https://auth.zhengchentao.win";
+    public string AuthorizationEndpoint { get; set; } = "https://auth.zhengchentao.win/authorize";
+    public string TokenEndpoint { get; set; } = "https://auth.zhengchentao.win/token";
+    public string RegistrationEndpoint { get; set; } = "https://auth.zhengchentao.win/register";
+}

Config/VaultOptions.cs

@@ -0,0 +1,19 @@
+namespace ObsidianMcp.Config;
+
+/// <summary>
+/// Vault 根目录与路径安全配置。
+/// 环境变量前缀 Vault__，例如 Vault__Root=/vault
+/// </summary>
+public class VaultOptions
+{
+    public const string Section = "Vault";
+
+    /// <summary>Vault 根目录的绝对路径，容器内默认 /vault</summary>
+    public string Root { get; set; } = "/vault";
+
+    /// <summary>额外黑名单路径段（与 hardcode 合并），env: Vault__Blacklist__0, __1...</summary>
+    public string[] Blacklist { get; set; } = [];
+
+    /// <summary>额外写入白名单前缀（与 hardcode 合并），env: Vault__WriteWhitelist__0...</summary>
+    public string[] WriteWhitelist { get; set; } = [];
+}

Dockerfile

@@ -0,0 +1,49 @@
+# ─── Stage 1: build ───────────────────────────────────────────────────────────
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS builder
+
+WORKDIR /src
+
+# 先只复制 csproj，利用层缓存加速 restore
+COPY obsidian-mcp.csproj ./
+RUN dotnet restore obsidian-mcp.csproj
+
+# 复制全部源码并 publish
+COPY . .
+RUN dotnet publish obsidian-mcp.csproj \
+    --configuration Release \
+    --no-restore \
+    --output /app/publish
+
+# ─── Stage 2: runtime ─────────────────────────────────────────────────────────
+FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
+
+WORKDIR /app
+
+# 安装 ripgrep（V3 搜索优化预留，现在不调用但容器里装上备用）
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ripgrep \
+    && rm -rf /var/lib/apt/lists/*
+
+# 从 builder 阶段复制 publish 产物
+COPY --from=builder /app/publish .
+
+# 日志目录（审计日志挂载点）
+RUN mkdir -p /app/logs
+
+# 非 root 运行，安全加固
+RUN adduser --disabled-password --no-create-home obsidian-mcp \
+    && chown -R obsidian-mcp:obsidian-mcp /app
+
+USER obsidian-mcp
+
+# 容器内监听 0.0.0.0:8080
+ENV ASPNETCORE_URLS=http://0.0.0.0:8080
+ENV ASPNETCORE_ENVIRONMENT=Production
+
+EXPOSE 8080
+
+# OCI 标签（source/revision 在 CI 构建时通过 --label 覆盖）
+LABEL org.opencontainers.image.source="https://git.zhengchentao.win/zhengchen.tao/obsidian-mcp"
+LABEL org.opencontainers.image.description="Obsidian vault MCP server — read/write vault via MCP, auth via nas-auth"
+
+ENTRYPOINT ["dotnet", "obsidian-mcp.dll"]

Endpoints/DiscoveryEndpoints.cs

@@ -0,0 +1,31 @@
+using ObsidianMcp.Config;
+
+namespace ObsidianMcp.Endpoints;
+
+public static class DiscoveryEndpoints
+{
+    /// <summary>
+    /// 注册 /.well-known/oauth-authorization-server 端点。
+    /// 返回静态 JSON 指向 nas-auth，让 Claude.ai 能自动发现授权服务器。
+    /// 所有字段从 McpDiscoveryOptions 读，不 hardcode。
+    /// </summary>
+    public static void MapDiscoveryEndpoints(this WebApplication app)
+    {
+        app.MapGet("/.well-known/oauth-authorization-server", (McpDiscoveryOptions opts) =>
+        {
+            return Results.Ok(new
+            {
+                issuer = opts.Issuer,
+                authorization_endpoint = opts.AuthorizationEndpoint,
+                token_endpoint = opts.TokenEndpoint,
+                registration_endpoint = opts.RegistrationEndpoint,
+                response_types_supported = new[] { "code" },
+                grant_types_supported = new[] { "authorization_code", "refresh_token" },
+                code_challenge_methods_supported = new[] { "S256" },
+                scopes_supported = new[] { "read:obsidian", "write:obsidian" },
+            });
+        })
+        .AllowAnonymous() // well-known 端点不需要认证，Claude 在登录前就要访问它
+        .WithName("OAuthDiscovery");
+    }
+}

Program.cs

@@ -0,0 +1,83 @@
+using Microsoft.AspNetCore.Authorization;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Config;
+using ObsidianMcp.Endpoints;
+using ObsidianMcp.Services;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// ─── 配置绑定 ───────────────────────────────────────────────────────────────
+
+var jwtOpts = builder.Configuration.GetSection(JwtOptions.Section).Get<JwtOptions>()
+    ?? new JwtOptions();
+
+// ─── 配置对象注册到 DI ───────────────────────────────────────────────────────
+
+builder.Services.Configure<VaultOptions>(
+    builder.Configuration.GetSection(VaultOptions.Section));
+builder.Services.Configure<JwtOptions>(
+    builder.Configuration.GetSection(JwtOptions.Section));
+
+// McpDiscoveryOptions 直接注册为单例（供 DiscoveryEndpoints 依赖注入）
+var discoveryOpts = builder.Configuration.GetSection(McpDiscoveryOptions.Section).Get<McpDiscoveryOptions>()
+    ?? new McpDiscoveryOptions();
+builder.Services.AddSingleton(discoveryOpts);
+
+// ─── 认证与授权 ──────────────────────────────────────────────────────────────
+
+builder.Services.AddObsidianJwtBearer(jwtOpts);
+
+builder.Services.AddAuthorization(opts =>
+{
+    opts.AddScopePolicies();
+    // 默认 policy：只要求已认证（JWT 验签通过即可），不要求特定 scope
+    opts.DefaultPolicy = new AuthorizationPolicyBuilder()
+        .RequireAuthenticatedUser()
+        .Build();
+});
+
+// scope 自定义 handler
+builder.Services.AddSingleton<IAuthorizationHandler, ScopeAuthorizationHandler>();
+
+// IHttpContextAccessor（Tool 里取 User / scope 用）
+builder.Services.AddHttpContextAccessor();
+
+// ─── MCP SDK ─────────────────────────────────────────────────────────────────
+
+builder.Services.AddMcpServer()
+    .WithHttpTransport()             // Streamable HTTP（单端点 POST /mcp）
+    .WithToolsFromAssembly();        // 自动扫描 [McpServerToolType]
+
+// ─── 业务服务 ────────────────────────────────────────────────────────────────
+
+builder.Services.AddSingleton<VaultPathResolver>();
+builder.Services.AddSingleton<VaultWriteGuard>();
+builder.Services.AddSingleton<VaultSearchService>();
+builder.Services.AddSingleton<AuditLogger>();
+
+// ─── Build ───────────────────────────────────────────────────────────────────
+
+var app = builder.Build();
+
+// ─── Middleware 顺序（顺序不能乱）───────────────────────────────────────────
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+// ─── 路由 ────────────────────────────────────────────────────────────────────
+
+// /.well-known/oauth-authorization-server（不需要认证）
+app.MapDiscoveryEndpoints();
+
+// 健康检查（方便 docker compose 和 NPM 探活）
+app.MapGet("/health", () => Results.Ok(new { status = "ok", time = DateTime.UtcNow }))
+    .AllowAnonymous();
+
+// MCP 端点（必须认证，Bearer JWT）。
+// 端点级只校验"已认证"，scope 校验放在每个 Tool 里：
+//   - 读 tool 校验 read:obsidian
+//   - 写 tool 校验 write:obsidian
+// 这样客户端拿单一 scope（仅读 / 仅写）的 Token 都能正常用对应工具。
+app.MapMcp("/mcp").RequireAuthorization();
+
+app.Run();

Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5117",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7031;http://localhost:5117",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

README.md

@@ -0,0 +1,100 @@
+# 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)
+    │
+    ▼
+obs.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)

Services/AuditLogger.cs

@@ -0,0 +1,55 @@
+using System.Text.Json;
+
+namespace ObsidianMcp.Services;
+
+/// <summary>
+/// 写操作审计日志（JSON lines 格式，按天 rotate）。
+/// 输出到 /app/logs/audit-YYYY-MM-DD.log。
+/// 注册为 Singleton，内部用 lock 保证多线程写入安全。
+/// </summary>
+public class AuditLogger
+{
+    private readonly string _logDir;
+    private readonly object _lock = new();
+
+    public AuditLogger(IConfiguration config)
+    {
+        // 允许通过配置覆盖日志目录，默认 /app/logs
+        _logDir = config["AuditLog:Directory"] ?? "/app/logs";
+        Directory.CreateDirectory(_logDir);
+    }
+
+    /// <summary>
+    /// 记录一次写操作审计条目。
+    /// </summary>
+    public void LogWrite(
+        string user,
+        string clientId,
+        string tool,
+        string path,
+        long bytes,
+        bool ok,
+        string? error = null)
+    {
+        var entry = new
+        {
+            timestamp = DateTime.UtcNow.ToString("O"),
+            user,
+            tool,
+            path,
+            bytes,
+            client_id = clientId,
+            ok,
+            error,
+        };
+
+        var line = JsonSerializer.Serialize(entry);
+        var fileName = $"audit-{DateTime.UtcNow:yyyy-MM-dd}.log";
+        var filePath = Path.Combine(_logDir, fileName);
+
+        lock (_lock)
+        {
+            File.AppendAllText(filePath, line + Environment.NewLine);
+        }
+    }
+}

Services/VaultPathResolver.cs

@@ -0,0 +1,141 @@
+using ObsidianMcp.Config;
+using Microsoft.Extensions.Options;
+
+namespace ObsidianMcp.Services;
+
+/// <summary>
+/// Vault 路径安全守卫（chroot 语义）。
+///
+/// 职责：
+///   - 把相对路径拼接到 VaultRoot，防止路径穿越（../）
+///   - 拒绝绝对路径输入
+///   - 拒绝命中黑名单的路径段
+///
+/// 线程安全，注册为 Singleton。
+/// </summary>
+public class VaultPathResolver
+{
+    // hardcode 黑名单路径段（任意路径段命中即拒）
+    private static readonly HashSet<string> HardcodeBlacklist =
+        new(StringComparer.OrdinalIgnoreCase)
+        {
+            "01-Secret",
+            ".obsidian",
+            ".trash",
+            ".git",
+        };
+
+    private readonly string _root;
+    private readonly HashSet<string> _blacklist;
+
+    public VaultPathResolver(IOptions<VaultOptions> opts)
+    {
+        var o = opts.Value;
+        _root = Path.GetFullPath(o.Root);
+
+        // 合并 hardcode + env 配置的黑名单，去重
+        _blacklist = new HashSet<string>(HardcodeBlacklist, StringComparer.OrdinalIgnoreCase);
+        foreach (var b in o.Blacklist)
+            if (!string.IsNullOrWhiteSpace(b))
+                _blacklist.Add(b.Trim());
+    }
+
+    /// <summary>返回 vault 根目录的绝对路径（规范化后）。</summary>
+    public string VaultRoot => _root;
+
+    /// <summary>
+    /// 将相对路径解析为 vault 内的绝对路径。
+    ///
+    /// 可能抛出：
+    ///   UnauthorizedAccessException — 路径穿越、绝对路径、命中黑名单、目标是 symlink
+    ///   ArgumentException — relativePath 为空
+    /// </summary>
+    public string Resolve(string relativePath)
+    {
+        if (string.IsNullOrWhiteSpace(relativePath))
+            throw new ArgumentException("路径不能为空。", nameof(relativePath));
+
+        // 拒绝绝对路径输入（防止容器外访问；包括 Linux /etc/... 与 Windows C:\... / UNC \\server）
+        if (Path.IsPathRooted(relativePath))
+            throw new UnauthorizedAccessException(
+                $"拒绝绝对路径输入：{relativePath}");
+
+        // 把 Windows 反斜杠归一化成 Unix 分隔符，避免 Linux 容器上把 "..\\.." 当成单段不消解。
+        // 注意：仅对相对路径输入做归一化；root 路径已经由 Path.GetFullPath 处理过。
+        var normalizedRel = relativePath.Replace('\\', '/');
+
+        // 拼接并规范化（自动消解 .. 和 .）
+        var target = Path.GetFullPath(Path.Combine(_root, normalizedRel));
+
+        // 确认解析后的路径仍在 vault root 内
+        if (!IsUnderRoot(target))
+            throw new UnauthorizedAccessException(
+                $"路径穿越 vault 根目录：{relativePath}");
+
+        // 逐段检查黑名单
+        CheckBlacklist(target, relativePath);
+
+        // 拒绝 symlink（无论指向 vault 内外，统一禁；vault 真实内容应是普通文件 / 目录）。
+        // 这是兜底防线：万一 WebDAV / 操作失误把 symlink 落到 vault 里，避免 Tool 跟随到容器外。
+        RejectSymlink(target, relativePath);
+
+        return target;
+    }
+
+    /// <summary>
+    /// 检查路径自身（以及任一父级路径段）是否是 symlink。是 → 拒绝。
+    /// 防御链外文件 leak（例如有人在 vault 里建一个指向 /etc/passwd 的软链）。
+    /// </summary>
+    private void RejectSymlink(string absPath, string original)
+    {
+        // 从 absPath 一直向上检查到 _root（不含 root 本体；root 是已知信任的挂载点）
+        var current = absPath;
+        while (current != null && current.Length > _root.Length)
+        {
+            try
+            {
+                var info = new FileInfo(current);
+                if (info.Exists && info.LinkTarget != null)
+                    throw new UnauthorizedAccessException($"拒绝 symlink 路径：{original}");
+                if (!info.Exists)
+                {
+                    var di = new DirectoryInfo(current);
+                    if (di.Exists && di.LinkTarget != null)
+                        throw new UnauthorizedAccessException($"拒绝 symlink 路径：{original}");
+                }
+            }
+            catch (UnauthorizedAccessException) { throw; }
+            catch
+            {
+                // I/O 异常不在这里阻断；后续真正读文件时会自然抛
+            }
+            var parent = Path.GetDirectoryName(current);
+            if (parent == null || parent == current) break;
+            current = parent;
+        }
+    }
+
+    /// <summary>检查绝对路径是否在 vault root 下（含等于 root）。</summary>
+    private bool IsUnderRoot(string absPath)
+    {
+        return absPath == _root
+            || absPath.StartsWith(_root + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>逐个路径段检查黑名单。</summary>
+    private void CheckBlacklist(string absPath, string original)
+    {
+        // 把 absPath 中 root 之后的部分按分隔符拆分，逐段比对
+        var relative = absPath[_root.Length..].TrimStart(Path.DirectorySeparatorChar);
+        var segments = relative.Split(
+            [Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar],
+            StringSplitOptions.RemoveEmptyEntries);
+
+        foreach (var seg in segments)
+        {
+            if (_blacklist.Contains(seg))
+                throw new UnauthorizedAccessException(
+                    $"路径命中黑名单段 '{seg}'：{original}");
+        }
+    }
+}

Services/VaultSearchService.cs

@@ -0,0 +1,104 @@
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Extensions.FileSystemGlobbing.Abstractions;
+
+namespace ObsidianMcp.Services;
+
+/// <summary>
+/// Vault 全文搜索服务。
+/// 纯 C# 实现，大小写不敏感子串匹配（不支持 regex）。
+/// V3 可替换为 ripgrep 调用。
+/// </summary>
+public class VaultSearchService
+{
+    private readonly VaultPathResolver _resolver;
+
+    public VaultSearchService(VaultPathResolver resolver)
+    {
+        _resolver = resolver;
+    }
+
+    /// <param name="query">大小写不敏感的子串</param>
+    /// <param name="glob">glob 过滤，例如 "NAS/**/*.md"，为 null 时搜全 vault</param>
+    /// <param name="limit">最多返回条数</param>
+    /// <param name="ct">CancellationToken</param>
+    public async Task<List<SearchHit>> SearchAsync(
+        string query,
+        string? glob,
+        int limit,
+        CancellationToken ct = default)
+    {
+        var root = _resolver.VaultRoot;
+        var files = GetFilesToSearch(root, glob);
+
+        var hits = new List<SearchHit>();
+        foreach (var file in files)
+        {
+            if (ct.IsCancellationRequested) break;
+            if (hits.Count >= limit) break;
+
+            await SearchFileAsync(file, root, query, limit, hits, ct);
+        }
+
+        return hits;
+    }
+
+    private static IEnumerable<string> GetFilesToSearch(string root, string? glob)
+    {
+        if (string.IsNullOrWhiteSpace(glob))
+        {
+            // 全 vault 搜索，只搜 .md 文件（.json/.yaml 通常不需要全文检索）
+            return Directory.EnumerateFiles(root, "*.md", SearchOption.AllDirectories);
+        }
+
+        // 用 Microsoft.Extensions.FileSystemGlobbing 做 glob 过滤
+        var matcher = new Matcher(StringComparison.OrdinalIgnoreCase);
+        matcher.AddInclude(glob);
+        var dirInfo = new DirectoryInfoWrapper(new DirectoryInfo(root));
+        var result = matcher.Execute(dirInfo);
+        return result.Files.Select(f => Path.Combine(root, f.Path));
+    }
+
+    private static async Task SearchFileAsync(
+        string filePath,
+        string root,
+        string query,
+        int limit,
+        List<SearchHit> hits,
+        CancellationToken ct)
+    {
+        // 跳过过大的文件（>5MB），避免 OOM
+        var fi = new FileInfo(filePath);
+        if (!fi.Exists || fi.Length > 5 * 1024 * 1024) return;
+
+        try
+        {
+            int lineNumber = 0;
+            await foreach (var line in File.ReadLinesAsync(filePath, ct))
+            {
+                lineNumber++;
+                if (hits.Count >= limit) break;
+
+                if (line.Contains(query, StringComparison.OrdinalIgnoreCase))
+                {
+                    hits.Add(new SearchHit
+                    {
+                        File = Path.GetRelativePath(root, filePath).Replace('\\', '/'),
+                        Line = lineNumber,
+                        Preview = line.Length > 200 ? line[..200] + "..." : line,
+                    });
+                }
+            }
+        }
+        catch (IOException)
+        {
+            // 文件读取失败（权限、锁定等），跳过不影响其他结果
+        }
+    }
+}
+
+public class SearchHit
+{
+    public string File { get; set; } = "";
+    public int Line { get; set; }
+    public string Preview { get; set; } = "";
+}

Services/VaultWriteGuard.cs

@@ -0,0 +1,120 @@
+using ObsidianMcp.Config;
+using Microsoft.Extensions.Options;
+
+namespace ObsidianMcp.Services;
+
+/// <summary>
+/// 写入门禁——在路径安全（VaultPathResolver）之上再加写入白名单控制。
+///
+/// 规则优先级（从高到低）：
+///   1. 永禁写入：AGENTS.md / PROFILE.md / README.md / CLAUDE.md（任何路径下的同名文件）
+///   2. 永禁前缀：01-Secret/
+///   3. 必须命中写入白名单之一才允许
+///
+/// 白名单（hardcode）：
+///   - 前缀 02-ShengquGames/logs/
+///   - 前缀 Coding/
+///   - 精确匹配 NAS/NAS 待办清单.md
+///
+/// 白名单可通过 env Vault__WriteWhitelist__N 扩展。
+/// </summary>
+public class VaultWriteGuard
+{
+    // 永禁写入的文件名（不含路径，任何目录下的同名文件都禁写）
+    private static readonly HashSet<string> ForbiddenFileNames =
+        new(StringComparer.OrdinalIgnoreCase)
+        {
+            "AGENTS.md",
+            "PROFILE.md",
+            "README.md",
+            "CLAUDE.md",
+        };
+
+    // 永禁写入的路径前缀（相对路径）
+    private static readonly string[] ForbiddenPrefixes =
+    [
+        "01-Secret/",
+        "01-Secret\\",
+    ];
+
+    // hardcode 写入白名单
+    // 前缀匹配：以 / 或 \ 结尾表示前缀；精确匹配：其他
+    private static readonly string[] HardcodeWhitelist =
+    [
+        "02-ShengquGames/logs/",
+        "02-ShengquGames\\logs\\",
+        "Coding/",
+        "Coding\\",
+        "NAS/NAS 待办清单.md",
+        "NAS\\NAS 待办清单.md",
+    ];
+
+    private readonly VaultPathResolver _resolver;
+    private readonly string[] _extraWhitelist;
+
+    public VaultWriteGuard(VaultPathResolver resolver, IOptions<VaultOptions> opts)
+    {
+        _resolver = resolver;
+        _extraWhitelist = opts.Value.WriteWhitelist ?? [];
+    }
+
+    /// <summary>
+    /// 校验相对路径是否允许写入。
+    /// 通过则返回规范化后的绝对路径；不通过则抛 UnauthorizedAccessException。
+    /// </summary>
+    public string EnsureWritable(string relativePath)
+    {
+        // 先过路径安全守卫（防穿越 + 黑名单）
+        var absPath = _resolver.Resolve(relativePath);
+
+        // 规范化相对路径（用于白名单匹配），统一用 /
+        var normalized = NormalizeRelative(relativePath);
+
+        // 1. 永禁文件名
+        var fileName = Path.GetFileName(absPath);
+        if (ForbiddenFileNames.Contains(fileName))
+            throw new UnauthorizedAccessException(
+                $"禁止写入保护文件：{relativePath}");
+
+        // 2. 永禁前缀
+        foreach (var prefix in ForbiddenPrefixes)
+        {
+            if (normalized.StartsWith(NormalizeRelative(prefix), StringComparison.OrdinalIgnoreCase))
+                throw new UnauthorizedAccessException(
+                    $"禁止写入 01-Secret/ 目录：{relativePath}");
+        }
+
+        // 3. 白名单（hardcode + env 扩展）
+        if (!IsInWhitelist(normalized))
+            throw new UnauthorizedAccessException(
+                $"路径不在写入白名单内：{relativePath}");
+
+        return absPath;
+    }
+
+    private bool IsInWhitelist(string normalized)
+    {
+        var allWhitelist = HardcodeWhitelist.Concat(_extraWhitelist);
+        foreach (var entry in allWhitelist)
+        {
+            var normalizedEntry = NormalizeRelative(entry);
+            if (normalizedEntry.EndsWith('/'))
+            {
+                // 前缀匹配
+                if (normalized.StartsWith(normalizedEntry, StringComparison.OrdinalIgnoreCase))
+                    return true;
+            }
+            else
+            {
+                // 精确匹配
+                if (string.Equals(normalized, normalizedEntry, StringComparison.OrdinalIgnoreCase))
+                    return true;
+            }
+        }
+        return false;
+    }
+
+    /// <summary>统一用 / 作分隔符，用于白名单匹配。</summary>
+    private static string NormalizeRelative(string path) =>
+        path.Replace('\\', '/');
+}

Tools/AppendFileTool.cs

@@ -0,0 +1,81 @@
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class AppendFileTool(
+    VaultWriteGuard guard,
+    AuditLogger audit,
+    IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "Append text to the end of a vault file (requires write:obsidian scope). " +
+        "Automatically prepends a newline if the file is non-empty and does not end with one. " +
+        "Ideal for adding entries to monthly work logs (02-ShengquGames/logs/YYYY-MM.md) " +
+        "or the NAS todo list (NAS/NAS 待办清单.md) without touching existing content. " +
+        "Same whitelist restrictions as write_file apply.")]
+    public async Task<WriteResult> AppendFile(
+        [Description("Vault-relative path (must be in writable whitelist). " +
+                     "e.g. 'NAS/NAS 待办清单.md', '02-ShengquGames/logs/2026-05.md'")] string path,
+        [Description("Text to append (UTF-8). A newline is automatically inserted before this text " +
+                     "if the file does not already end with one.")] string content)
+    {
+        // scope 校验
+        EnsureScope(ScopePolicies.WriteObsidian);
+
+        var user = GetUser();
+        var clientId = GetClientId();
+
+        try
+        {
+            var absPath = guard.EnsureWritable(path);
+
+            // 确保父目录存在
+            var dir = Path.GetDirectoryName(absPath)!;
+            Directory.CreateDirectory(dir);
+
+            // 如果文件已存在且末尾没有换行，先补一个
+            string prefix = string.Empty;
+            if (File.Exists(absPath))
+            {
+                var existing = await File.ReadAllTextAsync(absPath);
+                if (existing.Length > 0 && !existing.EndsWith('\n'))
+                    prefix = Environment.NewLine;
+            }
+
+            await File.AppendAllTextAsync(absPath, prefix + content, System.Text.Encoding.UTF8);
+            var written = System.Text.Encoding.UTF8.GetByteCount(prefix + content);
+
+            audit.LogWrite(user, clientId, "append_file", path, written, ok: true);
+            return new WriteResult { Ok = true, WrittenBytes = written };
+        }
+        catch (Exception ex)
+        {
+            audit.LogWrite(user, clientId, "append_file", path, 0, ok: false, error: ex.Message);
+            throw;
+        }
+    }
+
+    private void EnsureScope(string requiredScope)
+    {
+        // OAuth 2.0 (RFC 6749) 规定 scope 大小写敏感，按 Ordinal 比对。
+        ToolScopeGuard.EnsureScope(http, requiredScope);
+    }
+
+    private string GetUser() =>
+        http.HttpContext?.User?.FindFirst("sub")?.Value ?? "unknown";
+
+    private string GetClientId() =>
+        http.HttpContext?.User?.FindFirst("client_id")?.Value ?? "unknown";
+}
+
+/// <summary>写入操作的返回值。</summary>
+public class WriteResult
+{
+    public bool Ok { get; set; }
+    public int WrittenBytes { get; set; }
+}

Tools/GetMetadataTool.cs

@@ -0,0 +1,60 @@
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class GetMetadataTool(VaultPathResolver resolver, IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "Get metadata for a vault file without reading its content. " +
+        "Returns size in bytes, last modified timestamp (UTC ISO-8601), " +
+        "and whether the file starts with YAML frontmatter (--- ... ---). " +
+        "Useful for deciding whether to read a file (staleness check, size guard before read_file).")]
+    public FileMetadata GetMetadata(
+        [Description("Vault-relative path to the file. " +
+                     "e.g. 'NAS/NAS 总览.md'")] string path)
+    {
+        ToolScopeGuard.EnsureScope(http, ScopePolicies.ReadObsidian);
+
+        var absPath = resolver.Resolve(path);
+
+        if (!File.Exists(absPath))
+            throw new FileNotFoundException($"文件不存在：{path}");
+
+        var fi = new FileInfo(absPath);
+
+        // 简单判断是否有 frontmatter：读前 4 字节检查是否以 --- 开头
+        bool hasFrontmatter = false;
+        try
+        {
+            using var fs = File.OpenRead(absPath);
+            var header = new byte[4];
+            if (fs.Read(header, 0, 4) == 4)
+                hasFrontmatter = header[0] == '-' && header[1] == '-' && header[2] == '-';
+        }
+        catch
+        {
+            // 读取失败不影响其他字段
+        }
+
+        return new FileMetadata
+        {
+            Path = path,
+            SizeBytes = fi.Length,
+            ModifiedAt = fi.LastWriteTimeUtc.ToString("O"),
+            HasFrontmatter = hasFrontmatter,
+        };
+    }
+}
+
+public class FileMetadata
+{
+    public string Path { get; set; } = "";
+    public long SizeBytes { get; set; }
+    public string ModifiedAt { get; set; } = "";
+    public bool HasFrontmatter { get; set; }
+}

Tools/ListFilesTool.cs

@@ -0,0 +1,55 @@
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class ListFilesTool(VaultPathResolver resolver, IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "List files and immediate subdirectories in a vault directory. " +
+        "Returns a flat list of names (not full paths). " +
+        "Use list_vault_tree for a recursive overview, or this tool to drill into one directory. " +
+        "Hidden directories and blacklisted paths (01-Secret, .obsidian, etc.) are excluded.")]
+    public List<string> ListFiles(
+        [Description("Vault-relative path to list. Defaults to root if omitted. " +
+                     "e.g. 'NAS', '02-ShengquGames/logs'")] string? path = null)
+    {
+        ToolScopeGuard.EnsureScope(http, ScopePolicies.ReadObsidian);
+
+        string absDir;
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            absDir = resolver.VaultRoot;
+        }
+        else
+        {
+            absDir = resolver.Resolve(path);
+        }
+
+        if (!Directory.Exists(absDir))
+            throw new DirectoryNotFoundException($"目录不存在：{path}");
+
+        var result = new List<string>();
+
+        // 子目录（排除隐藏和黑名单）
+        foreach (var dir in Directory.GetDirectories(absDir).OrderBy(Path.GetFileName, StringComparer.OrdinalIgnoreCase))
+        {
+            var seg = Path.GetFileName(dir)!;
+            if (seg.StartsWith('.')) continue;
+            if (seg.Equals("01-Secret", StringComparison.OrdinalIgnoreCase)) continue;
+            result.Add(seg + "/");
+        }
+
+        // 文件
+        foreach (var file in Directory.GetFiles(absDir).OrderBy(Path.GetFileName, StringComparer.OrdinalIgnoreCase))
+        {
+            result.Add(Path.GetFileName(file));
+        }
+
+        return result;
+    }
+}

Tools/ListVaultTreeTool.cs

@@ -0,0 +1,72 @@
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class ListVaultTreeTool(VaultPathResolver resolver, IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "Return a depth-limited directory tree of the entire Obsidian vault as JSON. " +
+        "Use this first when you need an overview of the vault structure. " +
+        "Each node has { name, type (file|directory), children? }. " +
+        "Blacklisted directories (01-Secret, .obsidian, .trash, .git) are excluded. " +
+        "Prefer this over multiple list_files calls when you need the big picture.")]
+    public object ListVaultTree(
+        [Description("Maximum depth to traverse (default 3). Root is depth 0.")] int depth = 3)
+    {
+        ToolScopeGuard.EnsureScope(http, ScopePolicies.ReadObsidian);
+
+        if (depth < 0) depth = 0;
+        if (depth > 10) depth = 10; // 防止超大 vault 超时
+
+        var root = resolver.VaultRoot;
+        return BuildNode(root, root, depth);
+    }
+
+    private static object BuildNode(string path, string root, int remainingDepth)
+    {
+        var name = path == root ? "/" : Path.GetFileName(path);
+
+        if (File.Exists(path))
+        {
+            return new { name, type = "file" };
+        }
+
+        if (!Directory.Exists(path))
+            return new { name, type = "unknown" };
+
+        if (remainingDepth == 0)
+            return new { name, type = "directory" };
+
+        // 枚举子项，排序：目录先、文件后，各自按名字排序
+        List<object> children = [];
+
+        try
+        {
+            var entries = Directory.GetFileSystemEntries(path)
+                .OrderBy(e => File.Exists(e) ? 1 : 0)
+                .ThenBy(e => Path.GetFileName(e), StringComparer.OrdinalIgnoreCase);
+
+            foreach (var entry in entries)
+            {
+                var segName = Path.GetFileName(entry);
+                // 跳过隐藏文件/目录（以 . 开头）
+                if (segName.StartsWith('.')) continue;
+                // 跳过 01-Secret
+                if (segName.Equals("01-Secret", StringComparison.OrdinalIgnoreCase)) continue;
+
+                children.Add(BuildNode(entry, root, remainingDepth - 1));
+            }
+        }
+        catch (UnauthorizedAccessException)
+        {
+            // 无权限目录跳过
+        }
+
+        return new { name, type = "directory", children };
+    }
+}

Tools/ReadFileTool.cs

@@ -0,0 +1,55 @@
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class ReadFileTool(VaultPathResolver resolver, IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "Read the full content of a vault file (UTF-8). " +
+        "This is the primary tool for reading notes, design docs, logs, and config files. " +
+        "Use get_metadata first if you want to check the file size before reading. " +
+        "For very large files (>100 KB), use the offset and limit parameters (in bytes) " +
+        "to read specific byte ranges and avoid context window overflow. " +
+        "Returns the raw Markdown text including frontmatter.")]
+    public async Task<string> ReadFile(
+        [Description("Vault-relative path to the file. " +
+                     "e.g. 'NAS/NAS 总览.md', 'PROFILE.md', '02-ShengquGames/logs/2026-05.md'")] string path,
+        [Description("Byte offset to start reading from (0-based). Omit to read from the beginning.")] long? offset = null,
+        [Description("Number of bytes to read. Omit to read the entire file.")] long? limit = null)
+    {
+        ToolScopeGuard.EnsureScope(http, ScopePolicies.ReadObsidian);
+
+        var absPath = resolver.Resolve(path);
+
+        if (!File.Exists(absPath))
+            throw new FileNotFoundException($"文件不存在：{path}");
+
+        // 无分页时直接读全文
+        if (offset is null && limit is null)
+            return await File.ReadAllTextAsync(absPath);
+
+        // 有分页参数时按字节切片
+        await using var fs = new FileStream(absPath, FileMode.Open, FileAccess.Read, FileShare.Read);
+
+        long startByte = offset ?? 0;
+        if (startByte < 0) startByte = 0;
+        if (startByte >= fs.Length)
+            return string.Empty;
+
+        fs.Seek(startByte, SeekOrigin.Begin);
+
+        long bytesToRead = limit.HasValue
+            ? Math.Min(limit.Value, fs.Length - startByte)
+            : fs.Length - startByte;
+
+        var buffer = new byte[bytesToRead];
+        var read = await fs.ReadAsync(buffer.AsMemory(0, (int)bytesToRead));
+
+        return System.Text.Encoding.UTF8.GetString(buffer, 0, read);
+    }
+}

Tools/SearchTool.cs

@@ -0,0 +1,37 @@
+using System.ComponentModel;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class SearchTool(VaultSearchService searchSvc, IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "Full-text search the Obsidian vault using case-insensitive literal substring match. " +
+        "Does NOT support regex or wildcards in the query string. " +
+        "Returns up to 50 hits by default, each with file path, line number, and a preview snippet. " +
+        "Use the glob parameter to narrow the search to specific directories or file patterns. " +
+        "For exact file reading use read_file instead. " +
+        "Examples: search for 'docker compose' across all files, or 'Uam' within '02-ShengquGames/**/*.md'.")]
+    public async Task<List<SearchHit>> Search(
+        [Description("Literal substring to search for (case-insensitive). " +
+                     "e.g. 'docker compose', 'iptables PREROUTING', 'DOCKER_API_VERSION'")] string query,
+        [Description("Optional glob pattern to narrow files. " +
+                     "e.g. 'NAS/**/*.md', '02-ShengquGames/**', '*.md'. " +
+                     "Omit to search all .md files.")] string? glob = null,
+        [Description("Maximum number of results to return (default 50, max 200).")] int limit = 50)
+    {
+        ToolScopeGuard.EnsureScope(http, ScopePolicies.ReadObsidian);
+
+        if (string.IsNullOrWhiteSpace(query))
+            throw new ArgumentException("query 不能为空。");
+
+        if (limit <= 0) limit = 50;
+        if (limit > 200) limit = 200;
+
+        return await searchSvc.SearchAsync(query, glob, limit);
+    }
+}

Tools/WriteFileTool.cs

@@ -0,0 +1,69 @@
+using System.ComponentModel;
+using Microsoft.AspNetCore.Authorization;
+using ModelContextProtocol.Server;
+using ObsidianMcp.Auth;
+using ObsidianMcp.Services;
+
+namespace ObsidianMcp.Tools;
+
+[McpServerToolType]
+public class WriteFileTool(
+    VaultWriteGuard guard,
+    AuditLogger audit,
+    IHttpContextAccessor http)
+{
+    [McpServerTool]
+    [Description(
+        "Overwrite a vault file with new content (requires write:obsidian scope). " +
+        "Completely replaces the existing content. " +
+        "Only whitelisted paths are allowed: " +
+        "  - 02-ShengquGames/logs/ (monthly work logs), " +
+        "  - Coding/ (personal infra notes), " +
+        "  - NAS/NAS 待办清单.md (NAS todo list). " +
+        "Vault entry files (AGENTS.md, PROFILE.md, README.md, CLAUDE.md) and 01-Secret/ are always forbidden. " +
+        "Use append_file to add content without overwriting.")]
+    public async Task<WriteResult> WriteFile(
+        [Description("Vault-relative path (must be in writable whitelist). " +
+                     "e.g. '02-ShengquGames/logs/2026-05.md'")] string path,
+        [Description("Full file content to write (UTF-8). Replaces existing content entirely.")] string content)
+    {
+        // scope 校验
+        EnsureScope(ScopePolicies.WriteObsidian);
+
+        var user = GetUser();
+        var clientId = GetClientId();
+        string? absPath = null;
+
+        try
+        {
+            absPath = guard.EnsureWritable(path);
+
+            // 确保父目录存在
+            var dir = Path.GetDirectoryName(absPath)!;
+            Directory.CreateDirectory(dir);
+
+            await File.WriteAllTextAsync(absPath, content, System.Text.Encoding.UTF8);
+            var written = System.Text.Encoding.UTF8.GetByteCount(content);
+
+            audit.LogWrite(user, clientId, "write_file", path, written, ok: true);
+            return new WriteResult { Ok = true, WrittenBytes = written };
+        }
+        catch (Exception ex)
+        {
+            audit.LogWrite(user, clientId, "write_file", path, 0, ok: false, error: ex.Message);
+            throw;
+        }
+    }
+
+    private void EnsureScope(string requiredScope)
+    {
+        // OAuth 2.0 (RFC 6749) 规定 scope 大小写敏感，按 Ordinal 比对。
+        ToolScopeGuard.EnsureScope(http, requiredScope);
+    }
+
+    private string GetUser() =>
+        http.HttpContext?.User?.FindFirst("sub")?.Value ?? "unknown";
+
+    private string GetClientId() =>
+        http.HttpContext?.User?.FindFirst("client_id")?.Value ?? "unknown";
+}

appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

appsettings.Production.json

@@ -0,0 +1,41 @@
+{
+  // 生产配置：所有敏感值通过环境变量注入，这里只放非敏感的生产默认值。
+  //
+  // 必须通过 env 覆盖的项：
+  //   Jwt__SigningKey__Current=<与 nas-auth 共享的 HS256 密钥>
+  //   Jwt__SigningKey__Previous=<密钥轮换时的旧密钥，可选>
+  //   Vault__Root=/vault
+  //
+  // 可选覆盖：
+  //   Vault__Blacklist__0=<额外黑名单段>
+  //   Vault__WriteWhitelist__0=<额外写入白名单前缀>
+
+  "Logging": {
+    "LogLevel": {
+      "Default": "Warning",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+
+  "Vault": {
+    "Root": "/vault"
+  },
+
+  "Jwt": {
+    "Issuer": "https://auth.zhengchentao.win",
+    "Audience": "obsidian"
+  },
+
+  "Mcp": {
+    "OAuthDiscovery": {
+      "Issuer": "https://auth.zhengchentao.win",
+      "AuthorizationEndpoint": "https://auth.zhengchentao.win/authorize",
+      "TokenEndpoint": "https://auth.zhengchentao.win/token",
+      "RegistrationEndpoint": "https://auth.zhengchentao.win/register"
+    }
+  },
+
+  "AuditLog": {
+    "Directory": "/app/logs"
+  }
+}

appsettings.json

@@ -0,0 +1,42 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Microsoft.AspNetCore.Authentication": "Warning"
+    }
+  },
+  "AllowedHosts": "*",
+
+  // Vault 路径配置（生产值通过 env 覆盖）
+  "Vault": {
+    "Root": "./test-vault",
+    "Blacklist": [],
+    "WriteWhitelist": []
+  },
+
+  // JWT 验签配置（生产 key 通过 env 覆盖，不要在此填真实密钥）
+  "Jwt": {
+    "Issuer": "https://auth.zhengchentao.win",
+    "Audience": "obsidian",
+    "SigningKey": {
+      "Current": "",
+      "Previous": ""
+    }
+  },
+
+  // /.well-known/oauth-authorization-server 元数据
+  "Mcp": {
+    "OAuthDiscovery": {
+      "Issuer": "https://auth.zhengchentao.win",
+      "AuthorizationEndpoint": "https://auth.zhengchentao.win/authorize",
+      "TokenEndpoint": "https://auth.zhengchentao.win/token",
+      "RegistrationEndpoint": "https://auth.zhengchentao.win/register"
+    }
+  },
+
+  // 审计日志目录（容器内 /app/logs）
+  "AuditLog": {
+    "Directory": "/app/logs"
+  }
+}

obsidian-mcp.csproj

@@ -0,0 +1,22 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <RootNamespace>ObsidianMcp</RootNamespace>
+    <AssemblyName>obsidian-mcp</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <!-- MCP SDK（Streamable HTTP transport） -->
+    <PackageReference Include="ModelContextProtocol" Version="1.0.0" />
+    <PackageReference Include="ModelContextProtocol.AspNetCore" Version="1.0.0" />
+    <!-- JWT 验签 -->
+    <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="10.0.7" />
+    <PackageReference Include="Microsoft.IdentityModel.Tokens" Version="8.9.0" />
+    <!-- glob 匹配 -->
+    <PackageReference Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.7" />
+  </ItemGroup>
+
+</Project>