tools package - github.com/jmrplens/gitlab-mcp-server/v3/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, one tool short of the meta surface cmd/server serves: the binary asks BuildActionCatalog for the gitlab_server diagnostics group through ActionCatalogOptions.IncludeMCP, which RegisterAllMeta does not. 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 BaseCatalogKey(tier edition.Tier, dotcom, includeMCP bool) string
func BuildActionCatalog(client *gitlabclient.Client, opts ActionCatalogOptions) (*actioncatalog.Catalog, error)
func BuildMCPActionGroup(client *gitlabclient.Client) actioncatalog.Group
func CatalogFilterKey(cfg *config.ServerConfig) string
func ExcludeFromCatalog(catalog *actioncatalog.Catalog, excludeTools []string) *actioncatalog.Catalog
func FilterScopeFilteredCatalog(catalog *actioncatalog.Catalog, tokenScopes []string) (*actioncatalog.Catalog, error)
func MetaParamSchema() string
func NewCallIdentifier(catalog *actioncatalog.Catalog, surface string) mcpotel.CallIdentifier
func RegisterAll(server *mcp.Server, client *gitlabclient.Client, tier edition.Tier) *actioncatalog.Catalog
func RegisterAllMeta(server *mcp.Server, client *gitlabclient.Client, tier edition.Tier) error
func RegisterIndividualCatalogTools(server *mcp.Server, catalog *actioncatalog.Catalog, ...)
func RegisterMetaCatalog(server *mcp.Server, catalog *actioncatalog.Catalog)
func RegisterMetaStandaloneTools(server *mcp.Server, client *gitlabclient.Client)
func RegisterSurfaceTools(server *mcp.Server, specs []actioncatalog.SurfaceToolSpec)
func RemoveNonReadOnlyTools(ctx context.Context, server *mcp.Server) int
func RemovedActionKeys(before, after *actioncatalog.Catalog) []string
func SetMetaParamSchema(mode string)
func SetMetaParamSchemaScoped(mode string) func()
func SharedBaseCatalog(dotcom bool, opts ActionCatalogOptions) (*actioncatalog.Catalog, error)
func SharedIndividualCatalog(client *gitlabclient.Client, cfg *config.ServerConfig) (*actioncatalog.Catalog, []string, error)
func StandaloneSurfaceToolSpecs(client *gitlabclient.Client) []actioncatalog.SurfaceToolSpec
func UnboundClient(dotcom bool) *gitlabclient.Client
func WrapMutatingToolsForSafeMode(ctx context.Context, server *mcp.Server) int
func WrapMutatingToolsForSafeModeExcept(ctx context.Context, server *mcp.Server, exempt map[string]struct{}) int
type ActionCatalogOptions
type ActionSpecGroup
- func CollectActionSpecs(client *gitlabclient.Client, enterprise bool) []ActionSpecGroup
type IndividualCatalogRegisterOptions
type MetaToolInput
type SafeModePreview
type WithheldActions
- func FilterActionCatalog(catalog *actioncatalog.Catalog, cfg *config.ServerConfig) (*actioncatalog.Catalog, WithheldActions, error)
- func ShareCatalog(key string, build func() (*actioncatalog.Catalog, WithheldActions, error)) (*actioncatalog.Catalog, WithheldActions, error)
- func SharedMetaCatalog(client *gitlabclient.Client, cfg *config.ServerConfig) (*actioncatalog.Catalog, WithheldActions, error)

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

The keys are meta-tool group names, and the filter is applied to the **catalog** rather than to registered tool names, which is what lets one set of keys reach all three surfaces. FilterScopeFilteredCatalog matches them against Group.ToolName, so on the dynamic and meta surfaces it removes the group a caller would name, and on the individual surface it removes every action projected from that group before any of them is registered.

That last part is the whole reason this comment is here. Until 3.0.0 the individual surface was filtered by a second pass over registered tool names, and nothing on that surface is ever named gitlab_admin: one tool is registered per action, so the pass matched nothing and every admin tool stayed listed for a token with no admin_mode. The calls themselves were refused, by GitLab, with a 403, so what was wrong was the listing rather than the authorization, which is the worse half to leave: a model reads tools/list to decide what is possible and concluded the capability was there. The fix is the shape the exclusion filter already had, and lives in SharedIndividualCatalog.

A group belongs in this map only when **every** action in it needs the scopes, because the removal is all-or-nothing per group. A domain that mixes read and write actions (gitlab_runner, say) is deliberately absent: removing it whole because the token cannot write would hide the reads that work.

gitlab_admin is the entry that tests that rule hardest, and the granularity is known to be slightly over-broad there: a handful of its 92 actions are reads GitLab serves to any authenticated token (topic_list, topic_get, broadcast_message_list, broadcast_message_get), and a token with no admin_mode loses them along with the 88 that genuinely need it. That is the direction to err in, and it is not new: the same removal has applied on the meta and dynamic surfaces since the filter existed, so what changed in 3.0.0 is that the individual surface stopped being the exception. Splitting those reads out means per-action requirements rather than per-group, which is a change to what all three surfaces serve and wants deciding as such.

Functions ¶

func BaseCatalogKey ¶

func BaseCatalogKey(tier edition.Tier, dotcom, includeMCP bool) string

BaseCatalogKey names the unfiltered catalog a configuration starts from: the tier, the instance class and whether the maintenance group is in.

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.

The catalog is built once per tier and instance class for the process and shared (see SharedBaseCatalog); what this returns is that shared catalog bound to client, so its handlers run under client's credential and its metadata is the same the next caller gets. Only a call carrying opts.SpecGroups, which is a test override with no cheap identity, builds a private catalog bound as it is built.

func BuildMCPActionGroup ¶

func BuildMCPActionGroup(client *gitlabclient.Client) actioncatalog.Group

BuildMCPActionGroup builds the registry group backing the gitlab_server meta-tool. The custom description documents the available actions and their semantics for the schema resource.

The group is read-only. It used to gain check_update and apply_update when a self-updater was configured, and apply_update was the only destructive action this server had that acted on the machine rather than on GitLab. Self-update is gone: every distribution channel already owns the binary, and the update path was the one place this server fetched and executed code at runtime.

func CatalogFilterKey ¶

func CatalogFilterKey(cfg *config.ServerConfig) string

CatalogFilterKey names the narrowing FilterActionCatalog applies from a server configuration, so two servers narrowed the same way share one filtered catalog.

The scope component is not the token's scope list but the part of it the filter can act on, canonicalized by [catalogRelevantScopes]: sorted, because GitLab lists a token's scopes in no order this cares about, deduplicated, and reduced to the scopes MetaToolScopes requires, because those are the only ones that change the result. Everything else a token carries would add keys to a cache that never evicts, at the choosing of whoever minted the token. A nil list is still told apart from an empty one, because the scope filter treats the two differently: nil means detection was unavailable.

func ExcludeFromCatalog ¶

func ExcludeFromCatalog(catalog *actioncatalog.Catalog, excludeTools []string) *actioncatalog.Catalog

ExcludeFromCatalog removes the groups and actions an operator excluded, and reports how many actions that was.

The count is the point. Removal already worked on the dynamic and meta surfaces, but the only line an operator saw came from the registered-tool filter, which counts registered tool names: on the dynamic surface there are two of them and neither is ever an exclusion target, so a working exclusion logged "excluded=0" and was indistinguishable from one that matched nothing.

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 MetaParamSchema ¶

func MetaParamSchema() string

MetaParamSchema reports the strategy SetMetaParamSchema selected: "opaque", "compact" or "full".

func NewCallIdentifier ¶

func NewCallIdentifier(catalog *actioncatalog.Catalog, surface string) mcpotel.CallIdentifier

NewCallIdentifier builds the resolver that tells instrumentation what a tools/call actually invokes, for the surface this process registered.

The tool name is the operation on exactly one surface, and on that one it is declared rather than derived:

surface     tool                    action argument   canonical id
dynamic     gitlab_execute_action   issue.list        the argument, resolved
meta        gitlab_issue            list              domain + "." + argument
individual  gitlab_issue_list       absent            declared, so looked up

The individual row is what forces a catalog. Tool names there come from each ActionSpec, with a large legacy verb-first set (gitlab_list_issue_discussions, gitlab_add_ssh_key) beside newer domain-first ones, so no string transformation recovers the action. CLAUDE.md states it directly: never infer one from a formula.

Why the surface is a parameter ¶

It is decided before the process starts and cannot change while it runs, so there is nothing to discover per request. An earlier version ignored it and tried each shape in turn: individual lookup, then decode, then meta, then dynamic. That worked, and it was dishonest in two ways. It built three maps where one is needed, keeping roughly a thousand entries alive twice over for nothing. And a fallback chain reads as though it were resolving an ambiguity, which invites the next reader to work out what happens when two surfaces claim one name, when in fact only one surface is ever registered.

func RegisterAll ¶

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

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. It returns the catalog it registered from. Callers that need to map a tool name back to its canonical action, which on this surface nothing else can do because the names are declared per ActionSpec rather than derived, would otherwise have to build the same catalog a second time. Discarding it is what left telemetry unable to record an action on the individual surface: the resolver degraded correctly to no attribute, on the one surface with a thousand tools.

func RegisterAllMeta ¶

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

RegisterAllMeta wires meta-tools to the MCP server.

Free/CE registers 33 tools: 28 domain meta-tools, gitlab_discover_project and the four gitlab_interactive_* elicitation tools. Premium adds 6 meta-tools (39), self-managed Ultimate 11 more (50), and GitLab.com Ultimate adds gitlab_orbit (51). The counts are pinned by the tests in register_test.go.

These are one short of what the binary serves on the meta surface, which is 34/40/51/52: cmd/server builds its catalog with ActionCatalogOptions.IncludeMCP, so the served surface also carries the gitlab_server diagnostics tool. This function does not, because the catalog it builds here asks for no MCP group.

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 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 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 RemoveNonReadOnlyTools ¶

func RemoveNonReadOnlyTools(ctx context.Context, server *mcp.Server) int

RemoveNonReadOnlyTools removes every registered tool that does not advertise ReadOnlyHint, implementing read-only mode for surfaces whose tools map one to one onto actions. Returns the number of tools removed.

Dispatcher surfaces (meta-tools, the dynamic execute tool) must not rely on this: one of their tools covers many actions, so read-only filtering happens in the catalog instead — see actioncatalog.Catalog.FilterReadOnlyActions.

func RemovedActionKeys ¶

func RemovedActionKeys(before, after *actioncatalog.Catalog) []string

RemovedActionKeys lists every canonical action ID, and every alias resolving to one, that `before` carried and `after` does not.

Aliases count because a caller who asked find for an action before the narrowing, or who is working from documentation, names the action the way the catalog used to: answering only the canonical form leaves the alias reported as a typo, which is the misdiagnosis this exists to prevent.

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 SharedBaseCatalog ¶

func SharedBaseCatalog(dotcom bool, opts ActionCatalogOptions) (*actioncatalog.Catalog, error)

SharedBaseCatalog returns the shared, unbound catalog for a tier and instance class, building it on first use with UnboundClient. Callers that want a catalog to register from want BuildActionCatalog, which binds this one; this is for the assemblers that filter it before binding.

func SharedIndividualCatalog ¶

func SharedIndividualCatalog(client *gitlabclient.Client, cfg *config.ServerConfig) (*actioncatalog.Catalog, []string, error)

SharedIndividualCatalog returns the catalog the individual surface registers for cfg, with the operator's exclusions and the credential's scopes applied and bound to client, and the canonical IDs those exclusions removed. The exclusions are applied to the catalog rather than to registered names, for the reason [registerConfiguredToolSurface] gives: only the catalog can map all three spellings an operator writes.

The scope filter is applied here for a related but distinct reason. Its keys are meta-tool group names, and this surface registers one tool per action, so nothing it names is ever a registered tool name here: filtering registered names after registration, which is what this surface used to be given, could only ever remove nothing, and every admin tool stayed listed for a token with no admin_mode. The calls were refused by GitLab with a 403, so the defect was in what the listing claimed rather than in what the server allowed, which is the worse half to leave: a model reads tools/list to decide what is possible, and concluded the capability was there.

Only the withheld-by-exclusion IDs are returned, and deliberately: they narrow the resource and prompt surfaces, because an action the operator removed must not stay readable through a second request path. A scope-removed action needs no such treatment, since the credential that cannot call it cannot read it either, and the two filtered surfaces make the same split.

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 UnboundClient ¶

func UnboundClient(dotcom bool) *gitlabclient.Client

UnboundClient returns the credential-less client a shared catalog is built with, for the instance class dotcom selects. See gitlabclient.NewUnboundClient for why the shared copy must not be built with a real one.

func WrapMutatingToolsForSafeMode ¶

func WrapMutatingToolsForSafeMode(ctx context.Context, 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.

func WrapMutatingToolsForSafeModeExcept ¶

func WrapMutatingToolsForSafeModeExcept(ctx context.Context, server *mcp.Server, exempt map[string]struct{}) int

WrapMutatingToolsForSafeModeExcept wraps mutating tools as WrapMutatingToolsForSafeMode does, skipping the named tools.

Dispatcher surfaces exempt their catalog-backed tools because those already preview per action; wrapping them would block the reads they also serve. Any tool registered outside the catalog — the interactive gitlab_interactive_* utilities, for instance — must still be wrapped here, or safe mode would let it execute for real.

Types ¶

type ActionCatalogOptions ¶

type ActionCatalogOptions struct {
	Tier       edition.Tier
	Enterprise bool
	IncludeMCP bool
	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; 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
	// SchemaCacheKey, when non-empty, enables process-wide reuse of compiled
	// tool schemas across registrations (see toolutil.CompileToolSchemas).
	// It must uniquely identify the catalog's schema content — RegisterAll
	// passes the instance tier. Leave empty when the schemas may vary for
	// the same tier (none of the production surfaces do).
	SchemaCacheKey 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 = toolutil.SafeModePreview

SafeModePreview is the structured response returned when a mutating operation is intercepted by Safe Mode. It aliases toolutil.SafeModePreview so individual tool wrapping and the per-action interception used by dispatcher surfaces return the identical payload.

type WithheldActions ¶

type WithheldActions struct {
	ByTokenScope []string
	ByOperator   []string
	// ExcludedByName are the actions --exclude-tools removed. They are kept
	// apart from the two above and never reach the dynamic registry's
	// withheld lists: a withheld action is one the model is told about so it
	// can act on the reason, and naming an excluded tool would both leak the
	// configuration and contradict the exclusion. They are recorded because
	// the tool surface is not the only request path to the same GitLab
	// object, and resources/read has to be narrowed by the same decision.
	ExcludedByName []string
}

WithheldActions records the catalog actions a filter removed, split by whose decision it was. Only the token-scope half is something the caller can act on, so the two must not be merged into one message.

func FilterActionCatalog ¶

func FilterActionCatalog(catalog *actioncatalog.Catalog, cfg *config.ServerConfig) (*actioncatalog.Catalog, WithheldActions, error)

FilterActionCatalog applies a deployment's narrowing to a catalog, in the order that keeps the causes apart: the operator's exclusions first, then the credential's scopes, then read-only mode, then safe-mode previews. The returned bookkeeping names what the scope and read-only steps removed.

func ShareCatalog ¶

func ShareCatalog(key string, build func() (*actioncatalog.Catalog, WithheldActions, error)) (*actioncatalog.Catalog, WithheldActions, error)

ShareCatalog returns the catalog cached under key, building it with build on the first call and marking the result shared (see actioncatalog.Catalog.MarkShared). Concurrent callers for one key wait for the one build; callers for different keys build in parallel. A failed build is not cached, so the next caller tries again and reports the same error rather than a stale one.

The returned catalog is the shared, unbound copy: its handlers refuse every call. Bind it with actioncatalog.Catalog.BindTo before registering anything from it.

func SharedMetaCatalog ¶

func SharedMetaCatalog(client *gitlabclient.Client, cfg *config.ServerConfig) (*actioncatalog.Catalog, WithheldActions, error)

SharedMetaCatalog returns the catalog the meta surface registers for cfg, narrowed by FilterActionCatalog and bound to client, together with what the narrowing withheld. One filtered catalog is built per distinct narrowing and shared by every server that needs it.

Directories ¶

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