files

package
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 22, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package files implements MCP tool handlers for GitLab repository file operations including get, create, update, delete, blame, metadata, and raw content retrieval. It wraps the RepositoryFiles service from client-go v2.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Delete

func Delete(ctx context.Context, client *gitlabclient.Client, input DeleteInput) error

Delete deletes a file from a GitLab repository.

func FormatBlameMarkdown

func FormatBlameMarkdown(out BlameOutput) string

FormatBlameMarkdown renders blame information as Markdown.

func FormatFileInfoMarkdown

func FormatFileInfoMarkdown(out FileInfoOutput) string

FormatFileInfoMarkdown renders file info (create/update result).

func FormatMetaDataMarkdown

func FormatMetaDataMarkdown(out MetaDataOutput) string

FormatMetaDataMarkdown renders file metadata as Markdown.

func FormatOutputMarkdown

func FormatOutputMarkdown(f Output) string

FormatOutputMarkdown renders file metadata as a Markdown summary. For image and binary files, it includes content type information instead of content.

func FormatRawBinaryMarkdown

func FormatRawBinaryMarkdown(out RawOutput) string

FormatRawBinaryMarkdown renders metadata for a raw binary file.

func FormatRawImageMarkdown

func FormatRawImageMarkdown(out RawOutput) string

FormatRawImageMarkdown renders metadata for a raw image file.

func FormatRawMarkdown

func FormatRawMarkdown(out RawOutput) string

FormatRawMarkdown renders raw file content as Markdown.

func RegisterTools

func RegisterTools(server *mcp.Server, client *gitlabclient.Client)

RegisterTools registers all file-related MCP tools on the given server.

Types

type BlameInput

type BlameInput struct {
	ProjectID  toolutil.StringOrInt `json:"project_id"            jsonschema:"Project ID or URL-encoded path,required"`
	FilePath   string               `json:"file_path"             jsonschema:"URL-encoded full path of the file,required"`
	Ref        string               `json:"ref,omitempty"         jsonschema:"Branch, tag, or commit SHA (defaults to default branch)"`
	RangeStart int                  `json:"range_start,omitempty" jsonschema:"Start line number for blame range"`
	RangeEnd   int                  `json:"range_end,omitempty"   jsonschema:"End line number for blame range"`
}

BlameInput defines parameters for retrieving file blame information.

type BlameOutput

type BlameOutput struct {
	toolutil.HintableOutput
	FilePath string             `json:"file_path"`
	Ranges   []BlameRangeOutput `json:"ranges"`
}

BlameOutput holds blame information for a file.

func Blame

func Blame(ctx context.Context, client *gitlabclient.Client, input BlameInput) (BlameOutput, error)

Blame retrieves blame information for a file in a GitLab repository.

type BlameRangeCommitOutput

type BlameRangeCommitOutput struct {
	ID            string `json:"id"`
	Message       string `json:"message"`
	AuthorName    string `json:"author_name"`
	AuthorEmail   string `json:"author_email"`
	AuthoredDate  string `json:"authored_date,omitempty"`
	CommittedDate string `json:"committed_date,omitempty"`
}

BlameRangeCommitOutput represents the commit info for a blame range.

type BlameRangeOutput

type BlameRangeOutput struct {
	Commit BlameRangeCommitOutput `json:"commit"`
	Lines  []string               `json:"lines"`
}

BlameRangeOutput represents one blame range with commit and lines.

type CreateInput

type CreateInput struct {
	ProjectID       toolutil.StringOrInt `json:"project_id"              jsonschema:"Project ID or URL-encoded path,required"`
	FilePath        string               `json:"file_path"               jsonschema:"URL-encoded full path of the new file,required"`
	Branch          string               `json:"branch"                  jsonschema:"Branch to create the file on,required"`
	Content         string               `json:"content"                 jsonschema:"File content,required"`
	CommitMessage   string               `json:"commit_message"          jsonschema:"Commit message,required"`
	StartBranch     string               `json:"start_branch,omitempty"  jsonschema:"Branch to start from (creates new branch if different from branch)"`
	Encoding        string               `json:"encoding,omitempty"      jsonschema:"Content encoding: text or base64 (default: text)"`
	AuthorEmail     string               `json:"author_email,omitempty"  jsonschema:"Commit author email"`
	AuthorName      string               `json:"author_name,omitempty"   jsonschema:"Commit author name"`
	ExecuteFilemode *bool                `json:"execute_filemode,omitempty" jsonschema:"Enable execute permission on the file"`
}

CreateInput defines parameters for creating a new file in a repository.

type DeleteInput

type DeleteInput struct {
	ProjectID     toolutil.StringOrInt `json:"project_id"              jsonschema:"Project ID or URL-encoded path,required"`
	FilePath      string               `json:"file_path"               jsonschema:"URL-encoded full path of the file to delete,required"`
	Branch        string               `json:"branch"                  jsonschema:"Branch to delete the file from,required"`
	CommitMessage string               `json:"commit_message"          jsonschema:"Commit message,required"`
	StartBranch   string               `json:"start_branch,omitempty"  jsonschema:"Branch to start from"`
	AuthorEmail   string               `json:"author_email,omitempty"  jsonschema:"Commit author email"`
	AuthorName    string               `json:"author_name,omitempty"   jsonschema:"Commit author name"`
	LastCommitID  string               `json:"last_commit_id,omitempty" jsonschema:"Last known commit ID for optimistic locking"`
}

DeleteInput defines parameters for deleting a file from a repository.

type FileInfoOutput

type FileInfoOutput struct {
	toolutil.HintableOutput
	FilePath string `json:"file_path"`
	Branch   string `json:"branch"`
}

FileInfoOutput represents the result of a file create or update operation.

func Create

func Create(ctx context.Context, client *gitlabclient.Client, input CreateInput) (FileInfoOutput, error)

Create creates a new file in a GitLab repository.

func Update

func Update(ctx context.Context, client *gitlabclient.Client, input UpdateInput) (FileInfoOutput, error)

Update updates an existing file in a GitLab repository.

type GetInput

type GetInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"URL-encoded full path of the file (e.g. src%2Fmain.go or src/main.go),required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch name, tag, or commit SHA (defaults to default branch)"`
}

GetInput defines parameters for retrieving a file from a repository.

type MetaDataInput

type MetaDataInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"URL-encoded full path of the file,required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch, tag, or commit SHA (defaults to default branch)"`
}

MetaDataInput defines parameters for retrieving file metadata (no content).

type MetaDataOutput

type MetaDataOutput struct {
	toolutil.HintableOutput
	FileName        string `json:"file_name"`
	FilePath        string `json:"file_path"`
	Size            int64  `json:"size"`
	Encoding        string `json:"encoding"`
	Ref             string `json:"ref"`
	BlobID          string `json:"blob_id"`
	CommitID        string `json:"commit_id"`
	LastCommitID    string `json:"last_commit_id"`
	ExecuteFilemode bool   `json:"execute_filemode"`
	SHA256          string `json:"content_sha256"`
}

MetaDataOutput holds file metadata without content.

func GetMetaData

func GetMetaData(ctx context.Context, client *gitlabclient.Client, input MetaDataInput) (MetaDataOutput, error)

GetMetaData retrieves file metadata without content from a GitLab repository.

func GetRawFileMetaData

func GetRawFileMetaData(ctx context.Context, client *gitlabclient.Client, input RawMetaDataInput) (MetaDataOutput, error)

GetRawFileMetaData retrieves file metadata from the raw file endpoint (HEAD request). Returns the same metadata as GetFileMetaData but uses a different API endpoint. Useful for checking file existence efficiently.

type Output

type Output struct {
	toolutil.HintableOutput
	FileName        string `json:"file_name"`
	FilePath        string `json:"file_path"`
	Size            int64  `json:"size"`
	Encoding        string `json:"encoding"`
	Content         string `json:"content"`
	ContentCategory string `json:"content_category"`
	Ref             string `json:"ref"`
	BlobID          string `json:"blob_id"`
	CommitID        string `json:"commit_id"`
	LastCommitID    string `json:"last_commit_id"`
	ExecuteFilemode bool   `json:"execute_filemode"`

	// ImageData holds raw image bytes for ImageContent responses (not serialized).
	ImageData []byte `json:"-"`
	// ImageMIMEType holds the MIME type for image files (not serialized).
	ImageMIMEType string `json:"-"`
}

Output represents a file retrieved from a repository.

func Get

func Get(ctx context.Context, client *gitlabclient.Client, input GetInput) (Output, error)

Get retrieves a single file from a GitLab repository by its path and optional ref (branch, tag, or commit SHA). If the file content is base64-encoded by the API, it is automatically decoded to plain text. Returns an error if the file is not found or decoding fails.

type RawInput

type RawInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"URL-encoded full path of the file,required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch, tag, or commit SHA (defaults to default branch)"`
}

RawInput defines parameters for retrieving raw file content.

type RawMetaDataInput

type RawMetaDataInput struct {
	ProjectID toolutil.StringOrInt `json:"project_id" jsonschema:"Project ID or URL-encoded path,required"`
	FilePath  string               `json:"file_path"  jsonschema:"URL-encoded full path of the file,required"`
	Ref       string               `json:"ref,omitempty" jsonschema:"Branch, tag, or commit SHA (defaults to default branch)"`
}

RawMetaDataInput defines parameters for retrieving raw file metadata via HEAD request.

type RawOutput

type RawOutput struct {
	toolutil.HintableOutput
	FilePath        string `json:"file_path"`
	Size            int    `json:"size"`
	Content         string `json:"content"`
	ContentCategory string `json:"content_category"`

	// ImageData holds raw image bytes for ImageContent responses (not serialized).
	ImageData []byte `json:"-"`
	// ImageMIMEType holds the MIME type for image files (not serialized).
	ImageMIMEType string `json:"-"`
}

RawOutput holds the raw content of a file.

func GetRaw

func GetRaw(ctx context.Context, client *gitlabclient.Client, input RawInput) (RawOutput, error)

GetRaw retrieves the raw content of a file from a GitLab repository.

type UpdateInput

type UpdateInput struct {
	ProjectID       toolutil.StringOrInt `json:"project_id"              jsonschema:"Project ID or URL-encoded path,required"`
	FilePath        string               `json:"file_path"               jsonschema:"URL-encoded full path of the file to update,required"`
	Branch          string               `json:"branch"                  jsonschema:"Branch to update the file on,required"`
	Content         string               `json:"content"                 jsonschema:"New file content,required"`
	CommitMessage   string               `json:"commit_message"          jsonschema:"Commit message,required"`
	StartBranch     string               `json:"start_branch,omitempty"  jsonschema:"Branch to start from"`
	Encoding        string               `json:"encoding,omitempty"      jsonschema:"Content encoding: text or base64 (default: text)"`
	AuthorEmail     string               `json:"author_email,omitempty"  jsonschema:"Commit author email"`
	AuthorName      string               `json:"author_name,omitempty"   jsonschema:"Commit author name"`
	LastCommitID    string               `json:"last_commit_id,omitempty" jsonschema:"Last known commit ID for optimistic locking"`
	ExecuteFilemode *bool                `json:"execute_filemode,omitempty" jsonschema:"Enable execute permission on the file"`
}

UpdateInput defines parameters for updating an existing file in a repository.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL