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.

Catalog-first registration ¶

The package follows the catalog-first registration model documented in ADR-0014. The canonical actioncatalog.Catalog produced by BuildActionCatalog is the single source of truth for ordinary GitLab API actions and feeds every catalog-backed surface:

meta tools registered by RegisterMetaCatalog
individual tools projected by RegisterIndividualCatalogTools
the dynamic find/execute registry in internal/tools/dynamic
the gitlab://tools schema resource in internal/resources
audits, LLM files, and the model-eval surfaces

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, tier edition.Tier)
func RegisterAllMeta(server *mcp.Server, client *gitlabclient.Client, tier edition.Tier) 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.

It collects domain-local [ActionSpecGroup]s via CollectActionSpecs, merges any opts.SpecGroups overrides into them, materializes each group through actioncatalog.GroupFromSpecs, adds the MCP maintenance group when opts.IncludeMCP is set, and finally calls actioncatalog.Catalog.Validate to surface ownership, schema, and surface classification errors before any runtime surface registers from the result.

The returned catalog is the source of truth for RegisterMetaCatalog, RegisterIndividualCatalogTools, and the dynamic find/execute registry. Returns a wrapped error for any group construction, addition, or validation failure so callers can present a clear "build catalog group" / "add catalog group" / "validate action catalog" message.

func BuildMCPActionGroup ¶

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

BuildMCPActionGroup builds the registry group backing the gitlab_server meta-tool. The group always exposes status and health_check actions; when updater is non-nil it also exposes check_update (read-only) and apply_update (destructive). The custom description documents the available actions and their semantics for the schema resource.

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. A nil input catalog returns an empty catalog; nil token scopes return a defensive clone of the source catalog.

func RegisterAll ¶

func RegisterAll(server *mcp.Server, client *gitlabclient.Client, tier edition.Tier)

RegisterAll wires all catalog-backed GitLab MCP tools to the MCP server. Catalog actions are gated to the supplied instance tier: an action is registered only when its minimum required tier is at most tier (Free ⊂ Premium ⊂ Ultimate). The function panics on catalog construction failure so startup fails fast rather than booting a partial MCP server.

func RegisterAllMeta ¶

func RegisterAllMeta(server *mcp.Server, client *gitlabclient.Client, tier edition.Tier) 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. The tier gates Premium/Ultimate actions per the central catalog tier filter.

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 onto the supplied server. Nil server or catalog inputs are accepted as no-ops so startup paths that pre-flight the catalog remain safe. The function applies the gating rules documented on IndividualCatalogRegisterOptions in order: edition → surface kind → allow/exclude → read-only filter.

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. Catalog construction failures are logged and the function returns without registering.

func RegisterMetaCatalog ¶

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

RegisterMetaCatalog registers visible meta-tools from the canonical action catalog. Each catalog group becomes one visible MCP meta-tool whose name matches the group ToolName and whose routes come from the group's actioncatalog.Group.ActionMap. Read-only groups use toolutil.AddReadOnlyMetaTool so the registered annotations reflect the read-only semantics; mutating groups use toolutil.AddMetaTool. Nil server or catalog inputs are accepted as no-ops.

func RegisterMetaStandaloneTools ¶

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

RegisterMetaStandaloneTools wires standalone utility tools that remain visible alongside the catalog-backed meta-tools. Today this is the set of interactive elicitation tools (gitlab_interactive_*).

func RegisterServerMaintenanceSurfaceTools ¶

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

RegisterServerMaintenanceSurfaceTools registers visible updater tools when auto-update is enabled. When the updater is nil, no tools are registered.

func RegisterSurfaceTools ¶

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

RegisterSurfaceTools registers visible tools from canonical surface specs. Each spec is projected through toolutil.RegisterSurfaceToolFromSpec and panics on projection failure because surface tools are part of the declared MCP surface and a malformed spec should fail startup.

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. Logs a debug entry per removed tool and an info entry summarizing the removal.

func ServerMaintenanceSurfaceToolSpecs ¶

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

ServerMaintenanceSurfaceToolSpecs returns updater-backed visible server maintenance tools. When the updater is nil, the returned slice is empty so RegisterServerMaintenanceSurfaceTools has nothing to register.

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. The list currently includes the interactive elicitation tools (gitlab_interactive_*) and the project discovery helper (gitlab_discover_project).

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. If listing tools fails, logs the error and returns 0.

Types ¶

type ActionCatalogOptions ¶

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

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

Tier is the effective instance licensing tier; an action is included only when its per-action minimum tier (derived from toolutil.ActionSpec.Edition via edition.TierFromEdition) is at most Tier. Enterprise is a deprecated back-compat selector retained for callers and tests that predate the 3-tier model: when Tier is the zero value (edition.Free) and Enterprise is true, the effective tier is edition.Ultimate (all tools), preserving the historical "enterprise = show everything" behavior. IncludeMCP adds the gitlab_server maintenance group; Updater enables the apply_update/check_update actions inside that group; SpecGroups injects additional ActionSpecGroup overrides that merge on top of the collected domain specs.

type ActionSpecGroup ¶

type ActionSpecGroup = actioncatalog.CatalogGroupSpec

ActionSpecGroup contains specs owned by one catalog group.

It is an alias for actioncatalog.CatalogGroupSpec; the alias keeps the domain builders free of cross-package dependencies while preserving a single canonical type for catalog projection.

func CollectActionSpecs ¶

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

CollectActionSpecs gathers canonical specs from domain-local builders and returns them in deterministic, sorted order. The enterprise flag toggles Premium/Ultimate domains; client is forwarded to every builder so GitLab.com detection and edition-sensitive specs can be assembled correctly. The result is the input to BuildActionCatalog.

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.

ApplyEditionFilters enables CE/Enterprise/GitLab.com gating; Enterprise and GitLabDotCom flag the deployment type. ReadOnlyOnly restricts registration to read-only actions. SafeMode routes mutating actions through the safe-mode preview handler. IncludeHiddenActions keeps individual tools whose toolutil.IndividualToolSpec.Hidden flag is true. IncludeStandaloneUtilities allows runtime/interactive/server maintenance utility groups. AllowedToolNames and ExcludeToolNames are post-filter allow/exclude lists. DescriptionForTool computes a per-action description when the spec does not provide one.

type MetaToolInput ¶

type MetaToolInput = toolutil.MetaToolInput

MetaToolInput is an alias for toolutil.MetaToolInput kept for backward compatibility with sub-package code that imports the alias from the tools namespace.

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. Status is always "blocked", Mode is "safe", Tool is the registered tool name, Params mirrors the would-be call arguments, and Hint tells the operator how to disable safe mode.

Source Files ¶

View all Source files

Directories ¶

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