GitHub MCP Server - 仓库管理模块深度分析

classDiagram
    class RepositoriesToolset {
        +name: "repos"
        +description: "GitHub Repository related tools"
        +readTools: []ServerTool
        +writeTools: []ServerTool
        +resourceTemplates: []ServerResourceTemplate
    }

    class RepositoryQuerying {
        +SearchRepositories()
        +SearchCode()
        +GetFileContents()
        +ListCommits()
        +GetCommit()
    }

    class BranchTagManagement {
        +ListBranches()
        +CreateBranch() 
        +ListTags()
        +GetTag()
        +ListReleases()
        +GetLatestRelease()
        +GetReleaseByTag()
    }

    class FileOperations {
        +CreateOrUpdateFile()
        +DeleteFile()
        +PushFiles()
        +resolveGitReference()
        +filterPaths()
    }

    class RepositoryManagement {
        +CreateRepository()
        +ForkRepository()
        +StarRepository()
        +UnstarRepository()
        +ListStarredRepositories()
    }

    class ResourceTemplates {
        +GetRepositoryResourceContent()
        +GetRepositoryResourceBranchContent()
        +GetRepositoryResourceCommitContent()
        +GetRepositoryResourceTagContent()
        +GetRepositoryResourcePrContent()
    }

    class APIStrategy {
        +REST API Client
        +GraphQL API Client
        +Raw Content API Client
        +Smart API Selection
    }

    RepositoriesToolset --> RepositoryQuerying
    RepositoriesToolset --> BranchTagManagement
    RepositoriesToolset --> FileOperations
    RepositoriesToolset --> RepositoryManagement
    RepositoriesToolset --> ResourceTemplates
    RepositoryQuerying --> APIStrategy
    FileOperations --> APIStrategy

// 位置: pkg/github/repositories.go:485-678
func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("get_file_contents",
        mcp.WithDescription("Get the contents of a file or directory from a GitHub repository with intelligent API selection"),
        
        // 灵活的引用参数
        mcp.WithString("path", mcp.Description("Path to file/directory (directories must end with a slash '/')"), mcp.DefaultString("/")),
        mcp.WithString("ref", mcp.Description("Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`")),
        mcp.WithString("sha", mcp.Description("Accepts optional commit SHA. If specified, it will be used instead of ref")),
    ),
    
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        // 参数解析
        owner, _ := RequiredParam[string](request, "owner")
        repo, _ := RequiredParam[string](request, "repo")
        path, _ := RequiredParam[string](request, "path")
        ref, _ := OptionalParam[string](request, "ref")
        sha, _ := OptionalParam[string](request, "sha")
        
        // 获取客户端
        client, err := getClient(ctx)
        if err != nil {
            return mcp.NewToolResultError("failed to get GitHub client"), nil
        }
        
        // 关键函数：解析Git引用
        rawOpts, err := resolveGitReference(ctx, client, owner, repo, ref, sha)
        if err != nil {
            return mcp.NewToolResultError(fmt.Sprintf("failed to resolve git reference: %s", err)), nil
        }
        
        // 策略1: 文件内容获取 - 优先使用Raw API
        if path != "" && !strings.HasSuffix(path, "/") {
            return handleFileContent(ctx, client, getRawClient, owner, repo, path, ref, rawOpts)
        }
        
        // 策略2: 目录内容获取 - 使用REST API
        if strings.HasSuffix(path, "/") {
            return handleDirectoryContent(ctx, client, owner, repo, path, ref)
        }
        
        // 策略3: 模糊路径匹配 - 使用Git Tree API
        return handlePathMatching(ctx, client, owner, repo, path, ref, rawOpts)
    }
}

// 文件内容处理策略
func handleFileContent(ctx context.Context, client *github.Client, getRawClient raw.GetRawClientFn, owner, repo, path, ref string, rawOpts *raw.ContentOpts) (*mcp.CallToolResult, error) {
    // 阶段1: 获取文件元信息（REST API）
    opts := &github.RepositoryContentGetOptions{Ref: ref}
    fileContent, _, respContents, err := client.Repositories.GetContents(ctx, owner, repo, path, opts)
    if err != nil {
        return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get file SHA", respContents, err), nil
    }
    defer respContents.Body.Close()
    
    if fileContent == nil || fileContent.SHA == nil {
        return mcp.NewToolResultError("file content SHA is nil"), nil
    }
    fileSHA := *fileContent.SHA
    
    // 阶段2: 使用Raw API下载文件内容（性能优化）
    rawClient, err := getRawClient(ctx)
    if err != nil {
        return mcp.NewToolResultError("failed to get GitHub raw content client"), nil
    }
    
    resp, err := rawClient.GetRawContent(ctx, owner, repo, path, rawOpts)
    if err != nil {
        return mcp.NewToolResultError("failed to get raw repository content"), nil
    }
    defer resp.Body.Close()
    
    if resp.StatusCode == http.StatusOK {
        // 阶段3: 内容类型检测和处理
        body, err := io.ReadAll(resp.Body)
        if err != nil {
            return mcp.NewToolResultError("failed to read response body"), nil
        }
        
        contentType := resp.Header.Get("Content-Type")
        
        // 构建资源URI
        var resourceURI string
        switch {
        case rawOpts.SHA != "":
            resourceURI, _ = url.JoinPath("repo://", owner, repo, "sha", rawOpts.SHA, "contents", path)
        case rawOpts.Ref != "":
            resourceURI, _ = url.JoinPath("repo://", owner, repo, rawOpts.Ref, "contents", path)
        default:
            resourceURI, _ = url.JoinPath("repo://", owner, repo, "contents", path)
        }
        
        // 阶段4: 根据内容类型返回不同格式
        if strings.HasPrefix(contentType, "application") || strings.HasPrefix(contentType, "text") {
            // 文本内容
            result := mcp.TextResourceContents{
                URI:      resourceURI,
                Text:     string(body),
                MIMEType: contentType,
            }
            return mcp.NewToolResultResource(fmt.Sprintf("successfully downloaded text file (SHA: %s)", fileSHA), result), nil
        }
        
        // 二进制内容
        result := mcp.BlobResourceContents{
            URI:      resourceURI,
            Blob:     base64.StdEncoding.EncodeToString(body),
            MIMEType: contentType,
        }
        return mcp.NewToolResultResource(fmt.Sprintf("successfully downloaded binary file (SHA: %s)", fileSHA), result), nil
    }
    
    return mcp.NewToolResultError("failed to download file content"), nil
}

// 位置: pkg/github/repositories.go:1615-1685
func resolveGitReference(ctx context.Context, githubClient *github.Client, owner, repo, ref, sha string) (*raw.ContentOpts, error) {
    // 优先级1: 如果提供了明确的SHA，直接使用
    if sha != "" {
        return &raw.ContentOpts{Ref: "", SHA: sha}, nil
    }
    
    originalRef := ref
    var reference *github.Reference
    var resp *github.Response
    var err error
    
    // 优先级2: 引用解析策略
    switch {
    case originalRef == "":
        // 2a. 空引用：获取默认分支
        repoInfo, resp, err := githubClient.Repositories.Get(ctx, owner, repo)
        if err != nil {
            return nil, fmt.Errorf("failed to get repository info: %w", err)
        }
        ref = fmt.Sprintf("refs/heads/%s", repoInfo.GetDefaultBranch())
        
    case strings.HasPrefix(originalRef, "refs/"):
        // 2b. 完全限定引用：refs/heads/main, refs/tags/v1.0.0
        // 直接使用，稍后统一获取
        
    case strings.HasPrefix(originalRef, "heads/") || strings.HasPrefix(originalRef, "tags/"):
        // 2c. 部分限定引用：heads/main, tags/v1.0.0
        ref = "refs/" + originalRef
        
    default:
        // 2d. 短名称：main, v1.0.0 - 需要智能识别
        return resolveShortReference(ctx, githubClient, owner, repo, originalRef)
    }
    
    // 优先级3: 最终引用获取
    if reference == nil {
        reference, resp, err = githubClient.Git.GetRef(ctx, owner, repo, ref)
        if err != nil {
            return nil, fmt.Errorf("failed to get final reference for %q: %w", ref, err)
        }
    }
    
    sha = reference.GetObject().GetSHA()
    return &raw.ContentOpts{Ref: ref, SHA: sha}, nil
}

// 短名称引用解析（分支或标签）
func resolveShortReference(ctx context.Context, githubClient *github.Client, owner, repo, shortName string) (*raw.ContentOpts, error) {
    // 策略：先尝试分支，再尝试标签
    branchRef := "refs/heads/" + shortName
    reference, resp, err := githubClient.Git.GetRef(ctx, owner, repo, branchRef)
    
    if err == nil {
        // 找到分支
        sha := reference.GetObject().GetSHA()
        return &raw.ContentOpts{Ref: branchRef, SHA: sha}, nil
    }
    
    // 检查是否为404错误（分支不存在）
    if ghErr, isGhErr := err.(*github.ErrorResponse); isGhErr && ghErr.Response.StatusCode == http.StatusNotFound {
        // 尝试标签
        tagRef := "refs/tags/" + shortName
        reference, resp, err = githubClient.Git.GetRef(ctx, owner, repo, tagRef)
        
        if err == nil {
            // 找到标签
            sha := reference.GetObject().GetSHA()
            return &raw.ContentOpts{Ref: tagRef, SHA: sha}, nil
        }
        
        if ghErr2, isGhErr2 := err.(*github.ErrorResponse); isGhErr2 && ghErr2.Response.StatusCode == http.StatusNotFound {
            return nil, fmt.Errorf("could not resolve ref %q as a branch or a tag", shortName)
        }
    }
    
    return nil, fmt.Errorf("failed to resolve reference %q: %w", shortName, err)
}

// 位置: pkg/github/repositories.go:1040-1208
func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("push_files",
        mcp.WithDescription("Push multiple files to a GitHub repository in a single atomic commit"),
        
        // 复杂的文件数组参数
        mcp.WithArray("files", mcp.Required(),
            mcp.Items(map[string]interface{}{
                "type":                 "object",
                "additionalProperties": false,
                "required":             []string{"path", "content"},
                "properties": map[string]interface{}{
                    "path":    map[string]interface{}{"type": "string", "description": "path to the file"},
                    "content": map[string]interface{}{"type": "string", "description": "file content"},
                },
            }),
            mcp.Description("Array of file objects to push, each object with path (string) and content (string)"),
        ),
    ),
    
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        owner, _ := RequiredParam[string](request, "owner")
        repo, _ := RequiredParam[string](request, "repo")
        branch, _ := RequiredParam[string](request, "branch")
        message, _ := RequiredParam[string](request, "message")
        
        // 复杂的文件数组解析
        filesObj, ok := request.GetArguments()["files"].([]interface{})
        if !ok {
            return mcp.NewToolResultError("files parameter must be an array of objects with path and content"), nil
        }
        
        client, err := getClient(ctx)
        if err != nil {
            return nil, fmt.Errorf("failed to get GitHub client: %w", err)
        }
        
        // 阶段1: 获取分支引用
        ref, resp, err := client.Git.GetRef(ctx, owner, repo, "refs/heads/"+branch)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get branch reference", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 阶段2: 获取基础提交
        baseCommit, resp, err := client.Git.GetCommit(ctx, owner, repo, *ref.Object.SHA)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get base commit", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 阶段3: 构建树条目（原子性关键）
        var entries []*github.TreeEntry
        
        for _, file := range filesObj {
            fileMap, ok := file.(map[string]interface{})
            if !ok {
                return mcp.NewToolResultError("each file must be an object with path and content"), nil
            }
            
            path, ok := fileMap["path"].(string)
            if !ok || path == "" {
                return mcp.NewToolResultError("each file must have a path"), nil
            }
            
            content, ok := fileMap["content"].(string)
            if !ok {
                return mcp.NewToolResultError("each file must have content"), nil
            }
            
            // 创建树条目
            entries = append(entries, &github.TreeEntry{
                Path:    github.Ptr(path),
                Mode:    github.Ptr("100644"), // 常规文件模式
                Type:    github.Ptr("blob"),
                Content: github.Ptr(content),
            })
        }
        
        // 阶段4: 创建新的Git树（原子性操作）
        newTree, resp, err := client.Git.CreateTree(ctx, owner, repo, *baseCommit.Tree.SHA, entries)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to create tree", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 阶段5: 创建新提交
        commit := &github.Commit{
            Message: github.Ptr(message),
            Tree:    newTree,
            Parents: []*github.Commit{{SHA: baseCommit.SHA}},
        }
        
        newCommit, resp, err := client.Git.CreateCommit(ctx, owner, repo, commit, nil)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to create commit", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 阶段6: 更新分支引用（原子性完成）
        ref.Object.SHA = newCommit.SHA
        updatedRef, resp, err := client.Git.UpdateRef(ctx, owner, repo, ref, false)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to update reference", resp, err), nil
        }
        defer resp.Body.Close()
        
        return MarshalledTextResult(updatedRef), nil
    }
}

// 高级代码搜索实现
func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("search_code",
        mcp.WithDescription("Search code using GitHub's powerful code search syntax with advanced filtering"),
        
        // GitHub代码搜索的强大查询语法
        mcp.WithString("query", mcp.Required(), 
            mcp.Description("Search query using GitHub's powerful code search syntax. Examples: 'content:Skill language:Java org:github', 'NOT is:archived language:Python OR language:go', 'repo:github/github-mcp-server'. Supports exact matching, language filters, path filters, and more.")),
        
        // 排序选项
        mcp.WithString("sort", mcp.Description("Sort field ('indexed' only)"), mcp.Enum("indexed")),
        mcp.WithString("order", mcp.Description("Sort order for results"), mcp.Enum("asc", "desc")),
        WithPagination(),
    ),
    
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        query, _ := RequiredParam[string](request, "query")
        sort, _ := OptionalParam[string](request, "sort")
        order, _ := OptionalParam[string](request, "order")
        pagination, _ := OptionalPaginationParams(request)
        
        client, err := getClient(ctx)
        if err != nil {
            return nil, fmt.Errorf("failed to get GitHub client: %w", err)
        }
        
        // 构建搜索选项
        opts := &github.SearchOptions{
            Sort:  sort,
            Order: order,
            ListOptions: github.ListOptions{
                Page:    pagination.Page,
                PerPage: pagination.PerPage,
            },
        }
        
        // 执行代码搜索
        result, resp, err := client.Search.Code(ctx, query, opts)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to search code", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 优化搜索结果的显示
        optimizedResult := optimizeCodeSearchResult(result)
        return MarshalledTextResult(optimizedResult), nil
    }
}

// 代码搜索结果优化
func optimizeCodeSearchResult(result *github.CodeSearchResult) *OptimizedCodeSearchResult {
    optimized := &OptimizedCodeSearchResult{
        TotalCount:        result.GetTotal(),
        IncompleteResults: result.GetIncompleteResults(),
        Items:             make([]OptimizedCodeResult, 0, len(result.CodeResults)),
    }
    
    for _, item := range result.CodeResults {
        optimizedItem := OptimizedCodeResult{
            Name:       item.GetName(),
            Path:       item.GetPath(),
            SHA:        item.GetSHA(),
            HTMLURL:    item.GetHTMLURL(),
            Repository: convertToMinimalRepository(item.GetRepository()),
        }
        
        // 代码片段优化：只保留相关上下文
        if item.TextMatches != nil {
            optimizedItem.TextMatches = optimizeTextMatches(item.TextMatches)
        }
        
        optimized.Items = append(optimized.Items, optimizedItem)
    }
    
    return optimized
}

type OptimizedCodeResult struct {
    Name         string                 `json:"name"`
    Path         string                 `json:"path"`
    SHA          string                 `json:"sha"`
    HTMLURL      string                 `json:"html_url"`
    Repository   MinimalRepository      `json:"repository"`
    TextMatches  []OptimizedTextMatch   `json:"text_matches,omitempty"`
}

type OptimizedTextMatch struct {
    ObjectURL  string               `json:"object_url"`
    ObjectType string               `json:"object_type"`
    Fragment   string               `json:"fragment"`
    Matches    []OptimizedMatch     `json:"matches"`
}

type OptimizedMatch struct {
    Text     string    `json:"text"`
    Indices  []int     `json:"indices"`
}

sequenceDiagram
    participant Developer as Developer
    participant AI as AI Assistant  
    participant Handler as PushFiles Handler
    participant GitAPI as GitHub Git API
    participant Validator as File Validator
    participant AtomicOp as Atomic Operations
    
    Note over Developer, AtomicOp: 多文件原子性推送流程
    
    Developer->>AI: "帮我同时更新README.md、package.json和src/main.js三个文件"
    AI->>Handler: push_files(branch="main", message="Update multiple files", files=[...])
    
    Handler->>Validator: 验证文件数组参数
    Validator->>Validator: 检查每个文件对象
    loop For each file in files
        Validator->>Validator: 验证path字段存在且非空
        Validator->>Validator: 验证content字段存在
        Validator->>Validator: 检查路径安全性（无../等）
    end
    Validator-->>Handler: 文件验证通过：3个文件
    
    Note over Handler, GitAPI: Git原子性操作序列
    
    Handler->>GitAPI: GetRef("refs/heads/main")
    GitAPI-->>Handler: 当前分支SHA: abc123
    
    Handler->>GitAPI: GetCommit(abc123)
    GitAPI-->>Handler: 基础提交和树SHA: def456
    
    Handler->>AtomicOp: 开始原子性树创建
    AtomicOp->>AtomicOp: 构建TreeEntry数组
    
    Note over AtomicOp: entries = [
    Note over AtomicOp:   {path: "README.md", content: "...", mode: "100644"},
    Note over AtomicOp:   {path: "package.json", content: "...", mode: "100644"},
    Note over AtomicOp:   {path: "src/main.js", content: "...", mode: "100644"}
    Note over AtomicOp: ]
    
    AtomicOp->>GitAPI: CreateTree(baseTreeSHA=def456, entries)
    GitAPI->>GitAPI: 创建包含所有文件变更的新树
    GitAPI-->>AtomicOp: 新树SHA: ghi789
    
    AtomicOp->>GitAPI: CreateCommit(message, treeSHA=ghi789, parentSHA=abc123)
    GitAPI->>GitAPI: 创建原子性提交
    GitAPI-->>AtomicOp: 新提交SHA: jkl012
    
    AtomicOp->>GitAPI: UpdateRef("refs/heads/main", newSHA=jkl012)
    GitAPI->>GitAPI: 原子性更新分支指向
    GitAPI-->>AtomicOp: 引用更新成功
    
    AtomicOp-->>Handler: 原子性操作完成
    Handler-->>AI: 多文件推送成功
    AI-->>Developer: "已成功原子性更新3个文件到main分支"
    
    Note over GitAPI: 原子性保证：
    Note over GitAPI: - 要么所有文件都更新成功
    Note over GitAPI: - 要么所有文件都不更新
    Note over GitAPI: - 不会出现部分更新的情况

sequenceDiagram
    participant Client as AI Client
    participant Handler as GetFileContents Handler
    participant Resolver as Reference Resolver
    participant REST as GitHub REST API
    participant Raw as GitHub Raw API
    participant TreeAPI as Git Tree API
    participant Optimizer as Path Optimizer
    
    Note over Client, Optimizer: 智能文件获取策略选择
    
    Client->>Handler: get_file_contents(owner="facebook", repo="react", path="README", ref="main")
    
    Handler->>Resolver: resolveGitReference(ctx, client, "facebook", "react", "main", "")
    
    Note over Resolver: Git引用解析流程
    Resolver->>Resolver: ref="main" (短名称)
    Resolver->>REST: GetRef("refs/heads/main")
    REST-->>Resolver: 分支引用找到
    Resolver->>REST: GetRef确认SHA
    REST-->>Resolver: SHA: a1b2c3d4...
    Resolver-->>Handler: 解析结果{Ref: "refs/heads/main", SHA: "a1b2c3d4..."}
    
    Note over Handler: 路径策略选择
    Handler->>Handler: path="README" (不以/结尾)
    Handler->>Handler: 选择文件内容获取策略
    
    Note over Handler, REST: 策略1: 获取文件元信息
    Handler->>REST: GetContents(ctx, "facebook", "react", "README", {Ref: "main"})
    REST-->>Handler: 文件不存在 (404)
    
    Note over Handler, TreeAPI: 策略2: 模糊路径匹配
    Handler->>TreeAPI: GetTree(ctx, "facebook", "react", "a1b2c3d4", recursive=true)
    TreeAPI-->>Handler: 完整仓库文件树
    
    Handler->>Optimizer: filterPaths(treeEntries, "README", maxResults=3)
    Optimizer->>Optimizer: 查找以"README"结尾的路径
    Optimizer->>Optimizer: 找到匹配：
    Note over Optimizer: - README.md
    Note over Optimizer: - docs/README.md  
    Note over Optimizer: - packages/README.md
    
    Optimizer-->>Handler: 匹配路径列表
    
    Note over Handler, Raw: 策略3: 获取最佳匹配的内容
    Handler->>Handler: 选择最可能的匹配：README.md
    Handler->>REST: GetContents("README.md") - 获取SHA
    REST-->>Handler: 文件SHA: e5f6g7h8...
    
    Handler->>Raw: GetRawContent(ctx, "facebook", "react", "README.md", opts)
    Raw->>Raw: 直接从raw.githubusercontent.com下载
    Raw-->>Handler: 文件内容 + Content-Type: text/markdown
    
    Handler->>Handler: 构建资源URI
    Handler->>Handler: uri = "repo://facebook/react/main/contents/README.md"
    
    Handler->>Handler: 检测内容类型：text/markdown
    Handler->>Handler: 构建TextResourceContents响应
    
    Handler-->>Client: {
    Handler-->>Client:   type: "resource",
    Handler-->>Client:   resource: {
    Handler-->>Client:     uri: "repo://facebook/react/main/contents/README.md",
    Handler-->>Client:     mimeType: "text/markdown",
    Handler-->>Client:     text: "# React\n\nA JavaScript library..."
    Handler-->>Client:   },
    Handler-->>Client:   message: "successfully downloaded text file (SHA: e5f6g7h8)"
    Handler-->>Client: }
    
    Client->>Client: 解析Markdown内容并显示给用户

// 位置: pkg/github/search.go
func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("search_repositories",
        mcp.WithDescription("Search repositories using GitHub's advanced search syntax with intelligent result optimization"),
        
        mcp.WithString("query", mcp.Required(),
            mcp.Description("Repository search query. Examples: 'machine learning in:name stars:>1000 language:python', 'topic:react', 'user:facebook'. Supports advanced search syntax for precise filtering.")),
        
        // 性能优化选项
        mcp.WithBoolean("minimal_output", mcp.Description("Return minimal repository information (default: true). When false, returns full GitHub API repository objects."), mcp.DefaultBool(true)),
        WithPagination(),
    ),
    
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        query, _ := RequiredParam[string](request, "query")
        minimalOutput, _ := OptionalBoolParamWithDefault(request, "minimal_output", true)
        pagination, _ := OptionalPaginationParams(request)
        
        client, err := getClient(ctx)
        if err != nil {
            return nil, fmt.Errorf("failed to get GitHub client: %w", err)
        }
        
        // 搜索选项配置
        opts := &github.SearchOptions{
            ListOptions: github.ListOptions{
                Page:    pagination.Page,
                PerPage: pagination.PerPage,
            },
        }
        
        // 执行仓库搜索
        result, resp, err := client.Search.Repositories(ctx, query, opts)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to search repositories", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 智能结果优化
        if minimalOutput {
            // 返回优化的最小结果
            minimalResult := &MinimalSearchRepositoriesResult{
                TotalCount:        result.GetTotal(),
                IncompleteResults: result.GetIncompleteResults(),
                Items:             make([]MinimalRepository, 0, len(result.Repositories)),
            }
            
            for _, repo := range result.Repositories {
                minimalRepo := MinimalRepository{
                    ID:            repo.GetID(),
                    Name:          repo.GetName(),
                    FullName:      repo.GetFullName(),
                    Description:   repo.GetDescription(),
                    HTMLURL:       repo.GetHTMLURL(),
                    Language:      repo.GetLanguage(),
                    Stars:         repo.GetStargazersCount(),
                    Forks:         repo.GetForksCount(),
                    OpenIssues:    repo.GetOpenIssuesCount(),
                    Private:       repo.GetPrivate(),
                    Fork:          repo.GetFork(),
                    Archived:      repo.GetArchived(),
                    DefaultBranch: repo.GetDefaultBranch(),
                }
                
                // 时间字段格式化
                if repo.UpdatedAt != nil {
                    minimalRepo.UpdatedAt = repo.UpdatedAt.Format("2006-01-02T15:04:05Z")
                }
                
                // 主题标签（如果存在）
                if len(repo.Topics) > 0 {
                    minimalRepo.Topics = repo.Topics
                }
                
                minimalResult.Items = append(minimalResult.Items, minimalRepo)
            }
            
            return MarshalledTextResult(minimalResult), nil
        }
        
        // 返回完整结果（用于详细分析）
        return MarshalledTextResult(result), nil
    }
}

// 位置: pkg/github/repositories.go:938-1036
func CreateBranch(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
    return mcp.NewTool("create_branch",
        mcp.WithDescription("Create a new branch in a GitHub repository with intelligent source branch detection"),
        
        mcp.WithString("branch", mcp.Required(), mcp.Description("Name for new branch")),
        mcp.WithString("from_branch", mcp.Description("Source branch (defaults to repo default)")),
    ),
    
    func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
        owner, _ := RequiredParam[string](request, "owner")
        repo, _ := RequiredParam[string](request, "repo")
        branch, _ := RequiredParam[string](request, "branch")
        fromBranch, _ := OptionalParam[string](request, "from_branch")
        
        client, err := getClient(ctx)
        if err != nil {
            return nil, fmt.Errorf("failed to get GitHub client: %w", err)
        }
        
        // 智能源分支检测
        if fromBranch == "" {
            // 获取仓库默认分支
            repository, resp, err := client.Repositories.Get(ctx, owner, repo)
            if err != nil {
                return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get repository", resp, err), nil
            }
            defer resp.Body.Close()
            
            fromBranch = *repository.DefaultBranch
        }
        
        // 获取源分支的SHA
        ref, resp, err := client.Git.GetRef(ctx, owner, repo, "refs/heads/"+fromBranch)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get reference", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 创建新分支引用
        newRef := &github.Reference{
            Ref:    github.Ptr("refs/heads/" + branch),
            Object: &github.GitObject{SHA: ref.Object.SHA},
        }
        
        createdRef, resp, err := client.Git.CreateRef(ctx, owner, repo, newRef)
        if err != nil {
            return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to create branch", resp, err), nil
        }
        defer resp.Body.Close()
        
        // 构建详细响应
        response := map[string]interface{}{
            "ref":         createdRef.GetRef(),
            "sha":         createdRef.GetObject().GetSHA(),
            "url":         createdRef.GetURL(),
            "from_branch": fromBranch,
            "message":     fmt.Sprintf("Branch '%s' created from '%s'", branch, fromBranch),
        }
        
        return MarshalledTextResult(response), nil
    }
}

classDiagram
    class ResourceTemplateSystem {
        +GetRepositoryResourceContent()
        +GetRepositoryResourceBranchContent()
        +GetRepositoryResourceCommitContent()
        +GetRepositoryResourceTagContent()
        +GetRepositoryResourcePrContent()
    }

    class ResourceURI {
        +repo://owner/repo/contents/path
        +repo://owner/repo/branch/contents/path
        +repo://owner/repo/sha/commit_sha/contents/path
        +repo://owner/repo/refs/tags/tag/contents/path
        +repo://owner/repo/refs/pull/pr_number/contents/path
    }

    class ResourceContent {
        +TextResourceContents
        +BlobResourceContents
        +DirectoryResourceContents
    }

    class ContentOptimization {
        +MIME Type Detection
        +Binary/Text Classification
        +Base64 Encoding for Binary
        +UTF-8 Encoding for Text
    }

    ResourceTemplateSystem --> ResourceURI
    ResourceTemplateSystem --> ResourceContent
    ResourceContent --> ContentOptimization

// 资源URI构建策略
func buildResourceURI(owner, repo, resourceType, identifier, path string) (string, error) {
    // 基础URI格式：repo://owner/repo/...
    baseURI := fmt.Sprintf("repo://%s/%s", owner, repo)
    
    switch resourceType {
    case "default":
        // repo://owner/repo/contents/path
        return url.JoinPath(baseURI, "contents", path)
        
    case "branch":
        // repo://owner/repo/branch_name/contents/path
        return url.JoinPath(baseURI, identifier, "contents", path)
        
    case "commit":
        // repo://owner/repo/sha/commit_sha/contents/path
        return url.JoinPath(baseURI, "sha", identifier, "contents", path)
        
    case "tag":
        // repo://owner/repo/refs/tags/tag_name/contents/path
        return url.JoinPath(baseURI, "refs", "tags", identifier, "contents", path)
        
    case "pull_request":
        // repo://owner/repo/refs/pull/pr_number/contents/path
        return url.JoinPath(baseURI, "refs", "pull", identifier, "contents", path)
        
    default:
        return "", fmt.Errorf("unsupported resource type: %s", resourceType)
    }
}

// 资源内容类型智能检测
func detectContentType(content []byte, filename string) string {
    // 1. 基于文件扩展名的快速检测
    ext := strings.ToLower(filepath.Ext(filename))
    if mimeType, exists := extensionMimeTypes[ext]; exists {
        return mimeType
    }
    
    // 2. 基于内容的检测
    mimeType := http.DetectContentType(content)
    
    // 3. 特殊文件类型处理
    switch {
    case strings.Contains(filename, "Dockerfile"):
        return "text/x-dockerfile"
    case strings.Contains(filename, ".yml") || strings.Contains(filename, ".yaml"):
        return "text/yaml"
    case strings.Contains(filename, ".json"):
        return "application/json"
    case strings.Contains(filename, ".md"):
        return "text/markdown"
    default:
        return mimeType
    }
}

var extensionMimeTypes = map[string]string{
    ".js":   "text/javascript",
    ".ts":   "text/typescript", 
    ".py":   "text/x-python",
    ".go":   "text/x-go",
    ".java": "text/x-java",
    ".cpp":  "text/x-c++",
    ".c":    "text/x-c",
    ".sh":   "text/x-shellscript",
    ".sql":  "text/x-sql",
    ".xml":  "text/xml",
    ".html": "text/html",
    ".css":  "text/css",
}