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. There is deliberately no one-call entry point for the meta surface: the RegisterAllMeta that used to be one built its catalog without ActionCatalogOptions.IncludeMCP and so registered one tool fewer than the binary serves, which is how the published meta counts came to be off by one (issue 616). A caller registers the meta surface the way cmd/server does, with RegisterMetaCatalog and RegisterMetaStandaloneTools over a catalog it built itself. 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 ExcludedStandaloneTools(excludeTools []string) (toolNames, unmatched []string)
func FilterScopeFilteredCatalog(catalog *actioncatalog.Catalog, tokenScopes []string) (*actioncatalog.Catalog, error)
func IndividualActionCalls(catalog *actioncatalog.Catalog) toolutil.ActionCallResolver
func IndividualSchemaCacheKey(tier edition.Tier) string
func MetaActionCalls(catalog *actioncatalog.Catalog) toolutil.ActionCallResolver
func MetaParamSchema() string
func NewCallIdentifier(catalog *actioncatalog.Catalog, surface string) mcpotel.CallIdentifier
func NewServedCallIdentifier(catalog *actioncatalog.Catalog, surface string) mcpotel.CallIdentifier
func RegisterAll(server *mcp.Server, client *gitlabclient.Client, tier edition.Tier) *actioncatalog.Catalog
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 RegisterMetaStandaloneToolsFor(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 StandaloneActionIDs() map[string]string
func StandaloneSurfaceToolSpecs(client *gitlabclient.Client) []actioncatalog.SurfaceToolSpec
func StandaloneToolsBeyond(token finegrained.ClassicScope) []string
func TierWithheld(dotcom bool, cfg *config.ServerConfig) ([]actioncatalog.TierWithheld, error)
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) []ActionSpecGroup
type IndividualCatalogRegisterOptions
type MetaToolInput
type SafeModePreview
type WithheldActions
- func FilterActionCatalog(catalog *actioncatalog.Catalog, cfg *config.ServerConfig) (*actioncatalog.Catalog, WithheldActions, error)
- func NarrowForReading(catalog *actioncatalog.Catalog, cfg *config.ServerConfig, ...) (*actioncatalog.Catalog, WithheldActions)
- 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. A fine-grained token's list is keyed as nil, the reading the filter gives it (see [scopeCatalogKey]), so it shares the catalog of a classic token whose scopes are unknown and never that of a token with no scope.

The three flags are printed as true or false because this is a map key and not a card. A cache key is compared and never read, so the glyph a reader would want here would only make two configurations that differ collide less legibly.

func ExcludeFromCatalog ¶

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

ExcludeFromCatalog removes the groups and actions an operator excluded, reports how many actions that was, and warns about the entries that named nothing.

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 a catalog action, so a working catalog exclusion logged "excluded=0" and was indistinguishable from one that matched nothing.

The warning is raised here because every surface's catalog passes through this function whenever a shared catalog is built: FilterActionCatalog for the dynamic and meta surfaces, the individual assembler directly. That is once per catalog key rather than once per deployment, and the key carries the tier, the instance class and the part of the credential's scopes that narrows the catalog, so in HTTP mode, where the tier is detected per pool entry unless it is pinned, one deployment can write the warning several times, and an entry reported as naming nothing for a Free caller may still remove actions for an Ultimate one. An entry this catalog does not match may still name a standalone utility, which no surface keeps in this catalog, so what is left is put to ExcludedStandaloneTools before anything is reported. The warning used to be computed against this catalog alone. It named every standalone entry, the working ones among them, and added a note excusing them all as filtered where they are added, which was false of the canonical ID on every surface, so a reader could not tell a dead entry from a live one.

One entry is still reported although it removes something: a name of the dynamic surface's own two tools, gitlab_find_action and gitlab_execute_action, which the pass over registered tools removes by name there. This function knows no surface, and on the other two those names do name nothing.

It stays a warning rather than a refusal: one configuration is routinely reused across Free, Premium and Ultimate instances, and a lower tier's catalog legitimately lacks names the same file carries.

func ExcludedStandaloneTools ¶ added in v3.1.0

func ExcludedStandaloneTools(excludeTools []string) (toolNames, unmatched []string)

ExcludedStandaloneTools resolves an --exclude-tools list against the standalone utilities, and returns the tool names it removes, sorted, together with the entries that named none of them, in the operator's order.

The standalone utilities are the one part of every surface the action catalog does not hold: the meta and individual surfaces register them as tools of their own and narrow them after registration, and the dynamic surface adds them to its catalog after that catalog was filtered. So the catalog's exclusion rule never reached them, and each path kept its own copy, which is how the canonical action ID came to remove a guided flow on no surface at all. Resolving through surfaces.ExcludedToolSpecs puts them under the one rule: a group name (gitlab_interactive), a tool name (gitlab_interactive_issue_create) and a canonical action ID (interactive.issue_create) remove the same tools everywhere.

Three callers ask it: the pass over registered tools on the meta and individual surfaces, the warning about entries that named nothing, which must not report an entry a standalone utility answers, and the end-to-end harness, which has to expect what the binary serves rather than a copy of its rule. The resolution runs on every call, over a spec list built once per process (see standaloneSpecs).

It panics when the specs cannot be assembled, which only a malformed declared spec can cause: those tools are part of the declared surface, and RegisterSurfaceTools stops startup over the same spec the same way.

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.

The list is read through gitlabclient.CatalogScopes first, the one reading CatalogFilterKey applies too, so a fine-grained token, whose list is the single scope granular, is filtered as a token whose scopes are unknown: its list names no legacy scope a group requirement could be met by, and its authority is a grant GitLab judges per call, so no group is removed for it.

func IndividualActionCalls ¶ added in v3.3.0

func IndividualActionCalls(catalog *actioncatalog.Catalog) toolutil.ActionCallResolver

IndividualActionCalls answers how the individual surface calls each action of catalog: by the individual tool name the action declares, gitlab_issue_update for issue.update (issue 1325). No rule derives that name from the ID, so a next step written as the ID named no tool the model could call. A name declared by more than one action belongs to the first in registration order, as registration binds it, and the others are not answered.

func IndividualSchemaCacheKey ¶ added in v3.1.0

func IndividualSchemaCacheKey(tier edition.Tier) string

IndividualSchemaCacheKey names the process-wide compiled-schema cache entry for the individual projection of the catalog built for tier (see IndividualCatalogRegisterOptions.SchemaCacheKey, which toolutil's CompileToolSchemas caches under).

The tier identifies the content because the projection reads the catalog action's route and nothing else: the register options choose which actions are registered and what description each carries, never the shape of a schema, and the tier is what [pruneSchemaFieldsByTier] narrows a schema by. The instance class is deliberately not part of it — a GitLab.com catalog carries actions a self-managed one does not, and the tools both carry project the same schemas — and neither is anything about the credential, since the only thing a client changes in a catalog is its handlers.

It is one function rather than the three copies of the same string it replaces (this package, cmd/server and cmd/internal/mcpsurface) because a key whose whole contract is "the same content is named the same way" cannot be left to three places to spell alike. A catalog built with ActionCatalogOptions.SpecGroups overrides is not the tier's catalog and must not be registered under this key.

func MetaActionCalls ¶ added in v3.3.0

func MetaActionCalls(catalog *actioncatalog.Catalog) toolutil.ActionCallResolver

MetaActionCalls answers how the meta surface calls each action of catalog: the meta tool of the action's group with the action's name within it, "gitlab_issue with action 'update'" for issue.update (issue 1325). The meta tool's action argument refuses a canonical ID, so a next step written as one was a call the model could not make as written. An action catalog does not hold, which the surface therefore does not serve, is not answered, and the step that names it is left as it was written.

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 NewServedCallIdentifier ¶ added in v3.1.0

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

NewServedCallIdentifier is NewCallIdentifier for the server that registered catalog on surface, which on two surfaces serves more than the catalog holds.

The meta and individual surfaces register the standalone utilities (gitlab_discover_project and the gitlab_interactive_* flows) as tools of their own, through RegisterMetaStandaloneTools, beside a catalog that carries none of them. A resolver reading only that catalog left every call to one of those tools without an action on its span, so a deployment on either surface could not see them in its telemetry while the dynamic surface, whose catalog does carry them, could. This adds them, keyed by the tool name they are registered under, and consults them only when the surface's own reading does not know the tool: the catalog is always asked first, so nothing it names can be shadowed.

The dynamic surface is left alone because it needs nothing: its catalog holds the standalone groups, and a tool name there is never the operation. A missing catalog names nothing, as it does for NewCallIdentifier.

The index holds every standalone tool the surface registers and is not narrowed by the visibility pass that runs after registration. That pass removes a tool an --exclude-tools entry names, by its tool name, its group name or its canonical action ID (see ExcludedStandaloneTools), for a read_api token every tool whose action GitLab answers only from api (see StandaloneToolsBeyond), and, in read-only mode, every tool that does not read, and the index still names the removed ones. A call to one of them is therefore attributed to the action the client asked for, and the server then refuses it as a tool it does not serve. The individual surface already treats a catalog tool read-only removed that way, since its catalog is narrowed by exclusions and scopes only; the dynamic surface does not, because its catalog is filtered before anything is registered, so an action withheld there is named by nothing.

It is a separate constructor rather than a change to NewCallIdentifier because that one answers what a catalog names, and the model evaluation's scoring reads it on those terms.

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 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 registers the standalone utility tools, which the action catalog does not hold, as tools of their own beside the catalog-backed tools of the meta and individual surfaces: the project discovery helper (gitlab_discover_project) and the guided elicitation flows (gitlab_interactive_*). The dynamic surface adds the same specs (StandaloneSurfaceToolSpecs) to its own catalog instead.

func RegisterMetaStandaloneToolsFor ¶ added in v3.3.0

func RegisterMetaStandaloneToolsFor(server *mcp.Server, client *gitlabclient.Client, calls toolutil.ActionCallResolver)

RegisterMetaStandaloneToolsFor is RegisterMetaStandaloneTools for a surface whose tools are not called by canonical ID: the next steps the standalone tools write are resolved by calls, MetaActionCalls or IndividualActionCalls of the catalog the surface serves (issue 1325). A nil calls leaves them as they are written.

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 RegisterMetaCatalog.

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.

The reach of a credential carrying read_api and not api is applied here too, after the group scopes, for the same reason: the individual surface's read-only pass after registration reads each tool's annotation, which is the operator's rule, while what read_api reaches is decided per action from what it sends (ADR-0026), which only the catalog carries.

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 StandaloneActionIDs ¶ added in v3.2.0

func StandaloneActionIDs() map[string]string

StandaloneActionIDs maps each standalone utility's registered tool name to its canonical action ID, read from the same index the served call identifier uses. The meta and individual surfaces register those tools beside their catalogs, and this is how a reader of one of their tools finds the action it is. The map is the caller's to keep.

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 StandaloneToolsBeyond ¶ added in v3.2.0

func StandaloneToolsBeyond(token finegrained.ClassicScope) []string

StandaloneToolsBeyond names the standalone utility tools whose action needs a classic scope a token whose strongest scope is token does not reach, judged by the same rule as every catalog action (actioncatalog.ClassicNeedOf): what the generated table derived from the requests the action sends, never its annotation. The meta and individual surfaces register these tools outside the catalog, so the read_api narrowing reaches them only through this list, which the pass over registered tools removes (internal/tools/toolvisibility).

func TierWithheld ¶ added in v3.3.0

func TierWithheld(dotcom bool, cfg *config.ServerConfig) ([]actioncatalog.TierWithheld, error)

TierWithheld lists every key of an action the licensing tier of cfg removes from the catalog an instance class starts from, each with the lowest tier that serves it, leaving out every action cfg's exclusions name (issue 956).

The tier filter runs while the catalog is built, before anything FilterActionCatalog records, so an action it removed reached none of the withheld bookkeeping: the dynamic surface answered a call for one with "unknown action" and near-miss suggestions, which reads as a capability the server lacks, and dropped every cross-link to one. Recording them lets it answer that the action exists and needs a higher tier, which an operator can pin when detection was wrong, and publish the links as it publishes the ones the other filters withheld.

An action the operator excluded by name is left out whatever tier it needs, as WithheldActions.ExcludedByName is kept out of the other two lists: naming it back would contradict the exclusion (register row AUT-004). The operator's entries are resolved against the removed actions themselves, since the catalog the exclusions are otherwise resolved against no longer holds them.

The removed actions are read once per tier and instance class for the process; at Ultimate nothing is removed and nothing is read.

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) []ActionSpecGroup

CollectActionSpecs gathers canonical specs from domain-local builders and returns them in deterministic, sorted order. client is forwarded to every builder so GitLab.com detection and edition-sensitive specs can be assembled correctly. The result is every tier's specs, each tagged with its minimum tier: it is the input to BuildActionCatalog, whose tier filter decides which of them an instance is served.

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.

ExcludeToolNames is not how the server applies --exclude-tools, and no production path sets it. It matches a projected individual tool name exactly, while an operator's entry may also be a group name or a canonical action ID. The server narrows the catalog through ExcludeFromCatalog before this projection runs and narrows the standalone utilities through ExcludedStandaloneTools, so both paths ask the catalog's one rule; setting this field for that purpose would add the kind of private matcher that rule replaced.

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 []actioncatalog.ScopeWithheld
	ByOperator   []string
	// ByTier are the actions the instance's licensing tier removed, each key
	// with the lowest tier that serves its action, recorded by [TierWithheld]
	// rather than by [FilterActionCatalog], since the tier filter runs before
	// any catalog that function sees exists. Only the operator can change the
	// tier, so the answer to one asks the operator, as for ByOperator, and
	// says which tier the action needs (issue 956). No action ExcludedByName
	// is among them.
	ByTier []actioncatalog.TierWithheld
	// 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, and that half names the scopes each action needs that the credential lacks, so the message can say which to reauthorize with.

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 scopes the credential's catalog groups demand (admin_mode), then read-only mode, then the API scope a credential carrying read_api and not api reaches (ADR-0026), then safe-mode previews. The returned bookkeeping names what the scope, read-only and reach steps removed.

Read-only mode runs before the reach step so that an action both would remove is reported as the operator's: a write in a read-only deployment is not the credential's to fix, and blaming it would send a caller to reauthorize for nothing. What the reach step removes after it is what GitLab refuses read_api although the catalog classifies it as a read. The group step runs before both and removes writes too, so a write it removes from a read-only deployment is filed under the operator for the same reason, whatever scope the credential lacks besides.

func NarrowForReading ¶ added in v3.2.0

func NarrowForReading(catalog *actioncatalog.Catalog, cfg *config.ServerConfig, withheld WithheldActions) (*actioncatalog.Catalog, WithheldActions)

NarrowForReading applies the two narrowings that turn on whether an action writes, in the order FilterActionCatalog runs them: read-only mode, which keeps the actions the catalog classifies as reads and files the rest under the operator, then the reach of a credential carrying read_api and not api, which keeps the actions GitLab accepts from read_api and files the rest under the token's scope. It adds to withheld what each removed and returns it with the narrowed catalog.

It is exported for the dynamic surface, which adds the standalone utilities after the catalog is filtered and applies these two to the whole catalog again so that a guided flow they withhold is reported with its cause rather than as unknown. Both steps keep what they already kept, so the actions the first pass narrowed are not filed twice.

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