gitea-mcp: 初次落地 Gitea MCP Server (.NET 10, V1 only-read)

把 Gitea (git.zhengchentao.win) 通过 MCP 暴露给 Claude.ai：列 repo、读代码、看 commits / issues / PR / orgs / packages / actions。
设计文档见 vault Coding/gitea-mcp/gitea-mcp 设计.md。
代码模板复用 obsidian-mcp（.NET 10 + ModelContextProtocol SDK + JwtBearer）。

19 个只读 Tool（全部 scope=read:gitea）：

Repo / 文件：
- list_repos / read_repo
- list_tree（max_entries=500 防爆）
- read_file（max_bytes=1MB，超出 truncated=true）
- search_code（走 /repos/search-code，indexer 未启用时返回结构化错误说明）

分支 / 提交：
- list_branches / list_commits / read_commit（diff 文件数限 50）

Issue / PR：
- list_issues / read_issue（含评论）
- list_pulls / read_pull（含评论 + 改动文件列表）

Org / Package（用户额外授权 read:organization + read:package）：
- list_orgs / read_org
- list_packages / read_package

Gitea Actions（运维友好）：
- list_workflow_runs / read_run_log

技术栈：
- .NET 10 + ModelContextProtocol SDK 1.0
- HttpClientFactory + Microsoft.Extensions.Http.Resilience（指数 backoff，5xx/429/网络错误重试）
- JwtBearer (HS256, Current+Previous fallback, MapInboundClaims=false)
- aud=gitea, scope=read:gitea, iss=https://auth.zhengchentao.win

Gitea API client：
- Authorization: token <PAT> (admin PAT，仅 read scope)
- BaseUrl=https://git.zhengchentao.win
- 错误映射：401/403 → UnauthorizedAccessException，404 → KeyNotFoundException，5xx → InvalidOperationException
- RepoBlacklist 黑名单（owner/repo 精确匹配，默认空）

部署：
- Dockerfile multi-stage，COPY --chown，non-root user
- .gitea/workflows/build-image.yml：build + deploy 双 job，buildkit v0.13.2
- 容器内 :8080，宿主端口 9092
- 子域名 git-mcp.zhengchentao.win（区别于 Gitea 本体 git.zhengchentao.win）

测试：6/6 单测过（GiteaRepoFilter 黑名单匹配）

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

Auth/JwtBearerSetup.cs

@@ -0,0 +1,68 @@
+using GiteaMcp.Config;
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.IdentityModel.Tokens;
+using System.Text;
+
+namespace GiteaMcp.Auth;
+
+/// <summary>
+/// JWT Bearer 验签配置，与 obsidian-mcp 同款 HS256 对称密钥方案。
+/// ValidIssuer = https://auth.zhengchentao.win，ValidAudience = gitea。
+/// 支持 Current + Previous 双密钥（轮换窗口）。
+/// </summary>
+public static class JwtBearerSetup
+{
+    public static IServiceCollection AddGiteaJwtBearer(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        var jwtOpts = configuration.GetSection(JwtOptions.SectionName).Get<JwtOptions>()
+            ?? new JwtOptions();
+
+        services
+            .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+            .AddJwtBearer(options =>
+            {
+                // 关闭默认的入站 claim type 映射，否则 "sub"/"scope" 会被改写成
+                // ClaimTypes.NameIdentifier 之类的长 URI，下游 FindFirst("scope") 取不到。
+                options.MapInboundClaims = false;
+
+                options.TokenValidationParameters = new TokenValidationParameters
+                {
+                    ValidateIssuer = true,
+                    ValidIssuer = jwtOpts.Issuer,
+
+                    ValidateAudience = true,
+                    ValidAudience = jwtOpts.Audience,
+
+                    ValidateIssuerSigningKey = true,
+                    // ToList 物化一次，避免每次验签重建 SymmetricSecurityKey。
+                    IssuerSigningKeys = BuildSigningKeys(jwtOpts).ToList(),
+
+                    ValidateLifetime = true,
+                    // nas-auth 设计里允许 2 分钟时钟偏差
+                    ClockSkew = TimeSpan.FromMinutes(2),
+                };
+            });
+
+        return services;
+    }
+
+    /// <summary>
+    /// 构建 Current + Previous 双密钥列表，供 SDK 依次尝试验签。
+    /// 轮换期间两把钥匙同时有效，过期的旧 Token 会被 ValidateLifetime 自然拦截。
+    /// Current 未配置直接抛错，避免容器静默以"任何 token 都不通过"的状态运行。
+    /// </summary>
+    private static IEnumerable<SecurityKey> BuildSigningKeys(JwtOptions opts)
+    {
+        if (string.IsNullOrWhiteSpace(opts.SigningKeyCurrent))
+            throw new InvalidOperationException(
+                "Jwt:SigningKeyCurrent 未配置，gitea-mcp 无法启动。" +
+                "请在 .env.shared 设置 JWT_SIGNING_KEY_CURRENT 与 nas-auth 共用。");
+
+        yield return new SymmetricSecurityKey(Encoding.UTF8.GetBytes(opts.SigningKeyCurrent));
+
+        if (!string.IsNullOrWhiteSpace(opts.SigningKeyPrevious))
+            yield return new SymmetricSecurityKey(Encoding.UTF8.GetBytes(opts.SigningKeyPrevious));
+    }
+}

Auth/ScopePolicies.cs

@@ -0,0 +1,59 @@
+using Microsoft.AspNetCore.Authorization;
+
+namespace GiteaMcp.Auth;
+
+/// <summary>
+/// 自定义 scope 授权策略：要求 JWT 的 scope claim 包含指定值。
+/// 对应 RequireScope("read:gitea") policy。
+/// </summary>
+public static class ScopePolicies
+{
+    public const string ReadGitea = "read:gitea";
+
+    public static IServiceCollection AddScopePolicies(this IServiceCollection services)
+    {
+        services.AddAuthorizationBuilder()
+            .AddPolicy(ReadGitea, policy =>
+            {
+                policy.RequireAuthenticatedUser();
+                policy.AddRequirements(new ScopeRequirement(ReadGitea));
+            });
+
+        services.AddSingleton<IAuthorizationHandler, ScopeRequirementHandler>();
+        return services;
+    }
+}
+
+/// <summary>
+/// 授权要求：JWT scope claim 必须包含指定的 scope 字符串（空格分隔的多 scope 支持）。
+/// </summary>
+public class ScopeRequirement(string scope) : IAuthorizationRequirement
+{
+    public string Scope { get; } = scope;
+}
+
+/// <summary>
+/// 验证 scope claim。
+/// nas-auth 签发的 JWT 里 scope 是单字符串（空格分隔），形如 "read:gitea" 或 "read:gitea write:gitea"。
+/// 兼容部分实现把多 scope 拆成多个 claim 的形式（FindAll）。
+/// OAuth 2.0 (RFC 6749 §3.3) 规定 scope 大小写敏感。
+/// </summary>
+public class ScopeRequirementHandler : AuthorizationHandler<ScopeRequirement>
+{
+    protected override Task HandleRequirementAsync(
+        AuthorizationHandlerContext context,
+        ScopeRequirement requirement)
+    {
+        var scopes = context.User
+            .FindAll("scope")
+            .SelectMany(c => c.Value.Split(' ', StringSplitOptions.RemoveEmptyEntries))
+            .ToHashSet(StringComparer.Ordinal);
+
+        if (scopes.Contains(requirement.Scope))
+        {
+            context.Succeed(requirement);
+        }
+
+        return Task.CompletedTask;
+    }
+}