File Operations

Relevant source files

The following files were used as context for generating this wiki page:

• pkg/github/repositories.go
• pkg/github/repositories_test.go
• pkg/github/repository_resource_test.go
• e2e/e2e_test.go
• cmd/mcpcurl/README.md

The File Operations module in the GitHub MCP server provides a standardized interface for interacting with files and directories within GitHub repositories. It facilitates remote content retrieval, file creation, updates, and deletions through the Model Context Protocol (MCP). By abstracting the underlying GitHub REST and Git Data APIs, it enables LLMs and other MCP clients to perform complex version control tasks seamlessly.

This module is a core component of the repos toolset, allowing agents to read source code, commit changes, and manage repository structures. It handles logic for resolving git references (branches, tags, SHAs) and provides specialized handling for binary versus text content.

Architecture and Data Flow

The file operations architecture leverages both the high-level GitHub Repositories API and the low-level Git Data API. Read operations typically use the Repositories Content API or a "raw" content client, while write operations may use the Git Data API directly to ensure specific features like automatic commit signing.

Reference Resolution

Before performing file operations, the system resolves provided git references. The priority logic ensures that specific commit SHAs take precedence over branch or tag names.

Content Retrieval

The system supports fetching file and directory contents through the get_file_contents tool. This tool intelligently determines whether to return raw text, base64-encoded binary data, or directory listings.

API Parameters: get_file_contents

Parameter	Type	Required	Description
owner	string	Yes	Repository owner (username or organization)
repo	string	Yes	Repository name
path	string	No	Path to file/directory (directories must end with /)
ref	string	No	Git ref (e.g., refs/heads/main, v1.0.0)
sha	string	No	Commit SHA (takes precedence over ref)

Sources: pkg/github/repositories.go:345-375

Implementation Logic

If a path does not end in a slash, the system first attempts to retrieve the file's SHA and then fetches the raw content. If the content type is text/* or application/json, it is returned as a text resource; otherwise, it is treated as a binary blob. If the path points to a directory, it returns a JSON-formatted list of directory entries.

Sources: pkg/github/repositories.go:395-460, pkg/github/repository_resource_test.go:50-120

Modifying Files

Files can be modified individually or in batches. The module provides two primary tools for write operations: create_or_update_file and push_files.

File Creation and Updates

The create_or_update_file tool handles single file operations. When updating an existing file, the previous blob SHA must be provided to prevent merge conflicts.

Multi-file Commits

The push_files tool allows for pushing multiple files in a single atomic commit. This is implemented by creating a new Git Tree based on the current branch head, creating a new commit with that tree, and finally updating the branch reference.

Sources: pkg/github/repositories.go:610-730

Deletion Operations

The delete_file tool implements a robust approach to removing files. Instead of using the standard REST deletion endpoint, it uses the Git Data API to manually construct a tree where the target file is omitted (SHA set to nil).

Deletion Process

1. Fetch Reference: Get the current SHA for the target branch.
2. Fetch Base Commit: Retrieve the commit object to identify the current tree.
3. Create New Tree: Submit a tree entry for the path with SHA: nil.
4. Create Commit: Create a new commit object pointing to the new tree and the old commit as a parent.
5. Update Ref: Move the branch head to the new commit.

This method ensures automatic commit signing when the server operates as a GitHub App or via GitHub Actions.
Sources: pkg/github/repositories.go:505-605, pkg/github/repositories_test.go:1150-1200

Directory Handling and Matching

When a path provided to get_file_contents does not exactly match a file or directory, the system performs a recursive Git Tree search. It filters the tree entries to find possible path matches by matching the suffix of the entry paths.

Path Filtering Logic

• If the path ends in /, only directories are matched.
• The system returns up to 3 possible matches to help the agent correct the path.
• Directories in results are always returned with a trailing slash for clarity.

Sources: pkg/github/repositories.go:465-495, pkg/github/repositories.go:780-810

Summary

The File Operations module provides a comprehensive suite of tools for remote file management. By integrating reference resolution, recursive path matching, and atomic multi-file pushes, it allows for sophisticated agentic workflows. The use of the Git Data API for deletions ensures that all changes maintain a high standard of repository integrity through signed commits.

Sources: pkg/github/repositories.go:1-890, e2e/e2e_test.go:350-500