From 28f9a54ba9a3e24148f9e5d1ea55d6f2ec472544 Mon Sep 17 00:00:00 2001 From: Zhengchen Tao Date: Wed, 6 May 2026 01:32:11 +0800 Subject: [PATCH] =?UTF-8?q?obsidian-mcp:=20=E5=88=9D=E6=AC=A1=E8=90=BD?= =?UTF-8?q?=E5=9C=B0=20Obsidian=20Vault=20MCP=20Server=20(.NET=2010,=20rea?= =?UTF-8?q?d+write)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 把 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 --- .dockerignore | 15 ++++ .gitea/workflows/build-image.yml | 131 ++++++++++++++++++++++++++++ .gitignore | 23 +++++ Auth/JwtBearerSetup.cs | 62 ++++++++++++++ Auth/ScopePolicies.cs | 85 +++++++++++++++++++ Config/JwtOptions.cs | 27 ++++++ Config/McpDiscoveryOptions.cs | 15 ++++ Config/VaultOptions.cs | 19 +++++ Dockerfile | 49 +++++++++++ Endpoints/DiscoveryEndpoints.cs | 31 +++++++ Program.cs | 83 ++++++++++++++++++ Properties/launchSettings.json | 23 +++++ README.md | 100 ++++++++++++++++++++++ Services/AuditLogger.cs | 55 ++++++++++++ Services/VaultPathResolver.cs | 141 +++++++++++++++++++++++++++++++ Services/VaultSearchService.cs | 104 +++++++++++++++++++++++ Services/VaultWriteGuard.cs | 120 ++++++++++++++++++++++++++ Tools/AppendFileTool.cs | 81 ++++++++++++++++++ Tools/GetMetadataTool.cs | 60 +++++++++++++ Tools/ListFilesTool.cs | 55 ++++++++++++ Tools/ListVaultTreeTool.cs | 72 ++++++++++++++++ Tools/ReadFileTool.cs | 55 ++++++++++++ Tools/SearchTool.cs | 37 ++++++++ Tools/WriteFileTool.cs | 69 +++++++++++++++ appsettings.Development.json | 8 ++ appsettings.Production.json | 41 +++++++++ appsettings.json | 42 +++++++++ obsidian-mcp.csproj | 22 +++++ 28 files changed, 1625 insertions(+) create mode 100644 .dockerignore create mode 100644 .gitea/workflows/build-image.yml create mode 100644 .gitignore create mode 100644 Auth/JwtBearerSetup.cs create mode 100644 Auth/ScopePolicies.cs create mode 100644 Config/JwtOptions.cs create mode 100644 Config/McpDiscoveryOptions.cs create mode 100644 Config/VaultOptions.cs create mode 100644 Dockerfile create mode 100644 Endpoints/DiscoveryEndpoints.cs create mode 100644 Program.cs create mode 100644 Properties/launchSettings.json create mode 100644 README.md create mode 100644 Services/AuditLogger.cs create mode 100644 Services/VaultPathResolver.cs create mode 100644 Services/VaultSearchService.cs create mode 100644 Services/VaultWriteGuard.cs create mode 100644 Tools/AppendFileTool.cs create mode 100644 Tools/GetMetadataTool.cs create mode 100644 Tools/ListFilesTool.cs create mode 100644 Tools/ListVaultTreeTool.cs create mode 100644 Tools/ReadFileTool.cs create mode 100644 Tools/SearchTool.cs create mode 100644 Tools/WriteFileTool.cs create mode 100644 appsettings.Development.json create mode 100644 appsettings.Production.json create mode 100644 appsettings.json create mode 100644 obsidian-mcp.csproj diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..8315027 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,15 @@ +**/.git +**/.gitignore +**/.gitea +**/bin +**/obj +**/*.user +**/.vs +**/.vscode +**/.idea +**/test-vault +obsidian-mcp.Tests/ +.dockerignore +README.md +*.md +LICENSE diff --git a/.gitea/workflows/build-image.yml b/.gitea/workflows/build-image.yml new file mode 100644 index 0000000..95f715f --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..d2ed19a --- /dev/null +++ b/.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 diff --git a/Auth/JwtBearerSetup.cs b/Auth/JwtBearerSetup.cs new file mode 100644 index 0000000..3ec83dd --- /dev/null +++ b/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 +{ + /// + /// 配置 HS256 JWT Bearer 认证。 + /// 支持 Current + Previous 双密钥，方便密钥轮换过渡期。 + /// + 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 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)); + } +} diff --git a/Auth/ScopePolicies.cs b/Auth/ScopePolicies.cs new file mode 100644 index 0000000..4d5d9e2 --- /dev/null +++ b/Auth/ScopePolicies.cs @@ -0,0 +1,85 @@ +using Microsoft.AspNetCore.Authorization; + +namespace ObsidianMcp.Auth; + +/// +/// 自定义 scope 校验 Policy： +/// RequireScope("read:obsidian") +/// RequireScope("write:obsidian") +/// +/// JWT 的 scope claim 可能是单个字符串（空格分隔）或多个 claim，两种都处理。 +/// +public static class ScopePolicies +{ + public const string ReadObsidian = "read:obsidian"; + public const string WriteObsidian = "write:obsidian"; + + /// 注册两条 scope policy 到 AuthorizationOptions。 + 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 +{ + 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 ---------- + +/// +/// MCP Tool 内部 scope 校验：从当前 HttpContext.User 读 scope claim， +/// 不包含 requiredScope 时抛 UnauthorizedAccessException。 +/// +/// 用法：在每个读 / 写 Tool 的方法体首行调一下，给客户端可读的失败原因。 +/// 端点级 RequireAuthorization 只确保 JWT 验签通过；scope 颗粒度门禁在这里。 +/// OAuth 2.0 (RFC 6749) 规定 scope 大小写敏感。 +/// +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}"); + } +} diff --git a/Config/JwtOptions.cs b/Config/JwtOptions.cs new file mode 100644 index 0000000..6f3ba50 --- /dev/null +++ b/Config/JwtOptions.cs @@ -0,0 +1,27 @@ +namespace ObsidianMcp.Config; + +/// +/// JWT 验签配置。 +/// 环境变量：Jwt__Issuer, Jwt__Audience, Jwt__SigningKey__Current, Jwt__SigningKey__Previous +/// +public class JwtOptions +{ + public const string Section = "Jwt"; + + /// 期望的 iss claim，生产：https://auth.zhengchentao.win + public string Issuer { get; set; } = "https://auth.zhengchentao.win"; + + /// 期望的 aud claim，生产：obsidian + public string Audience { get; set; } = "obsidian"; + + public SigningKeyPair SigningKey { get; set; } = new(); + + public class SigningKeyPair + { + /// 当前签名密钥（HS256 对称密钥），env: Jwt__SigningKey__Current + public string Current { get; set; } = string.Empty; + + /// 上一轮密钥，密钥轮换过渡期用，env: Jwt__SigningKey__Previous（可为空） + public string? Previous { get; set; } + } +} diff --git a/Config/McpDiscoveryOptions.cs b/Config/McpDiscoveryOptions.cs new file mode 100644 index 0000000..bf8fc7a --- /dev/null +++ b/Config/McpDiscoveryOptions.cs @@ -0,0 +1,15 @@ +namespace ObsidianMcp.Config; + +/// +/// /.well-known/oauth-authorization-server 返回的元数据配置。 +/// 环境变量前缀 Mcp__OAuthDiscovery__，例如 Mcp__OAuthDiscovery__Issuer=... +/// +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"; +} diff --git a/Config/VaultOptions.cs b/Config/VaultOptions.cs new file mode 100644 index 0000000..fe7e1a4 --- /dev/null +++ b/Config/VaultOptions.cs @@ -0,0 +1,19 @@ +namespace ObsidianMcp.Config; + +/// +/// Vault 根目录与路径安全配置。 +/// 环境变量前缀 Vault__，例如 Vault__Root=/vault +/// +public class VaultOptions +{ + public const string Section = "Vault"; + + /// Vault 根目录的绝对路径，容器内默认 /vault + public string Root { get; set; } = "/vault"; + + /// 额外黑名单路径段（与 hardcode 合并），env: Vault__Blacklist__0, __1... + public string[] Blacklist { get; set; } = []; + + /// 额外写入白名单前缀（与 hardcode 合并），env: Vault__WriteWhitelist__0... + public string[] WriteWhitelist { get; set; } = []; +} diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..d89705c --- /dev/null +++ b/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"] diff --git a/Endpoints/DiscoveryEndpoints.cs b/Endpoints/DiscoveryEndpoints.cs new file mode 100644 index 0000000..db50b73 --- /dev/null +++ b/Endpoints/DiscoveryEndpoints.cs @@ -0,0 +1,31 @@ +using ObsidianMcp.Config; + +namespace ObsidianMcp.Endpoints; + +public static class DiscoveryEndpoints +{ + /// + /// 注册 /.well-known/oauth-authorization-server 端点。 + /// 返回静态 JSON 指向 nas-auth，让 Claude.ai 能自动发现授权服务器。 + /// 所有字段从 McpDiscoveryOptions 读，不 hardcode。 + /// + 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"); + } +} diff --git a/Program.cs b/Program.cs new file mode 100644 index 0000000..82c210b --- /dev/null +++ b/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() + ?? new JwtOptions(); + +// ─── 配置对象注册到 DI ─────────────────────────────────────────────────────── + +builder.Services.Configure( + builder.Configuration.GetSection(VaultOptions.Section)); +builder.Services.Configure( + builder.Configuration.GetSection(JwtOptions.Section)); + +// McpDiscoveryOptions 直接注册为单例（供 DiscoveryEndpoints 依赖注入） +var discoveryOpts = builder.Configuration.GetSection(McpDiscoveryOptions.Section).Get() + ?? 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(); + +// IHttpContextAccessor（Tool 里取 User / scope 用） +builder.Services.AddHttpContextAccessor(); + +// ─── MCP SDK ───────────────────────────────────────────────────────────────── + +builder.Services.AddMcpServer() + .WithHttpTransport() // Streamable HTTP（单端点 POST /mcp） + .WithToolsFromAssembly(); // 自动扫描 [McpServerToolType] + +// ─── 业务服务 ──────────────────────────────────────────────────────────────── + +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); +builder.Services.AddSingleton(); + +// ─── 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(); diff --git a/Properties/launchSettings.json b/Properties/launchSettings.json new file mode 100644 index 0000000..818ff0f --- /dev/null +++ b/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" + } + } + } +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..3a3988d --- /dev/null +++ b/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: +``` + +## 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) diff --git a/Services/AuditLogger.cs b/Services/AuditLogger.cs new file mode 100644 index 0000000..3920349 --- /dev/null +++ b/Services/AuditLogger.cs @@ -0,0 +1,55 @@ +using System.Text.Json; + +namespace ObsidianMcp.Services; + +/// +/// 写操作审计日志（JSON lines 格式，按天 rotate）。 +/// 输出到 /app/logs/audit-YYYY-MM-DD.log。 +/// 注册为 Singleton，内部用 lock 保证多线程写入安全。 +/// +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); + } + + /// + /// 记录一次写操作审计条目。 + /// + 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); + } + } +} diff --git a/Services/VaultPathResolver.cs b/Services/VaultPathResolver.cs new file mode 100644 index 0000000..c848aa2 --- /dev/null +++ b/Services/VaultPathResolver.cs @@ -0,0 +1,141 @@ +using ObsidianMcp.Config; +using Microsoft.Extensions.Options; + +namespace ObsidianMcp.Services; + +/// +/// Vault 路径安全守卫（chroot 语义）。 +/// +/// 职责： +/// - 把相对路径拼接到 VaultRoot，防止路径穿越（../） +/// - 拒绝绝对路径输入 +/// - 拒绝命中黑名单的路径段 +/// +/// 线程安全，注册为 Singleton。 +/// +public class VaultPathResolver +{ + // hardcode 黑名单路径段（任意路径段命中即拒） + private static readonly HashSet HardcodeBlacklist = + new(StringComparer.OrdinalIgnoreCase) + { + "01-Secret", + ".obsidian", + ".trash", + ".git", + }; + + private readonly string _root; + private readonly HashSet _blacklist; + + public VaultPathResolver(IOptions opts) + { + var o = opts.Value; + _root = Path.GetFullPath(o.Root); + + // 合并 hardcode + env 配置的黑名单，去重 + _blacklist = new HashSet(HardcodeBlacklist, StringComparer.OrdinalIgnoreCase); + foreach (var b in o.Blacklist) + if (!string.IsNullOrWhiteSpace(b)) + _blacklist.Add(b.Trim()); + } + + /// 返回 vault 根目录的绝对路径（规范化后）。 + public string VaultRoot => _root; + + /// + /// 将相对路径解析为 vault 内的绝对路径。 + /// + /// 可能抛出： + /// UnauthorizedAccessException — 路径穿越、绝对路径、命中黑名单、目标是 symlink + /// ArgumentException — relativePath 为空 + /// + 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; + } + + /// + /// 检查路径自身（以及任一父级路径段）是否是 symlink。是 → 拒绝。 + /// 防御链外文件 leak（例如有人在 vault 里建一个指向 /etc/passwd 的软链）。 + /// + 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; + } + } + + /// 检查绝对路径是否在 vault root 下（含等于 root）。 + private bool IsUnderRoot(string absPath) + { + return absPath == _root + || absPath.StartsWith(_root + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase); + } + + /// 逐个路径段检查黑名单。 + 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}"); + } + } +} diff --git a/Services/VaultSearchService.cs b/Services/VaultSearchService.cs new file mode 100644 index 0000000..78e4f4d --- /dev/null +++ b/Services/VaultSearchService.cs @@ -0,0 +1,104 @@ +using Microsoft.Extensions.FileSystemGlobbing; +using Microsoft.Extensions.FileSystemGlobbing.Abstractions; + +namespace ObsidianMcp.Services; + +/// +/// Vault 全文搜索服务。 +/// 纯 C# 实现，大小写不敏感子串匹配（不支持 regex）。 +/// V3 可替换为 ripgrep 调用。 +/// +public class VaultSearchService +{ + private readonly VaultPathResolver _resolver; + + public VaultSearchService(VaultPathResolver resolver) + { + _resolver = resolver; + } + + /// 大小写不敏感的子串 + /// glob 过滤，例如 "NAS/**/*.md"，为 null 时搜全 vault + /// 最多返回条数 + /// CancellationToken + public async Task> SearchAsync( + string query, + string? glob, + int limit, + CancellationToken ct = default) + { + var root = _resolver.VaultRoot; + var files = GetFilesToSearch(root, glob); + + var hits = new List(); + 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 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 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; } = ""; +} diff --git a/Services/VaultWriteGuard.cs b/Services/VaultWriteGuard.cs new file mode 100644 index 0000000..de1d3f4 --- /dev/null +++ b/Services/VaultWriteGuard.cs @@ -0,0 +1,120 @@ +using ObsidianMcp.Config; +using Microsoft.Extensions.Options; + +namespace ObsidianMcp.Services; + +/// +/// 写入门禁——在路径安全（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 扩展。 +/// +public class VaultWriteGuard +{ + // 永禁写入的文件名（不含路径，任何目录下的同名文件都禁写） + private static readonly HashSet 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 opts) + { + _resolver = resolver; + _extraWhitelist = opts.Value.WriteWhitelist ?? []; + } + + /// + /// 校验相对路径是否允许写入。 + /// 通过则返回规范化后的绝对路径；不通过则抛 UnauthorizedAccessException。 + /// + 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; + } + + /// 统一用 / 作分隔符，用于白名单匹配。 + private static string NormalizeRelative(string path) => + path.Replace('\\', '/'); +} diff --git a/Tools/AppendFileTool.cs b/Tools/AppendFileTool.cs new file mode 100644 index 0000000..6d36b34 --- /dev/null +++ b/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 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"; +} + +/// 写入操作的返回值。 +public class WriteResult +{ + public bool Ok { get; set; } + public int WrittenBytes { get; set; } +} diff --git a/Tools/GetMetadataTool.cs b/Tools/GetMetadataTool.cs new file mode 100644 index 0000000..bef47b3 --- /dev/null +++ b/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; } +} diff --git a/Tools/ListFilesTool.cs b/Tools/ListFilesTool.cs new file mode 100644 index 0000000..c1d982a --- /dev/null +++ b/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 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(); + + // 子目录（排除隐藏和黑名单） + 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; + } +} diff --git a/Tools/ListVaultTreeTool.cs b/Tools/ListVaultTreeTool.cs new file mode 100644 index 0000000..fb0b2cc --- /dev/null +++ b/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 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 }; + } +} diff --git a/Tools/ReadFileTool.cs b/Tools/ReadFileTool.cs new file mode 100644 index 0000000..cb923de --- /dev/null +++ b/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 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); + } +} diff --git a/Tools/SearchTool.cs b/Tools/SearchTool.cs new file mode 100644 index 0000000..37d2d98 --- /dev/null +++ b/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> 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); + } +} diff --git a/Tools/WriteFileTool.cs b/Tools/WriteFileTool.cs new file mode 100644 index 0000000..6c0fe84 --- /dev/null +++ b/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 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"; +} diff --git a/appsettings.Development.json b/appsettings.Development.json new file mode 100644 index 0000000..0c208ae --- /dev/null +++ b/appsettings.Development.json @@ -0,0 +1,8 @@ +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft.AspNetCore": "Warning" + } + } +} diff --git a/appsettings.Production.json b/appsettings.Production.json new file mode 100644 index 0000000..e614125 --- /dev/null +++ b/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" + } +} diff --git a/appsettings.json b/appsettings.json new file mode 100644 index 0000000..34e2f17 --- /dev/null +++ b/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" + } +} diff --git a/obsidian-mcp.csproj b/obsidian-mcp.csproj new file mode 100644 index 0000000..2c3c2cf --- /dev/null +++ b/obsidian-mcp.csproj @@ -0,0 +1,22 @@ + + + + net10.0 + enable + enable + ObsidianMcp + obsidian-mcp + + + + + + + + + + + + + +