tools package - github.com/jmrplens/gitlab-mcp-server/v2/internal/tools

Documentation ¶

Overview ¶

Package tools provides the MCP tool orchestration layer for the GitLab MCP server.

The package wires the individual, meta, and dynamic GitLab MCP tool surfaces to the server. It delegates domain implementations to internal/tools/{domain} sub-packages, builds the canonical action catalog for catalog-backed surfaces, exposes the gitlab_server meta-tool, applies read-only and safe mode behavior, filters tools by personal access token scopes, and delegates meta-tool Markdown rendering to the type-based registry in internal/toolutil.

Architecture ¶

The high-level registration flow is:

cmd/server
    |
    +--> RegisterAll --> BuildActionCatalog --> RegisterIndividualCatalogTools
    |
    +--> BuildActionCatalog --> RegisterMetaCatalog
    |
    +--> BuildActionCatalog --> dynamic.RegisterCatalogFindExecuteTools

RegisterAll registers the individual tools by projecting the canonical action catalog. BuildActionCatalog builds the catalog used by RegisterIndividualCatalogTools, RegisterMetaCatalog, and dynamic mode. RegisterAllMeta preserves the meta registration entry point by building and registering that catalog. SafeModePreview describes the preview payload returned when safe mode intercepts mutating calls.

Domain packages document the official GitLab API pages they wrap. Keeping those references in package documentation preserves pkgsite discoverability without adding fields to MCP tool schemas or dynamic discovery responses.

Index ¶

Variables
func BuildActionCatalog(client *gitlabclient.Client, opts ActionCatalogOptions) (*actioncatalog.Catalog, error)
func BuildMCPActionGroup(client *gitlabclient.Client, updater *autoupdate.Updater) actioncatalog.Group
func FilterScopeFilteredCatalog(catalog *actioncatalog.Catalog, tokenScopes []string) (*actioncatalog.Catalog, error)
func RegisterAll(server *mcp.Server, client *gitlabclient.Client, enterprise bool)
func RegisterAllMeta(server *mcp.Server, client *gitlabclient.Client, enterprise bool) error
func RegisterIndividualCatalogTools(server *mcp.Server, catalog *actioncatalog.Catalog, ...)
func RegisterMCPMeta(server *mcp.Server, client *gitlabclient.Client, updater *autoupdate.Updater)
func RegisterMetaCatalog(server *mcp.Server, catalog *actioncatalog.Catalog)
func RegisterMetaStandaloneTools(server *mcp.Server, client *gitlabclient.Client)
func RegisterServerMaintenanceSurfaceTools(server *mcp.Server, updater *autoupdate.Updater)
func RegisterSurfaceTools(server *mcp.Server, specs []actioncatalog.SurfaceToolSpec)
func RemoveScopeFilteredTools(server *mcp.Server, tokenScopes []string) int
func ServerMaintenanceSurfaceToolSpecs(updater *autoupdate.Updater) []actioncatalog.SurfaceToolSpec
func SetMetaParamSchema(mode string)
func SetMetaParamSchemaScoped(mode string) func()
func StandaloneSurfaceToolSpecs(client *gitlabclient.Client) []actioncatalog.SurfaceToolSpec
func WrapMutatingToolsForSafeMode(server *mcp.Server) int
type ActionCatalogOptions
type ActionSpecGroup
- func CollectActionSpecs(client *gitlabclient.Client, enterprise bool) []ActionSpecGroup
type IndividualCatalogRegisterOptions
type MetaToolInput
type SafeModePreview

Constants ¶

This section is empty.

Variables ¶

View Source

var MetaToolScopes = map[string][]string{

	"gitlab_admin":           {"admin_mode"},
	"gitlab_enterprise_user": {"admin_mode"},
	"gitlab_project_alias":   {"admin_mode"},
	"gitlab_geo":             {"admin_mode"},
	"gitlab_storage_move":    {"admin_mode"},
}

MetaToolScopes maps meta-tool names to the PAT scopes required for that tool. Tools not listed here have no scope requirement and are always registered. A tool is removed when ANY of its required scopes is missing from the detected token scopes (i.e. all listed scopes must be present).

Scope reference (GitLab PAT scopes):

api              — Full API access (read+write)
read_api         — Read-only API access
read_user        — Read user information
read_repository  — Read repository contents
write_repository — Write to repository
read_registry    — Pull container registry images
write_registry   — Push container registry images
create_runner    — Create runners
manage_runner    — Manage runners
admin_mode       — Admin operations
ai_features      — GitLab Duo API access
k8s_proxy        — Kubernetes API calls via agent
sudo             — Impersonate users

Functions ¶

func BuildActionCatalog ¶

func BuildActionCatalog(client *gitlabclient.Client, opts ActionCatalogOptions) (*actioncatalog.Catalog, error)

BuildActionCatalog builds the canonical action catalog for catalog-backed GitLab action surfaces without constructing an MCP server.

func BuildMCPActionGroup ¶

func BuildMCPActionGroup(client *gitlabclient.Client, updater *autoupdate.Updater) actioncatalog.Group

BuildMCPActionGroup builds the registry group backing the gitlab_server meta-tool.

func FilterScopeFilteredCatalog ¶

func FilterScopeFilteredCatalog(catalog *actioncatalog.Catalog, tokenScopes []string) (*actioncatalog.Catalog, error)

FilterScopeFilteredCatalog removes catalog groups whose required scopes are not satisfied by the detected token scopes. It returns a non-nil error when rebuilding the filtered catalog fails, which means callers could not safely evaluate the scope filter and should propagate the failure.

func RegisterAll ¶

func RegisterAll(server *mcp.Server, client *gitlabclient.Client, enterprise bool)

RegisterAll wires all catalog-backed GitLab MCP tools to the MCP server. When enterprise is false, Premium/Ultimate-only catalog actions are not registered.

func RegisterAllMeta ¶

func RegisterAllMeta(server *mcp.Server, client *gitlabclient.Client, enterprise bool) error

RegisterAllMeta wires meta-tools to the MCP server. Base: 33 tools = 29 meta-tools (25 inline + 3 delegated + 1 standalone) + 4 standalone interactive elicitation tools (gitlab_interactive_*). Enterprise: +14 inline meta-tools = 47 tools total; GitLab.com Enterprise also adds gitlab_orbit. Each meta-tool dispatches to the underlying handler based on the "action" parameter. This reduces token usage for LLMs while preserving full functionality. Interactive tools cannot be consolidated because they require multi-round MCP elicitation/create exchanges with the client. Returns an error if the action catalog cannot be built or if wiring tools to the MCP server fails.

func RegisterIndividualCatalogTools ¶

func RegisterIndividualCatalogTools(server *mcp.Server, catalog *actioncatalog.Catalog, opts IndividualCatalogRegisterOptions)

RegisterIndividualCatalogTools registers individual MCP tools by projecting eligible actions from the canonical action catalog.

func RegisterMCPMeta ¶

func RegisterMCPMeta(server *mcp.Server, client *gitlabclient.Client, updater *autoupdate.Updater)

RegisterMCPMeta registers the gitlab_server meta-tool consolidating MCP server health/status and update operations. If updater is nil, only the status action is available.

func RegisterMetaCatalog ¶

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

RegisterMetaCatalog registers visible meta-tools from the canonical action catalog.

func RegisterMetaStandaloneTools ¶

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

RegisterMetaStandaloneTools wires standalone utility tools that remain visible alongside the catalog-backed meta-tools.

func RegisterServerMaintenanceSurfaceTools ¶

func RegisterServerMaintenanceSurfaceTools(server *mcp.Server, updater *autoupdate.Updater)

RegisterServerMaintenanceSurfaceTools registers visible updater tools when auto-update is enabled.

func RegisterSurfaceTools ¶

func RegisterSurfaceTools(server *mcp.Server, specs []actioncatalog.SurfaceToolSpec)

RegisterSurfaceTools registers visible tools from canonical surface specs.

func RemoveScopeFilteredTools ¶

func RemoveScopeFilteredTools(server *mcp.Server, tokenScopes []string) int

RemoveScopeFilteredTools removes tools whose required scopes are not satisfied by the detected token scopes. Returns the number of tools removed. If tokenScopes is nil (detection unavailable), no tools are removed.

func ServerMaintenanceSurfaceToolSpecs ¶

func ServerMaintenanceSurfaceToolSpecs(updater *autoupdate.Updater) []actioncatalog.SurfaceToolSpec

ServerMaintenanceSurfaceToolSpecs returns updater-backed visible server maintenance tools.

func SetMetaParamSchema ¶

func SetMetaParamSchema(mode string)

SetMetaParamSchema selects the meta-tool input schema strategy used by all meta-tool registrations in this package and its sub-packages. Accepts "opaque" (default), "compact", or "full". Unknown values are coerced to opaque so misconfiguration cannot break tools/list. Must be called before RegisterAllMeta.

func SetMetaParamSchemaScoped ¶

func SetMetaParamSchemaScoped(mode string) func()

SetMetaParamSchemaScoped selects the meta-tool input schema strategy and returns a restore function for tests that temporarily override the global mode. Valid modes match SetMetaParamSchema: "opaque", "compact", and "full". Use it with defer, for example: defer SetMetaParamSchemaScoped("full")().

func StandaloneSurfaceToolSpecs ¶

func StandaloneSurfaceToolSpecs(client *gitlabclient.Client) []actioncatalog.SurfaceToolSpec

StandaloneSurfaceToolSpecs returns visible utility tools that remain outside ordinary GitLab API meta-tool dispatchers.

func WrapMutatingToolsForSafeMode ¶

func WrapMutatingToolsForSafeMode(server *mcp.Server) int

WrapMutatingToolsForSafeMode lists all registered tools via an ephemeral in-memory session and replaces mutating tool handlers (ReadOnlyHint == false) with a handler that returns a SafeModePreview instead of executing. Returns the number of tools wrapped.

Types ¶

type ActionCatalogOptions ¶

type ActionCatalogOptions struct {
	Enterprise bool
	IncludeMCP bool
	Updater    *autoupdate.Updater
	SpecGroups []ActionSpecGroup
}

ActionCatalogOptions controls which action groups are included in the canonical catalog.

type ActionSpecGroup ¶

type ActionSpecGroup = actioncatalog.CatalogGroupSpec

ActionSpecGroup contains specs owned by one catalog group.

func CollectActionSpecs ¶

func CollectActionSpecs(client *gitlabclient.Client, enterprise bool) []ActionSpecGroup

CollectActionSpecs gathers canonical specs from domain-local builders.

type IndividualCatalogRegisterOptions ¶

type IndividualCatalogRegisterOptions struct {
	ApplyEditionFilters        bool
	Enterprise                 bool
	GitLabDotCom               bool
	ReadOnlyOnly               bool
	SafeMode                   bool
	IncludeHiddenActions       bool
	IncludeStandaloneUtilities bool
	AllowedToolNames           []string
	ExcludeToolNames           []string
	DescriptionForTool         func(actioncatalog.Action) string
}

IndividualCatalogRegisterOptions controls how catalog actions are projected into the individual-tool MCP surface.

type MetaToolInput ¶

type MetaToolInput = toolutil.MetaToolInput

MetaToolInput is an alias for toolutil.MetaToolInput.

type SafeModePreview ¶

type SafeModePreview struct {
	Status string          `json:"status"`
	Mode   string          `json:"mode"`
	Tool   string          `json:"tool"`
	Params json.RawMessage `json:"params"`
	Hint   string          `json:"hint"`
}

SafeModePreview is the structured response returned when a mutating tool is called with Safe Mode enabled.

Source Files ¶

View all Source files

Directories ¶

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