config

type Config struct {
	// Clockify
	APIKey         string
	WorkspaceID    string
	BaseURL        string
	RequestTimeout time.Duration
	MaxRetries     int
	Insecure       bool
	Timezone       string

	// MCP transport
	Transport          string
	AuthMode           string
	HTTPBind           string
	GRPCBind           string
	BearerToken        string
	AllowedOrigins     []string
	AllowAnyOrigin     bool
	StrictHostCheck    bool
	MaxMessageSize     int64
	MetricsBind        string
	MetricsAuthMode    string
	MetricsBearerToken string

	// Enterprise shared-service
	ControlPlaneDSN string
	// ControlPlaneAuditCap is the max number of audit events retained
	// in the file-backed control-plane store. 0 keeps the historical
	// unbounded behaviour; non-zero enables FIFO eviction. Wired from
	// MCP_CONTROL_PLANE_AUDIT_CAP. Postgres deployments ignore this
	// field in favour of time-based retention (B2).
	ControlPlaneAuditCap int
	// ControlPlaneAuditRetention caps the age of retained audit
	// events. The B2 reaper calls Store.RetainAudit(ctx, retention)
	// on a one-hour ticker; events with `at < now - retention` are
	// removed from the backend. Zero disables retention. Wired from
	// MCP_CONTROL_PLANE_AUDIT_RETENTION; default 720h (30 days).
	ControlPlaneAuditRetention time.Duration
	SessionTTL                 time.Duration
	TenantClaim                string
	SubjectClaim               string
	DefaultTenantID            string
	OIDCIssuer                 string
	OIDCAudience               string
	OIDCJWKSURL                string
	OIDCJWKSPath               string
	// OIDCResourceURI is the canonical URI clients use to address this
	// MCP server. When set, every OIDC token must list this URI in its
	// audience claim — RFC 8707 / MCP OAuth 2.1 resource indicator
	// binding. Wired from MCP_RESOURCE_URI.
	OIDCResourceURI string
	// OIDCVerifyCacheTTL is the hard ceiling on cached OIDC verify
	// results. Larger values amortise the per-request verify cost but
	// extend the window before a revoked token is re-checked. Zero
	// selects the conservative 60s default baked into authn; values
	// outside [1s, 5m] are clamped at the authn layer. Wired from
	// MCP_OIDC_VERIFY_CACHE_TTL.
	OIDCVerifyCacheTTL   time.Duration
	ForwardTenantHeader  string
	ForwardSubjectHeader string
	MTLSTenantHeader     string

	// Tool execution
	ToolTimeout               time.Duration
	ConcurrencyAcquireTimeout time.Duration

	// Dispatch-layer concurrency bound for stdio tools/call. 0 disables.
	MaxInFlightToolCalls int

	// Hard cap on entries aggregated by report tools. 0 disables.
	ReportMaxEntries int

	// DeltaFormat selects the resource notification diff algorithm.
	// "merge" (default) = RFC 7396 merge patch. "jsonpatch" = RFC 6902.
	DeltaFormat string

	// GRPCReauthInterval is how often long-lived gRPC streams re-validate
	// their auth token. 0 = disabled (per-stream validation only).
	GRPCReauthInterval time.Duration

	// AuditDurabilityMode controls behavior when audit persistence fails for
	// a successful non-read-only tool call.
	// "best_effort" (default): log + metric; the call still reports success.
	// "fail_closed": the call returns an error so the client knows the audit
	// trail is incomplete. The mutation already happened; this prevents
	// silent untracked mutations.
	AuditDurabilityMode string

	// HTTPInlineMetricsEnabled controls whether /metrics is mounted on the
	// main HTTP listener when MCP_TRANSPORT=http. Default: false (disabled).
	// The dedicated metrics listener (MCP_METRICS_BIND) is the preferred
	// pattern; this is a compatibility escape hatch that requires explicit
	// operator intent.
	HTTPInlineMetricsEnabled bool
	// HTTPInlineMetricsAuthMode governs auth for inline main-listener /metrics.
	// "inherit_main_bearer" (default when enabled): require the same bearer
	// token as the /mcp endpoint.
	// "static_bearer": require a separate MCP_HTTP_INLINE_METRICS_BEARER_TOKEN.
	// "none": unauthenticated — operator must opt in explicitly; startup warns.
	HTTPInlineMetricsAuthMode string
	// HTTPInlineMetricsBearerToken is the separate token for inline metrics
	// when HTTPInlineMetricsAuthMode == "static_bearer".
	HTTPInlineMetricsBearerToken string

	// HTTPLegacyPolicy governs startup behavior when MCP_TRANSPORT=http.
	// "warn" (default): emit structured startup warnings about legacy HTTP
	// limitations and recommend streamable_http.
	// "deny": refuse to start; operator must switch to streamable_http or
	// explicitly set MCP_HTTP_LEGACY_POLICY=allow.
	// "allow": permit startup without deny or warn behavior.
	HTTPLegacyPolicy string

	// GRPCTLSCert and GRPCTLSKey are paths to the server TLS cert and
	// private key for the gRPC transport. Both must be set together.
	GRPCTLSCert string
	GRPCTLSKey  string
	// MTLSCACertPath is the path to the CA cert for client certificate
	// verification. Required when MCP_AUTH_MODE=mtls on gRPC.
	MTLSCACertPath string
}

type EnvSpec struct {
	Name         string
	Group        string
	Default      string
	Help         string
	Enum         []string
	AppliesTo    []string
	Deprecated   bool
	Replacement  string
	EssentialDoc bool
}