gitea-mcp: 初次落地 Gitea MCP Server (.NET 10, V1 only-read)
Build Docker Image / build (push) Failing after 5m41s
Build Docker Image / deploy (push) Has been skipped

把 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>
This commit is contained in:
2026-05-06 01:32:42 +08:00
commit c7fa6aeb7f
38 changed files with 2675 additions and 0 deletions
+98
View File
@@ -0,0 +1,98 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
/// <summary>Gitea commit 摘要(list_commits 使用)</summary>
public class GiteaCommitSummary
{
[JsonPropertyName("sha")]
public string Sha { get; set; } = string.Empty;
[JsonPropertyName("created")]
public DateTimeOffset Created { get; set; }
[JsonPropertyName("commit")]
public GiteaCommitDetail? Commit { get; set; }
[JsonPropertyName("author")]
public GiteaUser? Author { get; set; }
}
public class GiteaCommitDetail
{
[JsonPropertyName("message")]
public string Message { get; set; } = string.Empty;
[JsonPropertyName("author")]
public GiteaCommitSignature? Author { get; set; }
[JsonPropertyName("committer")]
public GiteaCommitSignature? Committer { get; set; }
}
public class GiteaCommitSignature
{
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
[JsonPropertyName("email")]
public string Email { get; set; } = string.Empty;
[JsonPropertyName("date")]
public DateTimeOffset Date { get; set; }
}
/// <summary>read_commit 使用的完整 commit(含 diff 文件列表)</summary>
public class GiteaCommitFull
{
[JsonPropertyName("sha")]
public string Sha { get; set; } = string.Empty;
[JsonPropertyName("created")]
public DateTimeOffset Created { get; set; }
[JsonPropertyName("commit")]
public GiteaCommitDetail? Commit { get; set; }
[JsonPropertyName("author")]
public GiteaUser? Author { get; set; }
[JsonPropertyName("files")]
public List<GiteaCommitFile>? Files { get; set; }
[JsonPropertyName("stats")]
public GiteaCommitStats? Stats { get; set; }
}
public class GiteaCommitFile
{
[JsonPropertyName("filename")]
public string Filename { get; set; } = string.Empty;
[JsonPropertyName("status")]
public string Status { get; set; } = string.Empty;
[JsonPropertyName("additions")]
public int Additions { get; set; }
[JsonPropertyName("deletions")]
public int Deletions { get; set; }
[JsonPropertyName("changes")]
public int Changes { get; set; }
[JsonPropertyName("patch")]
public string? Patch { get; set; }
}
public class GiteaCommitStats
{
[JsonPropertyName("total")]
public int Total { get; set; }
[JsonPropertyName("additions")]
public int Additions { get; set; }
[JsonPropertyName("deletions")]
public int Deletions { get; set; }
}
+69
View File
@@ -0,0 +1,69 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
public class GiteaIssue
{
[JsonPropertyName("number")]
public int Number { get; set; }
[JsonPropertyName("title")]
public string Title { get; set; } = string.Empty;
[JsonPropertyName("body")]
public string? Body { get; set; }
[JsonPropertyName("state")]
public string State { get; set; } = string.Empty;
[JsonPropertyName("html_url")]
public string HtmlUrl { get; set; } = string.Empty;
[JsonPropertyName("user")]
public GiteaUser? User { get; set; }
[JsonPropertyName("labels")]
public List<GiteaLabel>? Labels { get; set; }
[JsonPropertyName("assignees")]
public List<GiteaUser>? Assignees { get; set; }
[JsonPropertyName("created_at")]
public DateTimeOffset CreatedAt { get; set; }
[JsonPropertyName("updated_at")]
public DateTimeOffset UpdatedAt { get; set; }
[JsonPropertyName("closed_at")]
public DateTimeOffset? ClosedAt { get; set; }
[JsonPropertyName("comments")]
public int Comments { get; set; }
}
public class GiteaLabel
{
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
[JsonPropertyName("color")]
public string Color { get; set; } = string.Empty;
}
public class GiteaComment
{
[JsonPropertyName("id")]
public long Id { get; set; }
[JsonPropertyName("body")]
public string? Body { get; set; }
[JsonPropertyName("user")]
public GiteaUser? User { get; set; }
[JsonPropertyName("created_at")]
public DateTimeOffset CreatedAt { get; set; }
[JsonPropertyName("updated_at")]
public DateTimeOffset UpdatedAt { get; set; }
}
+43
View File
@@ -0,0 +1,43 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
public class GiteaOrg
{
[JsonPropertyName("id")]
public long Id { get; set; }
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
[JsonPropertyName("full_name")]
public string? FullName { get; set; }
[JsonPropertyName("description")]
public string? Description { get; set; }
[JsonPropertyName("website")]
public string? Website { get; set; }
[JsonPropertyName("location")]
public string? Location { get; set; }
[JsonPropertyName("avatar_url")]
public string? AvatarUrl { get; set; }
[JsonPropertyName("repo_admin_change_team_access")]
public bool RepoAdminChangeTeamAccess { get; set; }
[JsonPropertyName("visibility")]
public string? Visibility { get; set; }
}
/// <summary>/api/v1/orgs/search 的响应包装(顶层 { ok, data })。</summary>
public class GiteaOrgSearchResult
{
[JsonPropertyName("ok")]
public bool Ok { get; set; }
[JsonPropertyName("data")]
public List<GiteaOrg> Data { get; set; } = [];
}
+27
View File
@@ -0,0 +1,27 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
public class GiteaPackage
{
[JsonPropertyName("id")]
public long Id { get; set; }
[JsonPropertyName("owner")]
public GiteaUser? Owner { get; set; }
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
[JsonPropertyName("type")]
public string Type { get; set; } = string.Empty;
[JsonPropertyName("version")]
public string Version { get; set; } = string.Empty;
[JsonPropertyName("creator")]
public GiteaUser? Creator { get; set; }
[JsonPropertyName("created")]
public DateTimeOffset Created { get; set; }
}
+85
View File
@@ -0,0 +1,85 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
public class GiteaPullRequest
{
[JsonPropertyName("number")]
public int Number { get; set; }
[JsonPropertyName("title")]
public string Title { get; set; } = string.Empty;
[JsonPropertyName("body")]
public string? Body { get; set; }
[JsonPropertyName("state")]
public string State { get; set; } = string.Empty;
[JsonPropertyName("html_url")]
public string HtmlUrl { get; set; } = string.Empty;
[JsonPropertyName("user")]
public GiteaUser? User { get; set; }
[JsonPropertyName("head")]
public GiteaPrRef? Head { get; set; }
[JsonPropertyName("base")]
public GiteaPrRef? Base { get; set; }
[JsonPropertyName("merged")]
public bool Merged { get; set; }
[JsonPropertyName("mergeable")]
public bool? Mergeable { get; set; }
[JsonPropertyName("created_at")]
public DateTimeOffset CreatedAt { get; set; }
[JsonPropertyName("updated_at")]
public DateTimeOffset UpdatedAt { get; set; }
[JsonPropertyName("closed_at")]
public DateTimeOffset? ClosedAt { get; set; }
[JsonPropertyName("merged_at")]
public DateTimeOffset? MergedAt { get; set; }
[JsonPropertyName("labels")]
public List<GiteaLabel>? Labels { get; set; }
}
public class GiteaPrRef
{
[JsonPropertyName("label")]
public string? Label { get; set; }
[JsonPropertyName("ref")]
public string Ref { get; set; } = string.Empty;
[JsonPropertyName("sha")]
public string Sha { get; set; } = string.Empty;
[JsonPropertyName("repo")]
public GiteaRepo? Repo { get; set; }
}
/// <summary>PR 变更文件(read_pull 附带返回)</summary>
public class GiteaPrFile
{
[JsonPropertyName("filename")]
public string Filename { get; set; } = string.Empty;
[JsonPropertyName("status")]
public string Status { get; set; } = string.Empty;
[JsonPropertyName("additions")]
public int Additions { get; set; }
[JsonPropertyName("deletions")]
public int Deletions { get; set; }
[JsonPropertyName("changes")]
public int Changes { get; set; }
}
+80
View File
@@ -0,0 +1,80 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
/// <summary>Gitea 仓库元数据(list_repos / read_repo 使用)</summary>
public class GiteaRepo
{
[JsonPropertyName("id")]
public long Id { get; set; }
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
[JsonPropertyName("full_name")]
public string FullName { get; set; } = string.Empty;
[JsonPropertyName("description")]
public string? Description { get; set; }
[JsonPropertyName("private")]
public bool Private { get; set; }
[JsonPropertyName("fork")]
public bool Fork { get; set; }
[JsonPropertyName("mirror")]
public bool Mirror { get; set; }
[JsonPropertyName("archived")]
public bool Archived { get; set; }
[JsonPropertyName("html_url")]
public string HtmlUrl { get; set; } = string.Empty;
[JsonPropertyName("clone_url")]
public string CloneUrl { get; set; } = string.Empty;
[JsonPropertyName("default_branch")]
public string DefaultBranch { get; set; } = "main";
[JsonPropertyName("stars_count")]
public int StarsCount { get; set; }
[JsonPropertyName("forks_count")]
public int ForksCount { get; set; }
[JsonPropertyName("size")]
public long Size { get; set; }
[JsonPropertyName("website")]
public string? Website { get; set; }
[JsonPropertyName("topics")]
public List<string>? Topics { get; set; }
[JsonPropertyName("updated_at")]
public DateTimeOffset UpdatedAt { get; set; }
[JsonPropertyName("owner")]
public GiteaUser? Owner { get; set; }
}
public class GiteaUser
{
[JsonPropertyName("login")]
public string Login { get; set; } = string.Empty;
[JsonPropertyName("full_name")]
public string? FullName { get; set; }
}
/// <summary>搜索仓库的 API 响应包装</summary>
public class GiteaRepoSearchResult
{
[JsonPropertyName("data")]
public List<GiteaRepo> Data { get; set; } = [];
[JsonPropertyName("ok")]
public bool Ok { get; set; }
}
+50
View File
@@ -0,0 +1,50 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
/// <summary>代码搜索结果条目(search_code 使用)</summary>
public class GiteaSearchHit
{
/// <summary>仓库所有者</summary>
public string Owner { get; set; } = string.Empty;
/// <summary>仓库名称</summary>
public string Repo { get; set; } = string.Empty;
/// <summary>命中的文件路径(相对仓库根)</summary>
public string Path { get; set; } = string.Empty;
/// <summary>命中的行号(1-basedGitea 索引未启用时为 0</summary>
public int Line { get; set; }
/// <summary>命中行的前后上下文预览(Gitea 返回原始片段)</summary>
public string Preview { get; set; } = string.Empty;
}
/// <summary>Gitea code search API 返回的单条结果</summary>
public class GiteaCodeSearchResult
{
[JsonPropertyName("filename")]
public string Filename { get; set; } = string.Empty;
[JsonPropertyName("language")]
public string? Language { get; set; }
[JsonPropertyName("content")]
public string? Content { get; set; }
[JsonPropertyName("commit_id")]
public string? CommitId { get; set; }
[JsonPropertyName("repo")]
public GiteaRepo? Repo { get; set; }
}
public class GiteaCodeSearchResponse
{
[JsonPropertyName("ok")]
public bool Ok { get; set; }
[JsonPropertyName("data")]
public List<GiteaCodeSearchResult> Data { get; set; } = [];
}
+69
View File
@@ -0,0 +1,69 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
/// <summary>Git tree 中的单个条目(list_tree 使用)</summary>
public class GiteaTreeEntry
{
[JsonPropertyName("path")]
public string Path { get; set; } = string.Empty;
[JsonPropertyName("mode")]
public string? Mode { get; set; }
/// <summary>"blob"(文件)/ "tree"(目录)/ "commit"(子模块)</summary>
[JsonPropertyName("type")]
public string Type { get; set; } = string.Empty;
[JsonPropertyName("size")]
public long? Size { get; set; }
[JsonPropertyName("sha")]
public string? Sha { get; set; }
[JsonPropertyName("url")]
public string? Url { get; set; }
}
public class GiteaTree
{
[JsonPropertyName("sha")]
public string Sha { get; set; } = string.Empty;
[JsonPropertyName("url")]
public string? Url { get; set; }
[JsonPropertyName("tree")]
public List<GiteaTreeEntry> Tree { get; set; } = [];
[JsonPropertyName("truncated")]
public bool Truncated { get; set; }
}
/// <summary>分支信息(list_branches 使用)</summary>
public class GiteaBranch
{
[JsonPropertyName("name")]
public string Name { get; set; } = string.Empty;
[JsonPropertyName("commit")]
public GiteaBranchCommit? Commit { get; set; }
[JsonPropertyName("protected")]
public bool Protected { get; set; }
}
public class GiteaBranchCommit
{
[JsonPropertyName("id")]
public string Id { get; set; } = string.Empty;
[JsonPropertyName("message")]
public string? Message { get; set; }
[JsonPropertyName("timestamp")]
public DateTimeOffset Timestamp { get; set; }
[JsonPropertyName("author")]
public GiteaCommitSignature? Author { get; set; }
}
+84
View File
@@ -0,0 +1,84 @@
using System.Text.Json.Serialization;
namespace GiteaMcp.Services.Models;
public class GiteaWorkflowRun
{
[JsonPropertyName("id")]
public long Id { get; set; }
[JsonPropertyName("name")]
public string? Name { get; set; }
[JsonPropertyName("head_branch")]
public string? HeadBranch { get; set; }
[JsonPropertyName("head_sha")]
public string? HeadSha { get; set; }
[JsonPropertyName("event")]
public string? Event { get; set; }
[JsonPropertyName("status")]
public string? Status { get; set; }
[JsonPropertyName("conclusion")]
public string? Conclusion { get; set; }
[JsonPropertyName("workflow_id")]
public long WorkflowId { get; set; }
[JsonPropertyName("url")]
public string? Url { get; set; }
[JsonPropertyName("html_url")]
public string? HtmlUrl { get; set; }
[JsonPropertyName("created_at")]
public DateTimeOffset CreatedAt { get; set; }
[JsonPropertyName("updated_at")]
public DateTimeOffset UpdatedAt { get; set; }
[JsonPropertyName("actor")]
public GiteaUser? Actor { get; set; }
}
public class GiteaWorkflowRunList
{
[JsonPropertyName("workflow_runs")]
public List<GiteaWorkflowRun> WorkflowRuns { get; set; } = [];
[JsonPropertyName("total_count")]
public int TotalCount { get; set; }
}
public class GiteaWorkflowJob
{
[JsonPropertyName("id")]
public long Id { get; set; }
[JsonPropertyName("name")]
public string? Name { get; set; }
[JsonPropertyName("status")]
public string? Status { get; set; }
[JsonPropertyName("conclusion")]
public string? Conclusion { get; set; }
[JsonPropertyName("started_at")]
public DateTimeOffset? StartedAt { get; set; }
[JsonPropertyName("completed_at")]
public DateTimeOffset? CompletedAt { get; set; }
}
public class GiteaWorkflowJobList
{
[JsonPropertyName("workflow_jobs")]
public List<GiteaWorkflowJob> WorkflowJobs { get; set; } = [];
[JsonPropertyName("total_count")]
public int TotalCount { get; set; }
}