actioncatalog

package
v2.0.5 Latest Latest
Warning

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

 Go to latest Published: May 22, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package actioncatalog provides the canonical GitLab action catalog shared by catalog-backed MCP tool surfaces.

The catalog is the intermediate action core between typed GitLab handlers and the public meta and dynamic tool surfaces. It stores executable actions as deterministic groups, preserving route metadata such as input schemas, output schemas, destructive flags, action aliases, tags, icons, descriptions, and formatter hooks.

Action IDs use the stable domain.action form derived from the backing meta-tool name and action name. For example, gitlab_project/create becomes project.create, and gitlab_merge_request/list becomes merge_request.list. Dynamic mode uses these IDs directly, while meta-tools expose the same routes through action dispatch inside domain tools.

This package is not the registry for individual MCP tools. Individual tools are still registered directly by internal/tools.RegisterAll for compatibility. Meta-tools and dynamic tools consume this catalog through adapters such as internal/tools.RegisterMetaCatalog and internal/tools/dynamic.NewRegistryFromCatalog.

Invariants

Catalog construction must be deterministic. Groups preserve explicit action order for user-facing descriptions, cloning avoids mutable alias/schema sharing between surfaces, and validation rejects duplicate action IDs or ambiguous aliases before tools are registered.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DomainFromToolName 

func DomainFromToolName(toolName string) string

DomainFromToolName returns the canonical dynamic domain for a meta-tool name.

func ToActionMaps 

func ToActionMaps(catalog *Catalog) map[string]toolutil.ActionMap

ToActionMaps returns legacy route maps for compatibility with existing schema resources, audits, and registration paths.

Types

type Action 

type Action struct {
	ID                     ActionID
	ToolName               string
	Domain                 string
	Name                   string
	Route                  toolutil.ActionRoute
	SchemaURI              string
	Aliases                []string
	Tags                   []string
	Usage                  string
	RelatedActions         []string
	Compatibility          toolutil.CompatibilityPolicy
	ReadOnly               bool
	Edition                string
	GitLabDotComOnly       bool
	OwnerPackage           string
	IndividualTool         toolutil.IndividualToolSpec
	ContentKind            string
	NotFoundPolicy         string
	EmbeddedResourcePolicy string
	RichResultPolicy       string
	SchemaValidationNotes  []string
	RuntimeValidationNotes []string
	SpecBacked             bool
	Destructive            bool
	Idempotent             bool
	OpenWorld              bool
}

Action describes one executable GitLab action in the canonical catalog.

func ActionsFromSpecs 

func ActionsFromSpecs(specs []toolutil.ActionSpec) ([]Action, error)

ActionsFromSpecs projects canonical action specs into catalog actions.

type ActionID 

type ActionID string

ActionID is the stable dynamic identifier for one GitLab action.

type Catalog 

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog stores deterministic groups and action lookup indexes. A Catalog is intended to be mutated during single-threaded initialization and then shared read-only; concurrent mutation is not supported.

func FromActionMaps 

func FromActionMaps(routes map[string]toolutil.ActionMap) *Catalog

FromActionMaps converts legacy route maps into a canonical catalog.

func FromActionMapsWithError 

func FromActionMapsWithError(routes map[string]toolutil.ActionMap) (*Catalog, error)

FromActionMapsWithError converts legacy route maps into a canonical catalog and reports invalid groups instead of panicking.

func NewCatalog 

func NewCatalog() *Catalog

NewCatalog creates an empty action catalog.

func (*Catalog) Action 

func (c *Catalog) Action(id ActionID) (Action, bool)

Action returns a defensive copy of one action by canonical ID.

func (*Catalog) ActionMaps 

func (c *Catalog) ActionMaps() map[string]toolutil.ActionMap

ActionMaps returns a defensive legacy route snapshot keyed by tool and action.

func (*Catalog) Actions 

func (c *Catalog) Actions() []Action

Actions returns all actions sorted by canonical ID.

func (*Catalog) AddAction 

func (c *Catalog) AddAction(toolName string, action Action, groupOptions ...GroupOptions) error

AddAction adds one action to an existing or newly-created group. When the group does not exist, callers may provide GroupOptions so the synthesized group carries the same metadata as a normal catalog group.

func (*Catalog) AddGroup 

func (c *Catalog) AddGroup(group Group) error

AddGroup adds a complete group to the catalog.

func (*Catalog) Clone 

func (c *Catalog) Clone() *Catalog

Clone returns a defensive deep copy of the catalog.

func (*Catalog) CountActions 

func (c *Catalog) CountActions() int

CountActions returns the number of actions in the catalog.

func (*Catalog) CountGroups 

func (c *Catalog) CountGroups() int

CountGroups returns the number of groups in the catalog.

func (*Catalog) Filter 

func (c *Catalog) Filter(opts FilterOptions) *Catalog

Filter applies all catalog-level filters in a deterministic order.

func (*Catalog) FilterAllowedToolNames 

func (c *Catalog) FilterAllowedToolNames(toolNames []string) *Catalog

FilterAllowedToolNames returns a cloned catalog with only explicitly allowed tools.

func (*Catalog) FilterExcludedTools 

func (c *Catalog) FilterExcludedTools(excludeTools []string) *Catalog

FilterExcludedTools returns a cloned catalog without excluded tool groups.

func (*Catalog) FilterReadOnlyGroups 

func (c *Catalog) FilterReadOnlyGroups() *Catalog

FilterReadOnlyGroups returns a cloned catalog containing only read-only groups.

func (*Catalog) Group 

func (c *Catalog) Group(toolName string) (Group, bool)

Group returns a defensive copy of one group by tool name.

func (*Catalog) Groups 

func (c *Catalog) Groups() []Group

Groups returns all groups sorted by tool name.

func (*Catalog) Validate 

func (c *Catalog) Validate() error

Validate verifies that the catalog has a consistent, executable action index.

type CatalogGroupSpec 

type CatalogGroupSpec struct {
	ToolName               string
	Title                  string
	Description            string
	ReadOnly               bool
	Icons                  []mcp.Icon
	BaseDomain             string
	EnterpriseOnly         bool
	GitLabDotComOnly       bool
	CapabilityRequirements []string
	FormatResult           toolutil.FormatResultFunc
	Actions                []toolutil.ActionSpec
	OwnerPackage           string
	SurfaceKind            SurfaceKind
}

CatalogGroupSpec is the canonical metadata contract for one catalog group.

func CloneCatalogGroupSpec 

func CloneCatalogGroupSpec(spec CatalogGroupSpec) CatalogGroupSpec

CloneCatalogGroupSpec returns a defensive copy of group metadata.

func (CatalogGroupSpec) GroupOptions 

func (spec CatalogGroupSpec) GroupOptions() GroupOptions

GroupOptions returns catalog group options projected from the group spec.

func (CatalogGroupSpec) Validate 

func (spec CatalogGroupSpec) Validate() error

Validate verifies group-level catalog invariants before runtime projection.

type FilterOptions 

type FilterOptions struct {
	ExcludeTools     []string
	ReadOnlyOnly     bool
	AllowedToolNames []string
}

FilterOptions describes catalog-level filtering inputs.

type Group 

type Group struct {
	ToolName               string
	Title                  string
	Description            string
	Icons                  []mcp.Icon
	ReadOnly               bool
	FormatResult           toolutil.FormatResultFunc
	BaseDomain             string
	EnterpriseOnly         bool
	GitLabDotComOnly       bool
	CapabilityRequirements []string
	OwnerPackage           string
	SurfaceKind            SurfaceKind
	Actions                map[string]Action
	ActionOrder            []string
}

Group describes all actions exposed through one logical meta-tool group.

func GroupFromSpecs 

func GroupFromSpecs(opts GroupOptions, specs []toolutil.ActionSpec) (Group, error)

GroupFromSpecs builds a catalog group from canonical action specs.

func NewGroup 

func NewGroup(opts GroupOptions) Group

NewGroup creates an action group with initialized maps.

func (*Group) ActionMap 

func (g *Group) ActionMap() toolutil.ActionMap

ActionMap returns a legacy route map for this group.

func (*Group) ActionsInOrder 

func (g *Group) ActionsInOrder() []Action

ActionsInOrder returns group actions in deterministic action-name order.

func (*Group) SetAction 

func (g *Group) SetAction(action Action)

SetAction inserts or replaces an action in the group.

type GroupOptions 

type GroupOptions struct {
	ToolName               string
	Title                  string
	Description            string
	Icons                  []mcp.Icon
	ReadOnly               bool
	FormatResult           toolutil.FormatResultFunc
	BaseDomain             string
	EnterpriseOnly         bool
	GitLabDotComOnly       bool
	CapabilityRequirements []string
	OwnerPackage           string
	SurfaceKind            SurfaceKind
}

GroupOptions contains metadata for creating a catalog group.

type SurfaceKind 

type SurfaceKind string

SurfaceKind classifies the runtime surface represented by a catalog group. 

const (
	// SurfaceKindGitLabAction identifies ordinary GitLab API actions.
	SurfaceKindGitLabAction SurfaceKind = "gitlab-action"
	// SurfaceKindMetaGroup identifies visible domain meta-tool dispatchers.
	SurfaceKindMetaGroup SurfaceKind = "meta-group"
	// SurfaceKindDynamicController identifies Dynamic controller tools.
	SurfaceKindDynamicController SurfaceKind = "dynamic-controller"
	// SurfaceKindRuntimeUtility identifies non-GitLab runtime helper tools.
	SurfaceKindRuntimeUtility SurfaceKind = "runtime-utility"
	// SurfaceKindInteractiveUtility identifies tools that require MCP elicitation.
	SurfaceKindInteractiveUtility SurfaceKind = "interactive-utility"
	// SurfaceKindSamplingUtility identifies tools that require MCP sampling.
	SurfaceKindSamplingUtility SurfaceKind = "sampling-utility"
	// SurfaceKindServerMaintenance identifies server maintenance tools.
	SurfaceKindServerMaintenance SurfaceKind = "server-maintenance"
)

type SurfaceToolSpec 

type SurfaceToolSpec struct {
	Name                   string
	Title                  string
	Description            string
	GroupToolName          string
	BaseDomain             string
	ActionName             string
	SurfaceKind            SurfaceKind
	Route                  toolutil.ActionRoute
	Aliases                []string
	Tags                   []string
	RelatedActions         []string
	Compatibility          toolutil.CompatibilityPolicy
	Icons                  []mcp.Icon
	CapabilityRequirements []string
	FormatResult           toolutil.FormatResultFunc
	SafeModePolicy         string
	ReadOnlyPolicy         string
	OwnerPackage           string
	ReadOnly               bool
	Destructive            bool
	Idempotent             bool
	OpenWorld              bool
}

SurfaceToolSpec is the canonical metadata contract for visible MCP tools that are not ordinary GitLab API meta-tool groups.

func CloneSurfaceToolSpec 

func CloneSurfaceToolSpec(spec SurfaceToolSpec) SurfaceToolSpec

CloneSurfaceToolSpec returns a defensive copy of surface tool metadata.

func (SurfaceToolSpec) ActionSpec 

func (spec SurfaceToolSpec) ActionSpec() (toolutil.ActionSpec, error)

ActionSpec projects a surface tool spec into the shared ActionSpec model.

func (SurfaceToolSpec) Validate 

func (spec SurfaceToolSpec) Validate() error

Validate verifies that the surface spec has enough metadata for runtime registration and catalog projection.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.