Repository Management Tools
Relevant source files
The following files were used as context for generating this wiki page:
The Repository Management Tools within the GitHub MCP server provide a comprehensive suite of Model Context Protocol (MCP) tools and resources for interacting with GitHub repositories. These tools enable automated agents to perform core version control operations, including repository creation, file manipulation, branch management, and metadata retrieval.
The system is designed to expose GitHub's REST and Git Data APIs through a standardized MCP interface, allowing LLMs to read file contents, commit changes, manage tags and releases, and perform social actions like starring or forking. By utilizing "minimal" data types, the system reduces token consumption while providing essential repository information.
Core Repository Operations
The server implements foundational tools for managing the lifecycle and state of a repository. This includes creating new repositories, forking existing ones, and managing social interactions.
Repository Creation and Forking
Users can create new repositories either in their personal account or within a specified organization. The create_repository tool supports configuration for visibility (private/public) and initialization with a README. The fork_repository tool allows for asynchronous forking of existing repositories.
Sources: pkg/github/repositories.go:377-440, pkg/github/repositories.go:648-709
Social and Metadata Tools
The system provides tools to manage stars and retrieve lists of starred repositories. These tools utilize the GitHub Activity API to track and modify user interest in specific projects.
Sources: pkg/github/repositories.go:1011-1205
| Tool Name | Purpose | Key Parameters |
|---|---|---|
create_repository | Creates a new GitHub repository | name, organization, private, autoInit |
fork_repository | Forks a repository to an account/org | owner, repo, organization |
star_repository | Stars a specific repository | owner, repo |
list_starred_repositories | Lists repositories starred by a user | username, sort, direction |
Sources: pkg/github/repositories.go:377-440, pkg/github/repositories.go:648-709, pkg/github/repositories.go:1011-1205
File and Content Management
File management is handled through two primary mechanisms: the standard REST Content API for simple operations and the Git Data API for more complex or signed operations.
Reading Content
The get_file_contents tool is the primary interface for retrieving data. It intelligently resolves Git references (branches, tags, or SHAs) and can return directory listings or raw file data.
The diagram shows the logic flow for resolving a file path, including the fallback to recursive tree searching if a direct path is not found.
Sources: pkg/github/repositories.go:442-595, pkg/github/repositories.go:871-913
Writing and Deleting Files
- Create/Update:
create_or_update_filehandles single-file modifications. - Push Multiple:
push_filesallows batching multiple file changes into a single atomic commit. - Delete:
delete_fileuses the Git Data API (Tree/Commit/Ref) rather than the REST Delete endpoint to ensure proper commit signing for automated accounts.
Sources: pkg/github/repositories.go:273-375, pkg/github/repositories.go:711-869, pkg/github/repositories.go:758-765
Version Control and Git Data
The server exposes low-level Git objects and versioning structures to allow for precise control over the repository state.
Branch and Tag Management
The server provides tools to list and create branches, as well as interact with Git tags. Branch creation defaults to the repository's default branch if no source is specified.
Sources: pkg/github/repositories.go:210-271, pkg/github/repositories.go:915-1009
Commit Interaction
Commit tools provide both summary lists and detailed views. The get_commit tool can optionally include file diffs.
This sequence illustrates the transformation from a verbose GitHub API response to a token-efficient MinimalCommit structure.
Sources: pkg/github/repositories.go:18-129, pkg/github/minimal_types.go:93-163
Reference Resolution Logic
A critical internal component is resolveGitReference, which determines a definitive SHA from various input types.
| Priority | Input Condition | Resolution Strategy |
|---|---|---|
| 1 | sha provided | Use SHA directly, skip resolution |
| 2 | ref is empty | Fetch repository default branch |
| 3 | ref starts with refs/ | Use as-is (Fully-qualified) |
| 4 | Short Name | Try refs/heads/, fallback to refs/tags/ |
Sources: pkg/github/repositories.go:944-1009
Data Structures (Minimal Types)
To optimize communication with LLMs, the server uses "Minimal" versions of GitHub types. These structures extract only the most relevant fields (e.g., ID, Name, URL, SHA).
- MinimalRepository: Focuses on metadata like stars, forks, and primary language.
- MinimalCommit: Contains the message, author info, and optionally file changes/stats.
- MinimalBranch: Simple mapping of name to commit SHA.
Sources: pkg/github/minimal_types.go:21-170
Conclusion
The Repository Management Tools provide a robust layer of abstraction over the GitHub API, tailored for MCP-enabled clients. By combining high-level REST operations with low-level Git Data manipulation and efficient data structures, the system enables complex repository workflows while maintaining technical accuracy and resource efficiency.