resources

package
v2.3.0 Latest Latest
Warning

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

Go to latest
Published: Jun 28, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package resources registers read-only MCP resources for GitLab and server metadata.

Resources expose project data, tool manifests, workflow guides, and MCP workspace roots through stable gitlab:// URIs. They are intended for discovery and context loading rather than mutation, and their output is formatted for predictable use by MCP clients and LLMs.

Resource Families

The package registers several groups of resources:

The public tool manifest resources expose these URI shapes:

gitlab://tools
gitlab://tools/{id}

Register wires the GitLab-backed resources into an MCP server.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Register

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

Register adds every GitLab-backed MCP resource to the given server. The full set of URI shapes exposed by Register is:

gitlab://user/current
gitlab://groups
gitlab://group/{group_id}
gitlab://group/{group_id}/members
gitlab://group/{group_id}/projects
gitlab://group/{group_id}/milestone/{milestone_iid}
gitlab://group/{group_id}/label/{label_id}
gitlab://project/{project_id}
gitlab://project/{project_id}/members
gitlab://project/{project_id}/issues
gitlab://project/{project_id}/issue/{issue_iid}
gitlab://project/{project_id}/pipelines/latest
gitlab://project/{project_id}/pipeline/{pipeline_id}
gitlab://project/{project_id}/pipeline/{pipeline_id}/jobs
gitlab://project/{project_id}/labels
gitlab://project/{project_id}/label/{label_id}
gitlab://project/{project_id}/milestones
gitlab://project/{project_id}/milestone/{milestone_iid}
gitlab://project/{project_id}/mr/{merge_request_iid}
gitlab://project/{project_id}/mr/{merge_request_iid}/notes
gitlab://project/{project_id}/mr/{merge_request_iid}/discussions
gitlab://project/{project_id}/branches
gitlab://project/{project_id}/branch/{branch}
gitlab://project/{project_id}/releases
gitlab://project/{project_id}/release/{tag_name}
gitlab://project/{project_id}/tags
gitlab://project/{project_id}/tag/{tag_name}
gitlab://project/{project_id}/commit/{sha}
gitlab://project/{project_id}/file/{ref}/{+path}
gitlab://project/{project_id}/wiki/{slug}
gitlab://project/{project_id}/deployment/{deployment_id}
gitlab://project/{project_id}/environment/{environment_id}
gitlab://project/{project_id}/job/{job_id}
gitlab://project/{project_id}/snippet/{snippet_id}
gitlab://project/{project_id}/feature_flag/{name}
gitlab://project/{project_id}/deploy_key/{deploy_key_id}
gitlab://project/{project_id}/board/{board_id}
gitlab://snippet/{snippet_id}

Tool-manifest, workflow-guide, workspace-root, and meta/dynamic schema resources are registered separately by their dedicated Register* helpers (see doc.go for the full family breakdown).

func RegisterDynamicSchemaResources added in v2.0.3

func RegisterDynamicSchemaResources(server *mcp.Server, catalog *actioncatalog.Catalog)

RegisterDynamicSchemaResources wires the dynamic action catalog resources into the MCP server. Two resources are registered:

  • The static "gitlab://schema/dynamic/" index resource, which lists every canonical "domain.action" ID accepted by gitlab_execute_action.
  • The "gitlab://schema/dynamic/{action}" template resource, which returns action-specific params schemas without the meta-tool-only fields (such as confirm) that gitlab_execute_action adds on top.

When catalog is nil an empty actioncatalog.Catalog is used; when catalog is non-nil a clone is taken so the original is not mutated by the resource handlers.

func RegisterMetaSchemaResources

func RegisterMetaSchemaResources(server *mcp.Server, routes map[string]toolutil.ActionMap)

RegisterMetaSchemaResources wires the index resource and the per-action template resource into the MCP server. Both resources are read-only and do not require a GitLab client; callers pass the exact meta-tool routes that are visible on this server after configuration filters have been applied.

The routes argument is cloned (via toolutil.CloneMetaSchemaRoutes) so later route registrations do not leak into already-wired servers.

func RegisterToolSurfaceResources added in v2.0.3

func RegisterToolSurfaceResources(server *mcp.Server, opts ToolSurfaceResourceOptions)

RegisterToolSurfaceResources wires a surface-aware tool manifest into the MCP server. Two resources are registered:

  • The static "gitlab://tools" resource, which lists the active surface ("dynamic", "meta", or "individual") and every executable entry that surface exposes.
  • The "gitlab://tools/{id}" template resource, which returns the accepted call shape and input schema for one entry.

Use ToolSurfaceResourceOptions to pass the active tool surface; see [newToolSurfaceSnapshot] for the projection rules.

func RegisterWorkflowGuides

func RegisterWorkflowGuides(server *mcp.Server)

RegisterWorkflowGuides registers static text resources with workflow best-practice content. The package-internal [workflowGuides] table defines the five guides exposed:

gitlab://guides/git-workflow
gitlab://guides/merge-request-hygiene
gitlab://guides/conventional-commits
gitlab://guides/code-review
gitlab://guides/pipeline-troubleshooting

These guides help LLMs provide consistent advice on Git workflows, merge requests, commits, code reviews, and pipeline troubleshooting.

Types

type BoardResourceOutput

type BoardResourceOutput struct {
	ID   int64  `json:"id"`
	Name string `json:"name"`
}

BoardResourceOutput is the JSON payload for a single project issue board, returned by the "gitlab://project/{id}/board/{board_id}" resource. It contains the board's ID and name.

type BranchResourceOutput

type BranchResourceOutput struct {
	Name      string `json:"name"`
	Protected bool   `json:"protected"`
	Merged    bool   `json:"merged"`
	Default   bool   `json:"default"`
	WebURL    string `json:"web_url"`
}

BranchResourceOutput is the JSON payload for a single repository branch (used by both the branch listing and the branch detail resources). It includes the branch's name, protection flag, merge status, default flag, and web URL.

type CommitResourceOutput

type CommitResourceOutput struct {
	ID            string             `json:"id"`
	ShortID       string             `json:"short_id"`
	Title         string             `json:"title"`
	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"`
	WebURL        string             `json:"web_url"`
	ParentIDs     []string           `json:"parent_ids,omitempty"`
	Stats         *CommitStatsOutput `json:"stats,omitempty"`
}

CommitResourceOutput is the JSON payload returned by the "gitlab://project/{id}/commit/{sha}" resource. It contains the commit's full ID, short ID, title, full message, author name and email, authored/committed timestamps, parent commit IDs, web URL, and optional CommitStatsOutput with addition/deletion totals.

type CommitStatsOutput

type CommitStatsOutput struct {
	Additions int64 `json:"additions"`
	Deletions int64 `json:"deletions"`
	Total     int64 `json:"total"`
}

CommitStatsOutput holds line addition and deletion totals for a single commit, returned as a sub-object of CommitResourceOutput.

type DeployKeyResourceOutput

type DeployKeyResourceOutput struct {
	ID          int64  `json:"id"`
	Title       string `json:"title"`
	Key         string `json:"key"`
	Fingerprint string `json:"fingerprint,omitempty"`
}

DeployKeyResourceOutput is the JSON payload for a single project deploy key, returned by the "gitlab://project/{id}/deploy_key/{deploy_key_id}" resource. It contains the key's ID, title, public key text, and optional SHA256 fingerprint.

type DeploymentResourceOutput

type DeploymentResourceOutput struct {
	ID          int64  `json:"id"`
	IID         int64  `json:"iid"`
	Ref         string `json:"ref"`
	SHA         string `json:"sha"`
	Status      string `json:"status"`
	Environment string `json:"environment,omitempty"`
}

DeploymentResourceOutput is the JSON payload for a single project deployment, returned by the "gitlab://project/{id}/deployment/{deployment_id}" resource. It contains the deployment's ID, IID, ref, SHA, status, and optional environment name.

type DynamicSchemaActionEntry added in v2.0.3

type DynamicSchemaActionEntry struct {
	ID             string   `json:"id"`
	Tool           string   `json:"tool"`
	Domain         string   `json:"domain"`
	Action         string   `json:"action"`
	SchemaURI      string   `json:"schema_uri"`
	MetaSchemaURI  string   `json:"meta_schema_uri,omitempty"`
	Destructive    bool     `json:"destructive"`
	RequiredParams []string `json:"required_params,omitempty"`
}

DynamicSchemaActionEntry describes one executable entry in the dynamic action catalog, returned as a row of the DynamicSchemaIndex payload.

type DynamicSchemaIndex added in v2.0.3

type DynamicSchemaIndex struct {
	URITemplate   string                     `json:"uri_template"`
	ExecuteAction string                     `json:"execute_action"`
	ActionCount   int                        `json:"action_count"`
	Actions       []DynamicSchemaActionEntry `json:"actions"`
}

DynamicSchemaIndex is the JSON payload returned by the "gitlab://schema/dynamic/" resource. It enumerates the canonical "domain.action" IDs accepted by gitlab_execute_action and points to the per-action schema resource.

type EnvironmentResourceOutput

type EnvironmentResourceOutput struct {
	ID    int64  `json:"id"`
	Name  string `json:"name"`
	Slug  string `json:"slug"`
	State string `json:"state"`
	Tier  string `json:"tier,omitempty"`
}

EnvironmentResourceOutput is the JSON payload for a single project environment, returned by the "gitlab://project/{id}/environment/{environment_id}" resource. It contains the environment's ID, name, slug, state, and optional tier ("production", "staging", "testing", "development", or other).

type FeatureFlagResourceOutput

type FeatureFlagResourceOutput struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Active      bool   `json:"active"`
	Version     string `json:"version"`
}

FeatureFlagResourceOutput is the JSON payload for a single project feature flag, returned by the "gitlab://project/{id}/feature_flag/{name}" resource. It contains the flag's name, optional description, active flag, and the strategy version ("legacy" or "new").

type FileBlobResourceOutput

type FileBlobResourceOutput struct {
	FileName        string `json:"file_name"`
	FilePath        string `json:"file_path"`
	Size            int64  `json:"size"`
	Encoding        string `json:"encoding,omitempty"`
	Ref             string `json:"ref"`
	BlobID          string `json:"blob_id"`
	CommitID        string `json:"commit_id"`
	LastCommitID    string `json:"last_commit_id"`
	Content         string `json:"content,omitempty"`
	ContentCategory string `json:"content_category"`
	Truncated       bool   `json:"truncated,omitempty"`
}

FileBlobResourceOutput is the JSON payload returned by the "gitlab://project/{id}/file/{ref}/{path}" resource. Binary content is omitted; only the textual representation is returned (see [decodeFileContent]). Files larger than [fileBlobMaxBytes] are truncated to their metadata with Truncated=true and ContentCategory="truncated".

type GroupResourceOutput

type GroupResourceOutput struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Path        string `json:"path"`
	FullPath    string `json:"full_path"`
	Description string `json:"description"`
	Visibility  string `json:"visibility"`
	WebURL      string `json:"web_url"`
}

GroupResourceOutput is the JSON payload for a GitLab group (used by both the groups listing and the group detail resources). It contains the group's ID, name, path, full path, description, visibility, and web URL.

type IssueResourceOutput

type IssueResourceOutput struct {
	ID        int64    `json:"id"`
	IID       int64    `json:"iid"`
	Title     string   `json:"title"`
	State     string   `json:"state"`
	Labels    []string `json:"labels"`
	Assignees []string `json:"assignees"`
	Author    string   `json:"author"`
	WebURL    string   `json:"web_url"`
	CreatedAt string   `json:"created_at"`
}

IssueResourceOutput is the JSON payload for a single project issue (used by both the issues listing and the issue detail resources). It contains the issue's ID, IID, title, state, labels, assignees (usernames), author username, web URL, and creation timestamp.

type JobResourceOutput

type JobResourceOutput struct {
	ID            int64   `json:"id"`
	Name          string  `json:"name"`
	Stage         string  `json:"stage"`
	Status        string  `json:"status"`
	Ref           string  `json:"ref"`
	Duration      float64 `json:"duration"`
	FailureReason string  `json:"failure_reason,omitempty"`
	WebURL        string  `json:"web_url"`
}

JobResourceOutput is the JSON payload for a single pipeline job returned by the "gitlab://project/{id}/pipeline/{id}/jobs" and "gitlab://project/{id}/job/{job_id}" resources. It contains the job's ID, name, stage, status, ref, duration in seconds, failure reason (omitted when empty), and web URL.

type LabelResourceOutput

type LabelResourceOutput struct {
	ID                     int64  `json:"id"`
	Name                   string `json:"name"`
	Color                  string `json:"color"`
	Description            string `json:"description"`
	OpenIssuesCount        int64  `json:"open_issues_count"`
	OpenMergeRequestsCount int64  `json:"open_merge_requests_count"`
}

LabelResourceOutput is the JSON payload for a single project or group label. It includes the label's ID, name, color (hex), optional description, and the current open issue and open MR counts (used by the label detail and listing resources).

type MRDiscussionNoteResourceOutput

type MRDiscussionNoteResourceOutput struct {
	ID         int64  `json:"id"`
	Author     string `json:"author"`
	Body       string `json:"body"`
	System     bool   `json:"system"`
	Resolved   bool   `json:"resolved"`
	Resolvable bool   `json:"resolvable"`
	CreatedAt  string `json:"created_at,omitempty"`
}

MRDiscussionNoteResourceOutput is the JSON payload for a single note inside a discussion thread, returned as part of the "gitlab://project/{id}/mr/{iid}/discussions" resource. It contains the note's ID, author username, body, system flag, resolved and resolvable flags, and optional creation timestamp.

type MRDiscussionResourceOutput

type MRDiscussionResourceOutput struct {
	ID             string                           `json:"id"`
	IndividualNote bool                             `json:"individual_note"`
	Notes          []MRDiscussionNoteResourceOutput `json:"notes"`
}

MRDiscussionResourceOutput is the JSON payload for a single discussion thread on a merge request. It bundles a thread ID, the individual_note flag (true for non-threaded comments), and the ordered list of notes that make up the thread.

type MRNoteResourceOutput

type MRNoteResourceOutput struct {
	ID         int64  `json:"id"`
	Author     string `json:"author"`
	Body       string `json:"body"`
	System     bool   `json:"system"`
	Resolvable bool   `json:"resolvable,omitempty"`
	Resolved   bool   `json:"resolved,omitempty"`
	CreatedAt  string `json:"created_at,omitempty"`
	UpdatedAt  string `json:"updated_at,omitempty"`
}

MRNoteResourceOutput is the JSON payload for a single merge-request note inside the flat "gitlab://project/{id}/mr/{iid}/notes" list resource. It contains the note's ID, author username, body, system flag, resolvable and resolved flags (omitted when not resolvable), and optional creation and update timestamps.

type MRResourceOutput

type MRResourceOutput struct {
	ID           int64  `json:"id"`
	IID          int64  `json:"iid"`
	Title        string `json:"title"`
	State        string `json:"state"`
	SourceBranch string `json:"source_branch"`
	TargetBranch string `json:"target_branch"`
	Author       string `json:"author"`
	WebURL       string `json:"web_url"`
	MergeStatus  string `json:"merge_status"`
}

MRResourceOutput is the JSON payload returned by the "gitlab://project/{id}/mr/{iid}" resource. It contains the MR's ID, IID, title, state, source and target branches, author username, web URL, and detailed merge status.

type MemberResourceOutput

type MemberResourceOutput struct {
	ID          int64  `json:"id"`
	Username    string `json:"username"`
	Name        string `json:"name"`
	State       string `json:"state"`
	AccessLevel int    `json:"access_level"`
	WebURL      string `json:"web_url"`
}

MemberResourceOutput is the JSON payload for a single member entry in the "gitlab://{project|group}/{id}/members" resources. It includes the member's ID, username, display name, account state, numeric access level (10=guest, 20=reporter, 30=developer, 40=maintainer, 50=owner), and web URL.

type MetaSchemaIndex

type MetaSchemaIndex struct {
	URITemplate string                 `json:"uri_template"`
	Tools       []MetaSchemaIndexEntry `json:"tools"`
}

MetaSchemaIndex is the JSON payload returned by the "gitlab://schema/meta/" resource. It enumerates the meta-tool catalog and points to the per-action schema template.

type MetaSchemaIndexEntry

type MetaSchemaIndexEntry struct {
	Tool    string   `json:"tool"`
	Actions []string `json:"actions"`
}

MetaSchemaIndexEntry is a single tool entry in the MetaSchemaIndex payload: the meta-tool name and the list of its supported action names.

type MilestoneResourceOutput

type MilestoneResourceOutput struct {
	ID          int64  `json:"id"`
	IID         int64  `json:"iid"`
	Title       string `json:"title"`
	Description string `json:"description"`
	State       string `json:"state"`
	DueDate     string `json:"due_date,omitempty"`
	WebURL      string `json:"web_url"`
}

MilestoneResourceOutput is the JSON payload for a single project or group milestone. It includes the milestone's ID, IID, title, description, state (active/closed), optional due date, and web URL.

type PipelineResourceOutput

type PipelineResourceOutput struct {
	ID     int64  `json:"id"`
	IID    int64  `json:"iid"`
	Status string `json:"status"`
	Ref    string `json:"ref"`
	SHA    string `json:"sha"`
	WebURL string `json:"web_url"`
	Source string `json:"source"`
}

PipelineResourceOutput is the JSON payload returned by the pipeline detail resources ("gitlab://project/{id}/pipelines/latest" and "gitlab://project/{id}/pipeline/{pipeline_id}"). It contains the pipeline's ID, IID, status, ref, SHA, web URL, and source ("push", "web", etc.).

type ProjectResourceOutput

type ProjectResourceOutput struct {
	ID                int64  `json:"id"`
	Name              string `json:"name"`
	PathWithNamespace string `json:"path_with_namespace"`
	Visibility        string `json:"visibility"`
	WebURL            string `json:"web_url"`
	Description       string `json:"description"`
	DefaultBranch     string `json:"default_branch"`
}

ProjectResourceOutput is the JSON payload returned by the "gitlab://project/{project_id}" resource. It contains the project's identifying fields, namespace path, visibility, web URL, description, and default branch — enough for clients to render a project card without an extra API call.

type ReleaseResourceOutput

type ReleaseResourceOutput struct {
	TagName     string `json:"tag_name"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Author      string `json:"author"`
	CreatedAt   string `json:"created_at"`
	ReleasedAt  string `json:"released_at,omitempty"`
}

ReleaseResourceOutput is the JSON payload for a single project release (used by both the releases listing and the release detail resources). It contains the tag name, release name, description, author username, creation timestamp, and optional release timestamp.

type SnippetResourceOutput

type SnippetResourceOutput struct {
	ID          int64  `json:"id"`
	Title       string `json:"title"`
	FileName    string `json:"file_name"`
	Description string `json:"description"`
	Visibility  string `json:"visibility"`
	WebURL      string `json:"web_url"`
}

SnippetResourceOutput is the JSON payload for a personal (global) or project snippet, returned by the "gitlab://snippet/{snippet_id}" and "gitlab://project/{id}/snippet/{snippet_id}" resources. It contains the snippet's ID, title, file name, description, visibility, and web URL.

type TagResourceOutput

type TagResourceOutput struct {
	Name      string `json:"name"`
	Message   string `json:"message,omitempty"`
	Target    string `json:"target"`
	Protected bool   `json:"protected"`
	CreatedAt string `json:"created_at,omitempty"`
}

TagResourceOutput is the JSON payload for a single repository tag (used by both the tags listing and the tag detail resources). It contains the tag name, optional annotation message, target commit SHA, protection status, and optional creation timestamp.

type ToolSurfaceCallShape added in v2.0.3

type ToolSurfaceCallShape struct {
	Tool            string `json:"tool"`
	Action          string `json:"action,omitempty"`
	ActionLocation  string `json:"action_location,omitempty"`
	ParamsLocation  string `json:"params_location"`
	ConfirmLocation string `json:"confirm_location,omitempty"`
}

ToolSurfaceCallShape describes how to invoke one manifest entry. ActionLocation and ConfirmLocation are populated only for surfaces where those fields apply (dynamic, meta); they are empty in individual mode.

type ToolSurfaceDetail added in v2.0.3

type ToolSurfaceDetail struct {
	ToolSurfaceEntry
	Call        ToolSurfaceCallShape `json:"call"`
	InputSchema any                  `json:"input_schema,omitempty"`
}

ToolSurfaceDetail is the JSON payload returned by the "gitlab://tools/{id}" resource. It embeds the matching ToolSurfaceEntry and adds the per-entry call shape and input schema.

type ToolSurfaceEntry added in v2.0.3

type ToolSurfaceEntry struct {
	ID             string   `json:"id"`
	Kind           string   `json:"kind"`
	Tool           string   `json:"tool"`
	Action         string   `json:"action,omitempty"`
	Domain         string   `json:"domain,omitempty"`
	BackingTool    string   `json:"backing_tool,omitempty"`
	BackingAction  string   `json:"backing_action,omitempty"`
	Title          string   `json:"title,omitempty"`
	Description    string   `json:"description,omitempty"`
	DetailURI      string   `json:"detail_uri"`
	Destructive    bool     `json:"destructive"`
	ReadOnly       bool     `json:"read_only"`
	RequiredParams []string `json:"required_params,omitempty"`
}

ToolSurfaceEntry describes one executable unit in the active tool surface. Entries can be dynamic actions (gitlab_execute_action surface), meta actions (gitlab_<tool>.<action> surface), or individual tools (one MCP tool per GitLab action).

type ToolSurfaceManifest added in v2.0.3

type ToolSurfaceManifest struct {
	Surface          string                   `json:"surface"`
	URITemplate      string                   `json:"uri_template"`
	VisibleToolCount int                      `json:"visible_tool_count"`
	EntryCount       int                      `json:"entry_count"`
	VisibleTools     []ToolSurfaceVisibleTool `json:"visible_tools"`
	Entries          []ToolSurfaceEntry       `json:"entries"`
}

ToolSurfaceManifest is the JSON payload returned by the "gitlab://tools" resource. It summarizes the active tool surface and lists every executable entry the surface exposes.

type ToolSurfaceResourceOptions added in v2.0.3

type ToolSurfaceResourceOptions struct {
	Surface    string
	Tools      []*mcp.Tool
	Catalog    *actioncatalog.Catalog
	MetaRoutes map[string]toolutil.ActionMap
}

ToolSurfaceResourceOptions captures the active server tool surface for the unified tool manifest resources (RegisterToolSurfaceResources). All three slices are projected differently depending on the surface (see [newToolSurfaceSnapshot]).

type ToolSurfaceVisibleTool added in v2.0.3

type ToolSurfaceVisibleTool struct {
	Name        string `json:"name"`
	Title       string `json:"title,omitempty"`
	DetailURI   string `json:"detail_uri"`
	ReadOnly    bool   `json:"read_only"`
	Destructive bool   `json:"destructive"`
}

ToolSurfaceVisibleTool summarizes one MCP tool currently advertised through tools/list, surfaced in the ToolSurfaceManifest's VisibleTools list.

type UserResourceOutput

type UserResourceOutput struct {
	ID       int64  `json:"id"`
	Username string `json:"username"`
	Name     string `json:"name"`
	Email    string `json:"email"`
	State    string `json:"state"`
	WebURL   string `json:"web_url"`
	IsAdmin  bool   `json:"is_admin"`
}

UserResourceOutput is the JSON payload returned by the "gitlab://user/current" resource. It contains the authenticated user's profile fields: ID, username, display name, email, account state, web URL, and admin status.

type WikiResourceOutput

type WikiResourceOutput struct {
	Title    string `json:"title"`
	Slug     string `json:"slug"`
	Format   string `json:"format"`
	Content  string `json:"content,omitempty"`
	Encoding string `json:"encoding,omitempty"`
}

WikiResourceOutput is the JSON payload returned by the "gitlab://project/{id}/wiki/{slug}" resource. It contains the page title, slug, format (markdown, rdoc, asciidoc, or org), raw content, and encoding (omitted when the API does not return one).

Jump to

Keyboard shortcuts

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