Documentation
¶
Overview ¶
Package config loads, normalizes, and validates runtime configuration for the GitLab MCP server.
Configuration comes from environment variables, .env files, and CLI flags in cmd/server. The package centralizes defaults and bounds for stdio mode, HTTP mode, OAuth token verification, auto-update behavior, upload limits, safe mode, read-only mode, rate limiting, tool surfaces, capability surfaces, and meta-tool schema detail.
Validation Model ¶
Loaders keep user-facing configuration forgiving while preserving hard bounds that protect runtime behavior: URL values are parsed and normalized, duration and size fields are clamped to documented limits, and invalid enum values are reported before server registration begins.
Index ¶
- Constants
- func EffectiveCapabilitySurface(capabilitySurface string) string
- func EffectiveToolSurface(metaTools bool, toolSurface string) string
- func LegacyMetaToolsReplacement(metaToolsValue string) string
- func LegacyMetaToolsSelectorInUse(toolSurfaceValue, metaToolsValue string) bool
- func ParseCSV(s string) []string
- func ParseToolSurface(toolSurfaceValue, metaToolsValue string) (mode string, metaTools bool, err error)
- type Config
- type ServerConfig
Constants ¶
const ( DefaultMaxFileSize = 2 * 1024 * 1024 * 1024 // 2 GB MaxFileSize = 1024 * 1024 * 1024 * 1024 // 1 TB upper bound )
DefaultMaxFileSize and MaxFileSize define the default and upper bound for GitLab upload payload sizes.
const ( DefaultMaxHTTPClients = 100 DefaultSessionTimeout = 30 * time.Minute DefaultRevalidateInterval = 15 * time.Minute MaxHTTPClients = 10000 MaxSessionTimeout = 24 * time.Hour MaxRevalidateInterval = 24 * time.Hour )
HTTP pool defaults.
const ( DefaultOAuthCacheTTL = 15 * time.Minute MinOAuthCacheTTL = 1 * time.Minute MaxOAuthCacheTTL = 2 * time.Hour )
OAuth defaults.
const ( DefaultAutoUpdateRepo = "jmrplens/gitlab-mcp-server" DefaultAutoUpdateInterval = 1 * time.Hour DefaultAutoUpdateTimeout = 60 * time.Second MinAutoUpdateTimeout = 5 * time.Second MaxAutoUpdateTimeout = 10 * time.Minute )
Auto-update defaults.
const ( // MetaParamSchemaOpaque keeps the legacy `params: object` envelope. // This is the default and produces the smallest tools/list payload. MetaParamSchemaOpaque = "opaque" // MetaParamSchemaCompact emits a discriminated `oneOf` per action with // descriptions and $defs stripped to reduce size. MetaParamSchemaCompact = "compact" // MetaParamSchemaFull emits a discriminated `oneOf` per action with the // complete reflected JSON Schema for each action's params. MetaParamSchemaFull = "full" // DefaultMetaParamSchema is the default mode applied when neither the // META_PARAM_SCHEMA env var nor the --meta-param-schema flag is set. DefaultMetaParamSchema = MetaParamSchemaOpaque )
Meta-tool param schema modes.
const ( // ToolSurfaceMeta exposes the current domain meta-tool catalog. ToolSurfaceMeta = "meta" // ToolSurfaceIndividual exposes the full individual tool catalog. ToolSurfaceIndividual = "individual" // ToolSurfaceDynamic exposes the default low-token find/execute catalog. ToolSurfaceDynamic = "dynamic" // DefaultToolSurface selects the low-token find/execute catalog by default. DefaultToolSurface = ToolSurfaceDynamic )
Tool surface modes select which tool catalog is exposed by the server.
const ( // CapabilitySurfaceFull exposes the current resource and prompt catalog. CapabilitySurfaceFull = "full" // CapabilitySurfaceMinimal exposes only capabilities required for dynamic use. CapabilitySurfaceMinimal = "minimal" // DefaultCapabilitySurface preserves the existing resource and prompt catalog. DefaultCapabilitySurface = CapabilitySurfaceFull )
Capability surface modes select which non-tool MCP capabilities are exposed.
const DefaultGitLabURL = "https://gitlab.com"
DefaultGitLabURL is the GitLab instance used when GITLAB_URL is unset.
const (
DefaultRateLimitBurst = 40
)
DefaultRateLimitBurst is the bucket size used when rps > 0 and the operator did not set RATE_LIMIT_BURST explicitly.
const EnvFileName = ".gitlab-mcp-server.env"
EnvFileName is the name of the env file where the setup wizard stores secrets.
Variables ¶
This section is empty.
Functions ¶
func EffectiveCapabilitySurface ¶
EffectiveCapabilitySurface returns the canonical capability surface.
func EffectiveToolSurface ¶
EffectiveToolSurface returns the canonical tool surface for legacy and new configuration snapshots. Empty ToolSurface values are derived from MetaTools so older tests and callers keep their current behavior.
func LegacyMetaToolsReplacement ¶
LegacyMetaToolsReplacement returns the canonical TOOL_SURFACE value that corresponds to a legacy META_TOOLS value. It returns an empty string when the legacy value is invalid.
func LegacyMetaToolsSelectorInUse ¶
LegacyMetaToolsSelectorInUse reports whether a configuration relies on the deprecated META_TOOLS selector instead of the canonical TOOL_SURFACE selector.
Types ¶
type Config ¶
type Config struct {
GitLabURL string
GitLabToken string
SkipTLSVerify bool
DisableRetries bool // Disable GitLab client retries for unit tests.
MetaTools bool
ToolSurface string
CapabilitySurface string
Enterprise bool
AutoDetectEnterprise bool
ReadOnly bool
SafeMode bool
EmbeddedResources bool // Append EmbeddedResource content blocks to get_* tool results (default true)
UploadMaxFileSize int64
MaxHTTPClients int // Maximum unique tokens in the server pool (HTTP mode only)
SessionTimeout time.Duration // Idle MCP session timeout (HTTP mode only)
RevalidateInterval time.Duration // Token re-validation interval (HTTP mode only)
AutoUpdate string // Auto-update mode: "true" (auto), "check" (log-only), "false" (disabled)
AutoUpdateRepo string // GitLab project path for update checks
AutoUpdateInterval time.Duration // How often to check for updates (HTTP mode)
AutoUpdateTimeout time.Duration // Timeout for pre-start update check (stdio mode)
AuthMode string // Auth mode for HTTP: "legacy" (default) or "oauth"
OAuthCacheTTL time.Duration // OAuth token cache TTL (HTTP mode, oauth auth mode)
TrustedProxyHeader string // HTTP header with real client IP (e.g. X-Forwarded-For, X-Real-IP)
ExcludeTools []string // Tool names to exclude from registration (comma-separated via EXCLUDE_TOOLS)
IgnoreScopes bool // When true, skip PAT scope detection and register all tools
RateLimitRPS float64 // Per-server tools/call rate limit in requests/second (0 = disabled)
RateLimitBurst int // Token-bucket burst size when RateLimitRPS > 0
// MetaParamSchema controls how meta-tool input schemas advertise the
// shape of the `params` object. Allowed values: "opaque" (default),
// "compact", "full". See [DefaultMetaParamSchema] and constants.
MetaParamSchema string
}
Config holds all configuration values for the MCP server.
func Load ¶
Load reads configuration from environment variables. It attempts to load a .env file from the current directory first, then falls back to ~/.gitlab-mcp-server.env (written by the setup wizard) for secrets not provided via the environment or CWD .env.
func (*Config) ServerConfig ¶
func (c *Config) ServerConfig() *ServerConfig
ServerConfig returns the server-scoped subset of Config. Callers may enrich the returned snapshot with detected per-principal data before creating a concrete MCP server instance.
type ServerConfig ¶
type ServerConfig struct {
GitLabURL string
MetaTools bool
ToolSurface string
CapabilitySurface string
Enterprise bool
ReadOnly bool
SafeMode bool
ExcludeTools []string
TokenScopes []string
RateLimitRPS float64
RateLimitBurst int
MetaParamSchema string
}
ServerConfig is an immutable configuration snapshot used to build one MCP server instance for a specific GitLab URL and credential principal.
Source Files