toolutil

func AccessLevelDescription ¶

func AccessLevelDescription(level gl.AccessLevelValue) string

AccessLevelDescription maps a GitLab access level to its human-readable label. A level the table does not name is rendered with its number, "Level 35", because the number is what GitLab sent and the one thing a reader can act on; "Unknown" told them nothing, which is why two packages kept a copy of this table with the numeric fallback of their own.

func ActionDispatchOutputSchema ¶

func ActionDispatchOutputSchema() map[string]any

ActionDispatchOutputSchema returns a permissive JSON Schema for tools whose exact structured result depends on the selected catalog action.

The pagination properties are the JSON names of PaginationOutput, the block a list read over REST carries, and a test reads them off the struct. They are not marked required, and the object stays open, because a list read over GraphQL carries its cursor block (GraphQLPaginationOutput) under the same key, and the SDK validates every result against this schema.

func ActionTimeout ¶

func ActionTimeout() time.Duration

ActionTimeout reports the deadline every action runs under, 0 for none.

func AddMetaTool ¶

func AddMetaTool(server *mcp.Server, name, desc string, routes ActionMap, icons []mcp.Icon, formatResult FormatResultFunc)

AddMetaTool registers an action-dispatched meta-tool with route-derived annotations. Use it for meta-tools that may include mutating or destructive actions; if any route is destructive, the tool receives DestructiveHint=true.

func AddReadOnlyMetaTool ¶

func AddReadOnlyMetaTool(server *mcp.Server, name, desc string, routes ActionMap, icons []mcp.Icon, formatResult FormatResultFunc)

AddReadOnlyMetaTool registers an action-dispatched meta-tool whose actions are all read-only list/get/search-style operations.

func AdjustPagination ¶

func AdjustPagination(p *PaginationOutput, itemCount int)

AdjustPagination completes the pagination of a list GitLab answers without the X-Total and X-Total-Pages headers, which is what its search API does. It numbers an unnumbered page 1 and derives HasMore from the next page, and it fills the two totals only on a lone page (no next page, no previous one, page 1 at most), the one page whose rows are the whole result. Anywhere else it leaves them at 0, the value PaginationOutput documents for a total GitLab did not send: search redacts the rows a caller may not read after it pages, so neither this page's row count nor the next page number counts the result, and an earlier page need not have been full. The Markdown then says "shown, more available" instead of a count nothing measured.

A keyset page is left as PaginationFromResponse described it: it has no page number or total to infer from, and its successor is its next_page_token rather than a page.

func AnnotationsForContentKind ¶ added in v3.1.0

func AnnotationsForContentKind(kind string) *mcp.Annotations

AnnotationsForContentKind maps an action's declared content kind (ActionSpecContentList, ActionSpecContentDetail, ActionSpecContentMutate, ActionSpecContentAssistant, ActionSpecContentImage) to the content annotation its text block carries, in one place, so the kind a spec declares and the annotation the dispatcher serves cannot disagree. An image action's text block is for the assistant like any other; the image block itself carries ContentUser. An empty or unknown kind is the assistant default.

func AppendHints ¶ added in v3.2.0

func AppendHints(md string, hints ...string) string

AppendHints returns md with hints added to the server's guidance section: as further bullets of the section it already carries, wherever WriteHints put it, or as a section of their own when it carries none. Blank hints are dropped, and with none left md is returned as it came.

A section is extended rather than a second one written, because ExtractHints reads one section and only one: a leading section is read in preference to anything after the body, and a closing one must end the response, so a second section would either be ignored or hide the first.

func ApplyActionMeta ¶

func ApplyActionMeta(options *ActionSpecOptions, meta ActionMetaEntry)

ApplyActionMeta overlays the non-zero fields of meta onto options. Aliases and RelatedActions are copied defensively so callers may share a metadata table across actions without aliasing the underlying slices. It is a no-op for a zero-value entry, so a missing metadata row leaves the option defaults untouched.

func ApplyListOptions ¶

func ApplyListOptions(opts *gl.ListOptions, page PaginationInput, keyset KeysetPaginationInput)

ApplyListOptions copies offset (PaginationInput) and keyset (KeysetPaginationInput) parameters onto a gl.ListOptions, setting only the values the caller supplied. Pass a zero KeysetPaginationInput for endpoints that only support offset pagination.

A page_token that is a next_page_token a previous response published is not copied: it is a link carrying the listing's parameters, which KeysetContinuation makes the query of the request, and sent whole as page_token it would reach GitLab as a parameter of its own, which GitLab copies into the next link it writes. Only a raw GitLab page token goes on PageToken.

func ApplyWorkItemWidgets ¶ added in v3.3.0

func ApplyWorkItemWidgets(opts *gl.UpdateWorkItemOptions, in WorkItemWidgetInputs) (gl.RequestOptionFunc, error)

ApplyWorkItemWidgets copies the inputs that set a value onto opts, refusing a negative reference and a date that does not parse, and returns the request option that sends each removal the inputs ask for, or nil when they ask for none.

The option exists because client-go's UpdateWorkItemOptions cannot express a removal (register row 119): it wraps any reference, 0 included, into a global ID, so 0 reached GitLab as gid://gitlab/Milestone/0 and was refused as "No object found", and its widget fields are omitted when unset, so an empty date or health status sent nothing and the update answered success with the value still in place. GitLab removes each of these when the widget's field is null, which the option writes into the input client-go built, beside whatever else the update sets.

func AssigneeFilter ¶ added in v3.3.0

func AssigneeFilter(field string, value StringOrInt) (*gl.AssigneeIDValue, error)

AssigneeFilter converts an assignee_id filter into the value client-go's list options send, on the terms of [parseUserIDFilter]. It returns nil for a filter left out, so callers can assign the result unconditionally.

func AttachArgumentLimits ¶

func AttachArgumentLimits(server *mcp.Server, maxDepth int)

AttachArgumentLimits registers a receiving middleware that refuses a tools/call whose arguments nest deeper than maxDepth, before the SDK decodes them.

Why this is not the HTTP body cap ¶

The SDK hands tools/call arguments to middleware as raw bytes and unmarshals them into a map[string]any only when it applies the tool's schema. That decoder (github.com/segmentio/encoding/json, through the SDK's internal json package) has no maximum-nesting guard, where the standard library refuses past 10000, and it is quadratic in nesting depth: measured on v0.5.4, an 18 KB value nested 9000 deep costs over a second of CPU, and a 4 MiB body admits depth in the millions. The decode runs ahead of additionalProperties validation and ahead of the handler, so read-only mode, safe mode and the tool's own logic are all downstream of the burn, and the per-second rate limiter counts requests rather than cycles.

A body-size cap alone only narrows the window: 256 KiB still admits depth 128000. The bound that closes it is on the shape, and it belongs in a receiving middleware rather than in the HTTP front door so that stdio — the transport with no body cap at all — is covered by the same check.

The scan is a single linear pass over bytes the SDK has already framed, so the guard costs about a microsecond on an ordinary call. A non-positive maxDepth disables it; a nil server is a no-op.

func AttachRateLimit ¶

func AttachRateLimit(server *mcp.Server, limiter *RateLimiter)

AttachRateLimit registers a receiving middleware that gates every method that reaches GitLab with the caller's credential, plus `completion/complete` and `tools/list`, when their buckets are empty.

`tools/call`, `resources/read`, `resources/subscribe`, `subscriptions/listen` and `prompts/get` draw on one bucket: each is a request to GitLab on the caller's behalf, and a limit that metered tool calls alone left the other doors open to the same upstream. They are refused differently because they fail differently. A refused tool call is reported as an MCP tool error result (IsError: true) rather than a JSON-RPC error, so the model receives a structured, retryable diagnostic and the agent loop can back off, carrying the resultType its revision requires (LabelForRevision). A refused resource or prompt request is a JSON-RPC error carrying the code that mirrors HTTP 429, since those results have no error flag of their own. A refused completion returns an empty completion instead: the documented contract for this surface is that autocomplete is never blocked, and an error in a completion popup is worse than no suggestions.

`tools/list` draws on a third bucket, refilled a tenth as fast as the tool-call one and holding the same burst (see [catalogDivisor]), and it is metered for a reason none of the others share: it reaches no upstream, it spends the processor of a process many tenants share. On the individual surface one listing marshals about 3.2 MB and is the majority of that surface's processor time, so a client listing in a loop takes the processor its co-tenants are waiting for while the shared bucket, which counts requests to GitLab, sees nothing at all. Keeping the two apart is also what preserves the property the old exemption provided: draining the tool-call bucket never refuses a client's discovery. It is refused like the flagless methods above, with the code that mirrors HTTP 429, because ListToolsResult carries no error flag either. One token is one JSON-RPC request, so a catalog split over several pages costs one per page; the server keeps its whole catalog in one page, for a different reason recorded where PageSize is set. A listing is charged first to a fourth bucket, the one the whole process shares and counts in tools listed ([processCatalog]), because the entry's multiplies by however many credentials a caller holds; that one refuses with the same code and the same words, and only the log line it writes says which refused.

Every other method (initialize, resources/list, prompts/list) bypasses the limiter: they reach no upstream and cost little to answer, and metering something cheap buys nothing and costs a concept. Which bucket each method draws on, and so which draws on none, is tenancy.MeterFor's answer (register rows RTC-001 to RTC-004); the buckets and the refusals stay here. If limiter is nil, this function is a no-op.

func AttachRateLimitFunc ¶

func AttachRateLimitFunc(server *mcp.Server, resolve func(context.Context) *RateLimiter)

AttachRateLimitFunc is AttachRateLimit for a server whose bucket depends on the request.

It exists because one server now answers for every credential of a configuration shape, while the limit is per credential: a bucket captured at registration would be one budget shared by every tenant, so the noisiest of them would refuse everybody else's calls. The resolver reads the bucket the request's own pool entry owns, and returning nil means this request is not limited, which is what an unbound request on a shape server and the stdio default both want. A listing is also charged to the bucket the whole process shares ([processCatalog]), wherever the entry's own listing bucket charges it.

func BoolEmoji ¶

func BoolEmoji(v bool) string

BoolEmoji returns ✅ for true and ❌ for false.

func BoolPtr ¶

func BoolPtr(b bool) *bool

BoolPtr returns a pointer to the given bool value.

func BuildMetaToolSchema ¶

func BuildMetaToolSchema(routes ActionMap, mode string) map[string]any

BuildMetaToolSchema returns the input schema for a meta-tool given the chosen mode. Unknown modes silently fall back to MetaParamSchemaOpaque so that callers cannot break the tools/list payload by passing a typo.

• opaque: legacy {action, params:any} envelope (default).
• full: one if/then per action under allOf, with the full params schema MetaActionSchema serves.
• compact: the same conditionals, with descriptions and $defs stripped.

func BuildPipelineInputs ¶

func BuildPipelineInputs(raw map[string]any) (gl.PipelineInputsOption, error)

BuildPipelineInputs converts a JSON-decoded inputs map into the SDK's type-safe gl.PipelineInputsOption. JSON numbers decode to float64 and JSON arrays to []any; both are normalized to the SDK's supported value types (string, float64, bool, []string). An unsupported value type returns an error.

Shared by pipeline creation and manual-job play, which take the same spec:inputs value shapes.

func BuildTargetURL ¶

func BuildTargetURL(projectWebURL, targetType string, targetIID int64) string

BuildTargetURL constructs a GitLab web URL for a target resource. Returns "" when the project web URL is empty, the IID is zero, or the target type has no known URL segment.

Supported target types: Issue, MergeRequest, Milestone.

func CancelledResult ¶

func CancelledResult(message string) *mcp.CallToolResult

CancelledResult returns an error tool result indicating the user canceled.

The operation was declined, so it produced none of the output its schema describes. A tool that declares an outputSchema MUST return structured results conforming to it, and a cancellation conforms to nothing, so this is reported as an error result rather than as a success carrying only prose, in the envelope every refusal travels in.

func CanonicalImportArchivePath ¶

func CanonicalImportArchivePath(path string) (string, error)

CanonicalImportArchivePath validates a local GitLab export archive path and returns the canonical path resolved through symlinks. Archives must be regular .tar.gz files under the current working directory, the OS temporary directory, or a directory listed in GITLAB_MCP_ALLOWED_IMPORT_DIRS.

func CanonicalLocalDirPath ¶

func CanonicalLocalDirPath(path string) (string, error)

CanonicalLocalDirPath resolves a caller-supplied path to an existing local directory and returns it canonicalized, subject to the same roots and the same HTTP refusal as CanonicalLocalFilePath.

func CanonicalLocalFilePath ¶

func CanonicalLocalFilePath(path string) (string, error)

CanonicalLocalFilePath resolves a caller-supplied path to an existing local file and returns it canonicalized, provided the resolved path lies under the working directory, the OS temporary directory, or a directory listed in GITLAB_MCP_ALLOWED_UPLOAD_DIRS. It refuses every path when the server is reached over HTTP.

func CapturedThread ¶

func CapturedThread[T any](op string, d *gl.Discussion, capture *gitlabclient.ResponseCapture) (T, error)

CapturedThread converts one discussion with what its captured answer carries beside the SDK's decode, or reports under op the answer the type cannot hold. It is the whole tail of a handler that returns one thread, and answers in T, the thread type the handler's own package declares over DiscussionThreadOutput so the Markdown registry finds that package's formatter (see convertShape for what T must be).

func CapturedThreadNote ¶

func CapturedThreadNote[T any](op string, n *gl.Note, capture *gitlabclient.ResponseCapture) (T, error)

CapturedThreadNote converts one note of a thread the same way, answering in T, the note type the handler's package declares over DiscussionThreadNoteOutput.

func CapturedThreads ¶

func CapturedThreads[T any](op string, ds []*gl.Discussion, capture *gitlabclient.ResponseCapture) ([]T, error)

CapturedThreads does the same for a list of discussions, pairing each with its own extra by position.

func CatalogListingRPS ¶

func CatalogListingRPS(rps float64) float64

CatalogListingRPS is the refill rate a listing draws on when the tool-call bucket is configured at rps.

Exported so the entrypoint can announce both figures at startup: the listing rate is the other number an operator can meet in a refusal, and the divisor that produces it belongs here rather than copied into a log statement. The burst is the configured one, unchanged; [catalogDivisor] records why.

func CellOr ¶ added in v3.3.0

func CellOr(value, absent string) string

CellOr renders a table cell the way Card.FieldOr renders a row: value through EscapeMdTableCell, or absent in its place when value is empty, for a column whose absence is the answer, such as the dash where a board column has no limit metric. absent is the server's own text and is written as given. It serves a CardTable row and a MarkdownTableRow alike.

func ClampPollInterval ¶

func ClampPollInterval(v int) int

ClampPollInterval constrains a polling interval to [PollMinInterval, PollMaxInterval], returning PollDefaultInterval when the value is below the minimum.

func ClampPollTimeout ¶

func ClampPollTimeout(v int) int

ClampPollTimeout constrains a polling timeout to [PollMinTimeout, PollMaxTimeout], returning PollDefaultTimeout when the value is below the minimum.

func ClassifyError ¶

func ClassifyError(err error) string

ClassifyError inspects the error chain and returns a short, human-friendly diagnostic message explaining what went wrong at a high level.

func ClassifyHTTPStatus ¶

func ClassifyHTTPStatus(code int) string

ClassifyHTTPStatus returns a semantic description for common HTTP status codes. It describes the status alone, so a 401 gets the sentence true of both of its causes; ClassifyError, which holds the whole response, can say which one.

func ClearableDate ¶ added in v3.3.0

func ClearableDate(field string, value *string) (*gl.ISOTime, error)

ClearableDate reads one optional date input of an update, where a field left out and a field set to an empty string mean different things: nil leaves the stored date alone, and an empty string removes it. An empty string returns a zero gl.ISOTime, which client-go encodes as JSON null, the value GitLab clears a date with. Anything else is read on the terms of ParseDateField.

func ClearableDateInputs ¶ added in v3.3.0

func ClearableDateInputs(inputs ...ClearableDateInput) error

ClearableDateInputs reads each update date into its destination on the terms of ClearableDate, refusing the call on the first value that does not parse, before any later one is read.

func CloneMetaSchemaRoutes ¶

func CloneMetaSchemaRoutes(routes map[string]ActionMap) map[string]ActionMap

CloneMetaSchemaRoutes returns a snapshot of the route maps: the two map levels are new, so later insertions and deletions in routes do not reach the snapshot, and every route in it is a CloneActionRoute copy.

The schemas are not copied. A route's InputSchema, OutputSchema and ParameterGuidance are frozen and shared by every consumer in the process, which is what lets a catalog cached per configuration serve every server without a copy per server; the copies this function used to make were half of the heap at a hundred pooled credentials. A consumer that must change a schema derives its own through DeriveSchema.

func CloneSchemaMap ¶

func CloneSchemaMap(schema map[string]any) map[string]any

CloneSchemaMap returns a deep copy of a JSON Schema map, for a caller that has a reason to mutate one: every schema reachable from a shared catalog is shared with every server in the process and must be copied before it is changed.

func CompileToolSchemas ¶

func CompileToolSchemas(tool *mcp.Tool, cacheKey string)

CompileToolSchemas replaces a projected tool's map-based input and output schemas with process-cached *jsonschema.Schema equivalents. Passing the SDK a stable schema pointer instead of a map removes the per-registration JSON remarshal inside mcp.AddTool and lets a shared mcp.SchemaCache (keyed by pointer identity) skip schema resolution on subsequent registrations — the dominant cost when the HTTP server pool builds a new MCP server per token.

The conversion is a faithful roundtrip: the maps are produced by marshaling jsonschema output, and jsonschema.Schema preserves non-standard keys such as x_destructive. On any marshal error the original map is kept, preserving current behavior. An empty cacheKey disables compilation, so callers that cannot guarantee a content-stable key keep the map path.

func ComputeSHA256 ¶

func ComputeSHA256(path string) (string, error)

ComputeSHA256 computes the SHA-256 checksum of a file at the given path and returns the lowercase hex-encoded hash string.

func ComputeSHA256Reader ¶

func ComputeSHA256Reader(r io.Reader) (string, error)

ComputeSHA256Reader computes the SHA-256 checksum from an arbitrary io.Reader and returns the lowercase hex-encoded hash string.

func ConfirmAction ¶

func ConfirmAction(ctx context.Context, req *mcp.CallToolRequest, message string) (*mcp.CallToolResult, error)

ConfirmAction uses MCP elicitation to ask the user for confirmation before a destructive action. Returns nil if the user confirmed or elicitation is unsupported (fallback: action proceeds — destructive callers must go through ConfirmDestructiveAction, which fails closed in that case). Returns an error tool result if the user declined or canceled. On sessions negotiated at protocol >= 2026-07-28 the confirmation travels as a multi round-trip input request (SEP-2322): the first pass returns an input-required result and the client retries the call with the user's answer attached.

func ConfirmDestructiveAction ¶

func ConfirmDestructiveAction(ctx context.Context, req *mcp.CallToolRequest, params map[string]any, message string) (*mcp.CallToolResult, error)

ConfirmDestructiveAction checks whether a destructive action should proceed. The confirmation flow is:

1. GITLAB_MCP_YOLO_MODE / AUTOPILOT env var → skip confirmation entirely
2. Explicit "confirm": true in params → skip confirmation
3. MCP elicitation supported → ask user interactively
4. Elicitation unsupported and no confirm param → fail closed: return an error result prompting the caller to re-send with confirm: true

Returns nil, nil if the action should proceed. Returns a non-nil *mcp.CallToolResult if the action was canceled or requires explicit confirmation.

The error return is for protocol faults rather than tool outcomes: a requestState this server did not issue, one carrying a version it does not know, or an inputResponses value of the wrong type. "Protocol errors (malformed JSON, invalid schema, internal server errors) SHOULD return a JSON-RPC error response with an appropriate error code and message", and none of those three is something the model wrote or can correct — putting them in a tool result asks it to fix a field its client mangled. Everything a caller can act on (declined, cancelled, a client that cannot prompt) stays in the result, which is where MCP wants tool-level failure.

func ContainsAny ¶

func ContainsAny(err error, substrs ...string) bool

ContainsAny returns true if err.Error() contains any of the substrings.

func ContextWithRequest ¶

func ContextWithRequest(ctx context.Context, req *mcp.CallToolRequest) context.Context

ContextWithRequest returns a derived context carrying the MCP request.

func CopyReadOnlyMetaAnnotations ¶

func CopyReadOnlyMetaAnnotations() *mcp.ToolAnnotations

CopyReadOnlyMetaAnnotations returns a copy of ReadOnlyMetaAnnotations so callers never alias the shared singleton.

Note on ToolAnnotations.Title: it is deliberately left unset here and in DeriveAnnotations. Since MCP 2025-06-18 a Tool carries its own top-level Title, and the display-name precedence is Title → Annotations.Title → Name, so setting both only duplicates the string in every tools/list response. The individual-tool projection has always relied on the top-level Title alone; the meta surface now matches it.

func DecodeEncodedPathIdentifier ¶ added in v3.3.0

func DecodeEncodedPathIdentifier(value string) (string, bool)

DecodeEncodedPathIdentifier reports the percent-decoding of a namespaced path an LLM sent URL-encoded ("group%2Fproject"), and false for anything else. Only a value carrying %2F is decoded, so a successful decode always differs from the input and always carries the "/" the caller is after: '%' is not a hex digit, so no earlier escape can absorb the '%' of a %2F, and PathUnescape either turns it into "/" or fails on the whole value.

It is exported for the handlers whose path input is not one of the identifiers above: a repository file path, a wiki slug, a submodule path. Those are decoded in their own handlers rather than by name here, because "file_path" also names a local filesystem path on every upload action.

func DefuseHintsHeading ¶

func DefuseHintsHeading(s string) string

DefuseHintsHeading rewrites every copy of the server's guidance heading in s so it can no longer pass for one. Text with no such heading is returned unchanged.

func DeriveAnnotations ¶

func DeriveAnnotations(routes ActionMap) *mcp.ToolAnnotations

DeriveAnnotations computes tool-level MCP annotations from the route map. If any route is destructive, returns a copy of MetaAnnotations (DestructiveHint: true). If all routes are non-destructive, returns a copy of NonDestructiveMetaAnnotations. Each call returns a fresh copy to avoid aliasing the shared singletons.

func DeriveSchema ¶

func DeriveSchema(schema any, transform string, derive func() any) any

DeriveSchema returns transform applied to schema, where derive builds the result and transform names the rewrite it performs. The name must identify the rewrite completely: two calls with the same name on the same schema are assumed to want the same output, so any parameter the rewrite depends on belongs in the name.

For a schema registered with ShareSchema the result is built once per process, registered as shared in turn, and returned to every later caller; derive must therefore never mutate its input. For any other schema the result is built privately on every call, exactly as before this memo existed. A transform reapplied to its own output returns that output.

func DetectRichContent ¶

func DetectRichContent(body string) string

DetectRichContent scans a GFM body for non-portable features that may not render correctly outside GitLab (mermaid diagrams, math blocks, raw HTML). Returns a comma-separated list of detected features or an empty string.

func DiscussionThreadOutputsFromGitLab ¶

func DiscussionThreadOutputsFromGitLab[T any](discussions []*gl.Discussion, extras []DiscussionExtra) []T

DiscussionThreadOutputsFromGitLab converts a list of discussions with the extras the captured list answer holds for each, by position, into T, the thread type the caller's package declares over DiscussionThreadOutput (see convertShape).

func DynamicConfirmationDescription ¶ added in v3.2.0

func DynamicConfirmationDescription(confirmationSkipped bool) string

DynamicConfirmationDescription is the text of the x_confirmation marker a destructive action's input schema carries on the dynamic surface, in the schema gitlab_find_action returns and in the one gitlab://tools/{id} serves, which find links every result to. Both readers take it from here, so the two cannot say different things.

confirmationSkipped is the switch the dynamic execute gate reads (IsYOLOMode, issue 1166), and it chooses the text: while the gate asks for confirm, the model is sent to the user for approval first, and once the switch skips the gate the marker says so, since an approval nobody gives would stall the unattended run the switch exists for.

func EditJSONBody ¶ added in v3.3.0

func EditJSONBody(edit BodyEdit) gl.RequestOptionFunc

EditJSONBody returns the request option that applies edit to the body of a write client-go has encoded, for the values an update has to send that its option struct cannot express: a null that clears a field whose pointer is tagged omitempty, an empty list a slice tagged omitempty leaves out, and the removal of a key a field without omitempty writes as null on every call. An edit with nothing in it returns no option, so the request goes out exactly as client-go built it.

It is meant for the POST, PUT and PATCH routes, whose options client-go writes as a JSON object. A body that is not one, or cannot be read, fails the request rather than sending it without the edit it was asked to carry.

func EmbedCanonicalResource ¶

func EmbedCanonicalResource(result *mcp.CallToolResult, template string, params map[string]any, value any)

EmbedCanonicalResource appends the canonical resource of a successful action result: the template is the one the action's spec declares, expanded from the parameters the call carried, and the payload is the JSON form of the output. It is a no-op without a template, on an error result, when a variable is missing, or when embedding is disabled, so every dispatcher can call it unconditionally after formatting.

FinishToolResult calls it last, after the hints have been set on the output, so the JSON the block carries and the structured output of the same result are one serialization: an embed run before the hints carried a body that lacked the next_steps the structured output had.

An output that implements ResourceURIParamsProvider names its own identity: its values are laid over the call's, in a copy, so the URI names the object returned rather than the reference the call resolved.

func EmbedResource ¶

func EmbedResource(result *mcp.CallToolResult, uri, mimeType, text string)

EmbedResource appends an EmbeddedResource content block to result that references the canonical MCP resource URI for the entity returned by the tool. mimeType should typically be "application/json" with text containing a compact JSON serialization of the entity (or empty if the resource is addressable but the body is large).

When result is nil, the URI is empty, or the global toggle is disabled, EmbedResource is a no-op. No further URI validation is performed; callers are responsible for passing well-formed URIs that match an MCP resource template registered with the server.

The block is annotated ResourceMachineDetail: it is the machine-facing payload of one entity, for the assistant deciding what to call next and for a programmatic client, with no display value for a person, which is the one resource family that drops the user role.

func EmbedResourceJSON ¶

func EmbedResourceJSON(result *mcp.CallToolResult, uri string, value any)

EmbedResourceJSON marshals value as JSON and embeds the result with MIME type application/json. Marshaling errors are dropped silently — the tool result is still returned with text and StructuredContent so the LLM has a usable response.

A nil result and an empty URI are decided by EmbedResource, which is the one place a block is appended and already refuses both; repeating the two checks here only meant that no test could tell either copy from the other. The toggle is checked here as well, and that one earns its place: it is what keeps a deployment with embedded resources off from marshaling every entity it is never going to embed.

func EmbeddedResourcesEnabled ¶

func EmbeddedResourcesEnabled() bool

EmbeddedResourcesEnabled reports the current state of the global toggle. Exposed for tests; production code should call EmbedResource directly.

func EmptyMessage ¶ added in v3.1.0

func EmptyMessage(resource string) string

EmptyMessage is the one sentence an empty list renders, "No <resource> found." with its newline, the whole response of a list with nothing in it. The resource is a plural noun the formatter names ("merge requests", "protected branches"). It replaces the heading rather than sitting under it: a heading counting zero above a sentence saying so said it twice.

func EnableEmbeddedResources ¶

func EnableEmbeddedResources(enabled bool)

EnableEmbeddedResources toggles the global EmbedResource behavior. When false, EmbedResource is a no-op, preserving the legacy two-block (text + structuredContent) tool result shape.

func EnrichPaginationConstraints ¶

func EnrichPaginationConstraints(server *mcp.Server)

EnrichPaginationConstraints registers a receiving middleware that walks every tools/list response and injects JSON Schema numeric constraints on the standard pagination property names so LLM clients see the bounds directly in tools/list rather than only through prose in the description.

The middleware operates per property name:

• `page` gets `minimum: 1`
• `per_page` gets `minimum: 1` and `maximum: 100`

Existing constraints are preserved: if a schema already declares `minimum` or `maximum` on these properties the middleware leaves them untouched so domain-specific overrides remain authoritative. Only nodes whose `type` is `integer` or `number` (or unset, defaulting to integer per the Go SDK's int-typed pagination input) are modified, so unrelated properties named `page` on a custom schema cannot be silently mutated.

The transformation runs after LockdownInputSchemas so it sees the same fully-populated schema set every list/tools response carries.

Concurrency. As with LockdownInputSchemas, the mutation runs through [onFirstToolsList], whose `sync.Once` guard prevents concurrent `tools/list` calls from racing on the shared *Tool.InputSchema maps.

Sharing. Like the lockdown, this derives the enriched schema instead of changing the one in place (see DeriveSchema): the lockdown's output is shared across servers, and so is this one.

func ErrFieldRequired ¶

func ErrFieldRequired(field string) error

ErrFieldRequired returns a validation error indicating that a required field is missing or empty. It produces the message "<field> is required", which is the standard validation pattern used across all tool handlers.

func ErrInvalidEnum ¶

func ErrInvalidEnum(field, value string, validValues []string) error

ErrInvalidEnum returns a validation error indicating that a field value is not one of the allowed options. The error message lists the valid values to guide LLMs toward correct parameter usage.

func ErrRequiredInt64 ¶

func ErrRequiredInt64(operation, field string) error

ErrRequiredInt64 returns a formatted error when a required int64 field is missing or has its zero value. This catches silent deserialization failures in meta-tool dispatch, where a misnamed JSON parameter (e.g. "mr_iid" instead of "merge_request_iid") is silently ignored and the field defaults to 0.

func ErrRequiredString ¶

func ErrRequiredString(operation, field string) error

ErrRequiredString returns a formatted error when a required string field is missing or empty. Like ErrRequiredInt64, this guides LLMs to use the exact parameter name when silent deserialization failures occur.

func ErrorResult ¶

func ErrorResult(message string) *mcp.CallToolResult

ErrorResult builds a standard error mcp.CallToolResult with IsError set, through ErrorResultAnnotated with the refusal annotation. The message is the server's own sentence, written as prose.

func ErrorResultAnnotated ¶ added in v3.1.0

func ErrorResultAnnotated(md string, ann *mcp.Annotations) *mcp.CallToolResult

ErrorResultAnnotated builds the one error envelope every refusal this server writes travels in: IsError set, the Markdown as the one text block through NormalizeResultMarkdown, and the annotation given, or ContentMutate for nil, since a refusal is something the model has to act on. The five hand-built literals it replaced carried no annotation and skipped the normalization every success got.

func ErrorResultMarkdown ¶

func ErrorResultMarkdown(domain, action string, err error) *mcp.CallToolResult

ErrorResultMarkdown creates an MCP tool error result carrying the DetailedError card for err, through ErrorResultAnnotated: it is the one path a handler has to a rich error result, and it travels in the same envelope as every other refusal.

func EscapeConsentValue ¶

func EscapeConsentValue(s string) string

EscapeConsentValue renders caller-controlled text for a consent dialog.

"MCP servers requesting elicitation SHOULD NOT include URLs intended to be clickable in any field of a form mode elicitation request." The dialog is where a person decides whether to allow an action, so what it shows has to be the server's own words plus data that cannot pass for them. Interpolating raw values did not meet that: a project path of

demo/proj\n\n**SECURITY NOTICE** Verify at https://evil.example/verify

reached the user as bold text and a link inside the question they were being asked, all of it attacker-supplied by way of the model.

Three things happen here. Line breaks collapse, so a value cannot add paragraphs to the dialog's structure. URL schemes are defanged to https[:]//, which stays legible while leaving nothing for a client to linkify. And the result is fenced in backticks, so emphasis, headings and link syntax inside it are shown rather than rendered — using a fence longer than any run of backticks in the value, the same rule Markdown itself uses for nesting code.

This is escaping, not sanitizing: the text still reaches the user, and should, since a project path they cannot read is no use to them deciding. What it can no longer do is impersonate the server asking the question.

func EscapeMdHeading ¶

func EscapeMdHeading(s string) string

EscapeMdHeading sanitizes a user-controlled string that will be interpolated into a Markdown heading (e.g. `## Project: {name}`). It strips leading '#' characters that could promote/demote the heading level and collapses newlines into spaces so the heading stays on one line.

The opening angle bracket and the opening square bracket are escaped for the reason EscapeMdTableCell gives, and in the same entity form: a heading is the other place a formatter puts a GitLab-authored name, all 44 call sites interpolate one value into a heading the server wrote, and the same name should not turn into a live tag or a live link in a heading after being neutralized in a cell. A heading therefore carries no link: a card's address is its URL row.

func EscapeMdLinkDestination ¶

func EscapeMdLinkDestination(url string) string

EscapeMdLinkDestination renders url as the destination of a Markdown link. It contains the delimiters and judges nothing: whether the value may be a destination at all is LinkableDestination's question, asked by the callers that decide to write a link. The whitespace around the value is dropped first, as LinkableDestination drops it before judging, so the address written is the one that was judged: encoded instead, a leading space made " https://host/x" the relative destination "%20https://host/x". A space inside the value is still encoded.

func EscapeMdLinkLabel ¶

func EscapeMdLinkLabel(s string) string

EscapeMdLinkLabel renders s as the visible text of a Markdown link.

A label is not a cell: escaping the pipe keeps the row intact and does nothing about the bracket. An issue titled

Fix login](http://attacker.invalid/x)

closed the label after "Fix login" and opened a destination of its own, so a reader saw the issue's title linking to a host that is not GitLab — on this server's own instruction, since HintPreserveLinks tells the model to keep the clickable links so the user can navigate to GitLab.

func EscapeMdTableCell ¶

func EscapeMdTableCell(s string) string

EscapeMdTableCell escapes characters in s that would break a Markdown table row. Pipes are replaced with the HTML entity &#124; and newlines/carriage-returns are replaced with a space so the cell stays on a single row. Control characters are dropped by StripControlBytes.

The opening angle bracket is an entity too, for the reason [mdLinkLabelEscaper] gives: a renderer takes raw HTML ahead of whatever surrounds it, so a title of

<a href="http://attacker.invalid/x">Fix login</a>

arrives as a working link to a host that is not GitLab. MdTitleLink closed that for the link case and returns this escaper's output untouched when the item has no URL, which is the ordinary shape for something with no page of its own, and around 266 formatters call this one directly.

An entity rather than the backslash the label escaper uses, because MdTitleLink pipes a cell through that escaper: a backslash arriving there is escaped again into a visible one, where &lt; passes through untouched and renders as the character it always was.

The opening square bracket is an entity as well, &#91;, because a value may be a link only when this server wrote the link around it. A title of

[Fix login](http://attacker.invalid/x)

passed through here as it was, so a cell or a list value the server meant as text rendered as a working link to a host that is not GitLab, and HintPreserveLinks then told the model to keep it clickable. The one consequence worth knowing is that a finished link does not survive this function: a link is built by MdTitleLink from its raw halves and is never escaped afterwards, and a cell that holds one is written as it is.

Only '<' and '[' are escaped, since everything a renderer obeys instead of reading opens with one of them (a tag, a comment, an autolink, a link, an image). '>' and ']' are left alone because callers compose cells of their own: a merge request's branch cell reads "feature/fix -> develop", and entity-encoding the arrow the server itself wrote damages output that no untrusted text ever touched.

The result is idempotent: nothing this function writes is anything it rewrites, so a value escaped twice renders once, which is what lets a caller that still escapes by hand pass its value to a helper that escapes again.

func ExceedsJSONDepth ¶

func ExceedsJSONDepth(raw []byte, limit int) bool

ExceedsJSONDepth reports whether raw nests containers deeper than limit.

Convenience wrapper over JSONDepthScanner for a value that is already whole in memory.

func ExecGraphQLDestroyNote ¶

func ExecGraphQLDestroyNote(ctx context.Context, gql gl.GraphQLInterface, op, hint, query, noteGID string) error

ExecGraphQLDestroyNote runs the destroyNote work item mutation, applying the shared error conventions: transport errors are wrapped with op + hint, a refusal GitLab answers at the top level is reported as that refusal, and the first mutation payload error becomes "op: message".

The document selects the errors alone. The payload type offers a note and a quick actions status as well, and Mutations::Notes::Destroy answers with neither: its resolver returns the errors and nothing else, so both are null on every response.

The top-level check is what keeps a refused delete from reading as a successful one. A note that is gone or that the token may not delete is refused with HTTP 200, a top-level error and a null payload, which client-go does not turn into an error, and a null payload carries no payload error either.

func ExpandResourceURI ¶

func ExpandResourceURI(template string, params map[string]any) (string, bool)

ExpandResourceURI fills a canonical resource URI template from an action's parameters. Each {name} is replaced by the value of the parameter of that name escaped as RFC 6570 simple expansion escapes it ([escapeSimpleExpansion]), so a project given as "group/project" lands in the URI as group%2Fproject and a scoped label priority::high as priority%3A%3Ahigh, which is the form the resource templates accept and the resource handlers decode once; {+name} keeps the slashes of a path-valued parameter, escaping each segment. It reports false when the template is empty or any variable is absent or empty, so a result whose identifier the caller never supplied gets no resource block instead of a URI with a hole in it.

func ExplicitConfirmFromRequest ¶

func ExplicitConfirmFromRequest(req *mcp.CallToolRequest) bool

ExplicitConfirmFromRequest reports whether the caller set the reserved confirm key on this tool call.

The key never reaches a typed action input: [stripReservedKeys] removes it before strict unmarshalling so it cannot trip the unknown-field rejection. A handler that needs to know whether the caller confirmed — because its destructiveness depends on runtime state and cannot be declared on the route — must therefore read it from the raw arguments, which this does for both call shapes: flat on individual tools, and nested under params on the dispatcher surfaces.

func ExtractGitLabMessage ¶

func ExtractGitLabMessage(err error) string

ExtractGitLabMessage extracts the specific error message from the GitLab response err carries, found over REST and GraphQL alike by [gitLabResponseOf]. Returns empty string if not found, if the message only repeats the HTTP status text (e.g. "405 Method Not Allowed"), or if it is an unparsed upstream response body rather than a GitLab message.

The unparsed-body drop belongs to [boundedGitLabMessage], which every path out of here returns through, so it is not tested a second time on the way in: a copy of that test could only agree with the one below it.

What survives is flattened onto one line and truncated to [maxGitLabMessageLen] bytes. GitLab's messages routinely quote input an attacker chose (a branch name, a path, a title), so the span has to stay a span: with its newlines intact it could add structure to the error text a model reads.

func ExtractHints ¶

func ExtractHints(md string) []string

ExtractHints parses the "💡 Next steps" section from a Markdown tool response and returns the individual hint strings. Returns nil when the section is absent.

Only a section in a position the server could have written it is read, and there are exactly two: WriteHints is called either on an empty builder, so the section opens the response, or after the body, so it closes it. The leading form is a defect the migration to one card vocabulary retires, not an idiom, and the number of formatters still using it only shrinks; it is read here because a response that has it carries no other section. A section anywhere in between is content that happens to look like guidance, a README, a job log, a project description, and content does not get to speak as the server. This used to be the first match anywhere in the response, which is what let a file's contents fill next_steps.

func FieldTiers ¶

func FieldTiers(rt reflect.Type) map[string]string

FieldTiers returns a map from top-level JSON field name to the minimum licensing tier declared via the `tier:"premium"` / `tier:"ultimate"` struct tag on the input/output type rt. Fields without a tier tag (the common case, Free) are omitted. Anonymous embedded structs are flattened, mirroring the JSON field promotion used by [secretJSONFieldNames]. The result drives per-instance-tier schema pruning so Free/Premium instances never see fields that require a higher tier.

func FineGrainedErrorNote ¶ added in v3.2.0

func FineGrainedErrorNote(ctx context.Context, actionID string, err error) error

FineGrainedErrorNote is FineGrainedNotes for a handler that reported an answer as a Go error: the error comes back carrying a note after its own message, and still unwraps to the error it was.

Two answers get one. GitLab's missing-permissions refusal of a permission the session's grant does hold, at the boundary type the refusal names, gets the authority's HeldElsewhereNote: GitLab's sentence is the same whether the grant lacks the permission or holds it for other projects, and only the session knows which, so the note says what is missing is this project or group in the grant, or its user's membership there (issue 1336). A not-found error, which is how most GraphQL handlers report a null, gets the NullNote.

func FineGrainedNotes ¶ added in v3.2.0

func FineGrainedNotes(ctx context.Context, actionID string, callResult *mcp.CallToolResult, result any) *mcp.CallToolResult

FineGrainedNotes adds to an answer a fine-grained session was served the next steps that say what GitLab did to it without saying so, and returns it. A classic session's answer is returned as it came.

Three notes, each worded by the authority (internal/finegrained) so every surface words them alike: the parts of the answer GitLab leaves empty for this credential; on a not-found answer of an action that reads GraphQL, that GitLab answers null for an object the token cannot see; and on an empty list of an action whose answer is a GraphQL list or connection, that GitLab leaves out the items the token cannot see. They are written into the answer's own next steps, so the tail every dispatcher applies afterwards (FinishToolResult) carries them into next_steps as well.

A safe-mode preview gets none: it is the answer to a call nothing sent to GitLab, so there is no answer of GitLab's for a note to describe. The meta and dynamic surfaces reach here with one, since safe mode replaces a write's route there (SafeModeActionFunc); the individual surface answers with its preview before it would.

func FineGrainedRefusal ¶ added in v3.2.0

func FineGrainedRefusal(ctx context.Context, req *mcp.CallToolRequest, callName, actionID, prefix string) *mcp.CallToolResult

FineGrainedRefusal is the one check every dispatcher makes before it does anything on an action's behalf: it answers the call with the reason when a fine-grained session may not run the action, and nil when it may.

It reads the authority of the client bound to the request (gitlabclient.AuthorityFrom), which only a fine-grained credential's client carries, so a classic session returns at once and pays nothing. What it decides comes from the authority's Decide and what it says from its WithheldText (internal/finegrained), so every surface refuses in the same words, which name the action by its canonical ID and never a tool.

The dispatchers call it before their own work: in the meta handler right after the action is resolved and its arguments validated, before a destructive action is confirmed and before the route's safe-mode preview; in the individual handler before safe mode; in dynamic execute right after the action is resolved; and in the standalone handler first. A withheld write is therefore never offered for confirmation nor previewed as something this token could do. The receiving middleware answers most calls before the SDK validates their arguments, and this is the defense behind it.

prefix is prepended to the refusal: the dynamic surface names its own tool there, as every refusal it writes does, and every other caller passes "". callName is what the refusal is logged under. The refusal is logged at INFO with the reason class RefusalFineGrained, and the action and its cause at DEBUG, never the token or anything of its grant.

func FinishToolResult ¶ added in v3.1.0

func FinishToolResult(callResult *mcp.CallToolResult, result any, route ActionRoute, params map[string]any) (finished *mcp.CallToolResult, structured any)

FinishToolResult is the one tail every dispatcher applies to a formatted result, so an envelope rule cannot be added to two dispatchers of three again. In order: a nil result, which a formatter returning "" produces, becomes the JSON rendering rather than reaching the client with no content block; an error result is returned as it is, with no structured output, since the action produced none of what its schema describes; every text block is annotated with the action's declared content kind and every image block for the user; the next-step hints the Markdown carries are set on the typed output when its type declares them; and the canonical resource is embedded last, so the JSON it carries agrees with the structured output, hints included.

The hints are set through the output's own HintSetter, never spliced into its JSON: the individual surface validates the structured output against the schema the type declares, and a next_steps key on a type that declares none would fail that validation, so a type without HintableOutput carries its hints in the Markdown alone.

func FormatCICDVariableCollectionMarkdown ¶

func FormatCICDVariableCollectionMarkdown[T any](variables []T, pagination PaginationOutput, convert func(T) CICDVariableMarkdown, title, emptyMessage string, includeEnvironmentScope bool, hints ...string) string

FormatCICDVariableCollectionMarkdown maps package-specific CI/CD variable outputs and renders them as a shared Markdown list.

func FormatCICDVariableDetailMarkdown ¶

func FormatCICDVariableDetailMarkdown(v CICDVariableMarkdown, title string, includeEnvironmentScope bool, hints ...string) string

FormatCICDVariableDetailMarkdown renders a CI/CD variable as the card the project, group and instance variables share, closed with the next steps the caller names. The hints are the caller's because the actions that update and delete a variable differ by scope (ci_variable.update, ci_variable.group_update, ci_variable.instance_update), and a card shared by all three cannot name one of them for the other two.

func FormatDiscussionMarkdown ¶

func FormatDiscussionMarkdown(discussion DiscussionMarkdown, hints ...string) string

FormatDiscussionMarkdown renders a single discussion thread as the card of one thread: the heading the card writer escapes, the thread's notes quoted under their authors, and the hints last. The notes are a collection the reader reads rather than a table of columns, so they keep the shape [writeDiscussionNotes] gives them.

The thread id reaches this renderer as a field of the result rather than as a literal the server wrote, and a heading is the one line where a value that is not a digest would open a tag, so the card's heading escaper is what contains it.

func FormatGID ¶

func FormatGID(typeName string, id int64) string

FormatGID builds a GitLab Global ID string from a type name and numeric ID.

FormatGID("Vulnerability", 42) → "gid://gitlab/Vulnerability/42"

func FormatGraphQLForwardPagination ¶

func FormatGraphQLForwardPagination(p GraphQLForwardPaginationOutput, shown int) string

FormatGraphQLForwardPagination renders the pagination metadata of a forward-only connection, which never names a previous page.

func FormatGraphQLPagination ¶

func FormatGraphQLPagination(p GraphQLPaginationOutput, shown int) string

FormatGraphQLPagination renders cursor-based pagination metadata as a Markdown summary line, suitable for appending to list tool responses.

func FormatISOTimePtr ¶

func FormatISOTimePtr(t *gl.ISOTime) string

FormatISOTimePtr renders an optional *gl.ISOTime as YYYY-MM-DD, or "" when nil.

func FormatLabelListMarkdownFunc ¶

func FormatLabelListMarkdownFunc[T any](labels []T, pagination PaginationOutput, opts LabelMarkdownOptions, convert func(T) LabelMarkdown) string

FormatLabelListMarkdownFunc renders labels after mapping domain-specific outputs to the shared Markdown view.

func FormatLabelMarkdown ¶

func FormatLabelMarkdown(label LabelMarkdown, opts LabelMarkdownOptions) string

FormatLabelMarkdown renders a project or group label as a card: the identity rows, the description as the card's long text, the priority when GitLab sent one, the two flags as glyphs, and the counters when GitLab sent them, zeros included, since a label a listing counted and nothing uses is an answer of its own.

func FormatNoteListMarkdown ¶

func FormatNoteListMarkdown(notes []NoteMarkdown, pagination PaginationOutput, opts NoteListMarkdownOptions) string

FormatNoteListMarkdown renders a list of GitLab notes as a Markdown table. The table carries no link, so the footer carries no instruction to keep them.

func FormatNoteMarkdown ¶

func FormatNoteMarkdown(note NoteMarkdown, opts NoteMarkdownOptions) string

FormatNoteMarkdown renders a single GitLab note as a card: the author as a handle, the time, the flags that hold, the resolution state when the domain has one, the body as the card's long text, quoted under its label when it spans more than one line, and what the quick actions in the body did when a mutation reported it.

A note GitLab synthesizes from a resource event has no ID, so its card is headed by its global ID and says why no note action takes it.

func FormatQuickActionsOnlyMarkdown ¶ added in v3.1.0

func FormatQuickActionsOnlyMarkdown(title string, status QuickActionsStatusOutput, hints ...string) string

FormatQuickActionsOnlyMarkdown renders the answer to a note mutation whose body held nothing but quick actions: GitLab ran them and kept no note, so there is no note to show, only what the commands did. title names the kind of note the caller asked for ("Epic Note").

func FormatRESTDiscussionListMarkdown ¶

func FormatRESTDiscussionListMarkdown[T any](discussions []T, pagination PaginationOutput, convert func(T) DiscussionMarkdown, title, emptyMessage string, hints ...string) string

FormatRESTDiscussionListMarkdown maps REST discussion outputs and renders them with offset pagination metadata.

func FormatSafeModePreviewMarkdown ¶ added in v3.1.0

func FormatSafeModePreviewMarkdown(p SafeModePreview) string

FormatSafeModePreviewMarkdown renders a preview as a card, the way every other refusal is rendered: the intercepted tool in the heading, the status and mode rows, the tool as a code span, the would-be arguments in a JSON fence, and the operator's hint last. It is the registered formatter for SafeModePreview, so the dispatcher surfaces render the preview through it, and SafeModePreviewResult is what the individual surface answers with.

The hint is escaped, unlike every other hint this server writes. WriteHints writes a hint as it is given because a hint is the server's own sentence composed at the call site, and one of them, HintPreserveLinks, is a link; here the hint is a field of a struct the formatter is handed, so it is data on the same terms as the status and the mode. Unescaped it could end its own bullet and open a heading, a list item or a second guidance section below the card, which took the real hint out of next_steps with it.

func FormatStorageMoveCollectionMarkdown ¶

func FormatStorageMoveCollectionMarkdown[T any](moves []T, pagination PaginationOutput, convert func(T) StorageMoveMarkdown, title, emptyMessage, entityColumn string) string

FormatStorageMoveCollectionMarkdown maps package-specific storage moves and renders them as a shared Markdown list.

func FormatStorageMoveDetailMarkdown ¶

func FormatStorageMoveDetailMarkdown(move StorageMoveMarkdown, title string, hints ...string) string

FormatStorageMoveDetailMarkdown renders one repository storage move as a card: the identity and state rows, the two storages, the creation time in the display form, and the moved entity as a link with its ID.

func FormatTarget ¶

func FormatTarget(targetType string, targetIID int64, targetTitle, targetURL string) string

FormatTarget builds a Markdown table cell for a typed target resource. When targetURL is non-empty, the result is a clickable link like [Issue #42](url). When empty, the label is returned as plain text. Returns "" if there is nothing to display.

The title reaches MdTitleLink raw. It used to be escaped here and again inside the link helper, which was harmless only while the escaper left every character it wrote alone; the rule now is that a link is built from its raw halves once, and escaping a value that is about to be linked is the shape that turns the link back into text.

func FormatTemplateAttributeListMarkdown ¶

func FormatTemplateAttributeListMarkdown(items []TemplateAttributeListMarkdownItem, opts TemplateAttributeListMarkdownOptions) string

FormatTemplateAttributeListMarkdown renders a template list as a table, in the two-column and the three-column shape alike, so the two families share one heading, one empty form and one footer. Templates carry no link, so the footer carries no instruction to keep them.

func FormatTemplateContentMarkdown ¶

func FormatTemplateContentMarkdown(title, name, language, content string, hints ...string) string

FormatTemplateContentMarkdown renders a GitLab template body as a card whose only content is the body inside a fenced code block, through Card.Fence, which sizes the fence past the longest backtick run in the body. On an instance with custom file templates the set is served out of a designated project, so the name is a repository file name somebody chose, and the heading is escaped as every card heading is.

func FormatTemplateDetailMarkdown ¶

func FormatTemplateDetailMarkdown(detail TemplateDetailMarkdown) string

FormatTemplateDetailMarkdown renders a template detail page as a card: the identity rows, the description as the card's long text, the three lists joined on their rows, and the content in a fence under its heading when the caller named one. The project-template endpoints also serve issue and merge-request description templates, whose name is a file in .gitlab/issue_templates named by whoever pushed it, so the heading is escaped as every card heading is.

func FormatTime ¶

func FormatTime(s string) string

FormatTime converts an RFC3339 timestamp string to a human-readable format ("2 Jan 2006 15:04 UTC"), falling back to the date-only layout and then to the string it was given.

Every one of this function's callers writes the result straight into Markdown, so the fallback runs it through EscapeMdTableCell rather than returning it as it arrived. A value that reaches the fallback is by definition not a timestamp, which leaves only two ways to get there: a field this server formatted itself and a field carrying whatever GitLab put in it. Returning the second verbatim put a pipe, a newline and a '<' into a table cell from 155 call sites, and telling each of those call sites to escape a timestamp would have taught the next reader that a date needs escaping. Escaping here costs nothing that renders: neither layout's output contains any character the escaper touches.

func FormatTimePtr ¶

func FormatTimePtr(t *time.Time) string

FormatTimePtr renders an optional *time.Time as RFC 3339, or "" when nil.

It is superseded by RFC3339Ptr, which it is an alias of: the name says display and the output is the wire form, which is how a table came to show RFC 3339 where every other one shows FormatTime's layout. New code calls RFC3339Ptr, or FormatTimeValue for a value a reader sees, and the staticcheck deprecation marker goes on here once the forty-odd callers have moved, since the marker fails the lint gate on every one of them until then.

func FormatTimeValue ¶ added in v3.1.0

func FormatTimeValue(t time.Time) string

FormatTimeValue renders t in the display form, or "" for a zero time, which is what a field GitLab did not send decodes to and would otherwise read as the year one.

func GraphQLMutationError ¶

func GraphQLMutationError(operation string, payloadErrors []string) error

GraphQLMutationError formats mutation payload errors, if any.

func GraphQLNullPropagated ¶ added in v3.3.0

func GraphQLNullPropagated(messages []string) bool

GraphQLNullPropagated reports whether the top-level errors of a GraphQL answer are all the ones a null below a non-null position writes, which is how an object GitLab denied answers where its position cannot be null. A set holding any other message, a refusal among them, is not one, and neither is an empty set: an answer that came back null with no error is the caller's to see.

func GraphQLNumber ¶ added in v3.1.0

func GraphQLNumber(s string) int64

GraphQLNumber reads a number GitLab's GraphQL API spells as a String: the iid of an issue or a merge request. A value that is not a number, which the schema allows, reads as zero rather than an error, since the object it sits on is worth reporting whether or not that one value parsed.

func GraphQLPartialPage ¶ added in v3.3.0

func GraphQLPartialPage(operation string, responseErrors []GraphQLError, kept, nulled int) (string, error)

GraphQLPartialPage reads what GitLab said beside a page of a connection it answered (issue 1298). GitLab nulls a node or a field it could not resolve where it sits and explains the null in errors[], keeping the rest of the answer, so errors[] beside a connection that resolved mean the page was answered in part, and a node answered null with no error is one left out all the same. kept is how many nodes the page still holds, and nulled how many it answered null.

It returns the account a page's card names, empty for a page answered whole, and an error for a page with no node left: read as a page, that answer would say the list is empty, which is what nobody knows. With errors[] the error is GraphQLTopLevelError's, so a refusal it carries is read as one.

func GraphQLTopLevelError ¶

func GraphQLTopLevelError(operation string, responseErrors []GraphQLError) error

GraphQLTopLevelError formats top-level GraphQL response errors, if any.

The error it returns keeps each message apart as well as joined into its text, because a message is read whole: GitLab refuses a GraphQL mutation a fine-grained token lacks the permission for with one errors[] entry whose message is exactly the sentence its authorization service wrote, and one of those sentences, "404 Not Found", means something only as a whole entry ([fineGrainedRefusalOf]).

func HasRegisteredMarkdownFormatter ¶

func HasRegisteredMarkdownFormatter(v any) bool

HasRegisteredMarkdownFormatter reports whether a Markdown formatter has been registered for the given Go type. Accepts either a reflect.Type (the canonical lookup path, matching spec.Route.OutputType) or a value of any kind (used by tests). Pointer types are dereferenced to their element type for the registry lookup, exactly as MarkdownForResult dereferences a pointer value. Returns false for nil, for the special "interface" reflect.Type returned by reflect.TypeOf on a nil/untyped interface, and for unregistered types.

This is the authoritative source for "is there a Markdown formatter for this output type?" queries from external tools (e.g. cmd/audit_discovery_completeness uses it to gate the `missing_next_steps` check).

func HintAction ¶ added in v3.1.0

func HintAction(actionID, purpose string) string

HintAction composes a next-step hint that names an action by its canonical catalog ID, "Use action 'issue.update' to change this issue". The dynamic surface executes that ID as it is written. The meta and individual surfaces do not accept it: a meta tool's action argument takes the action's name within that tool, and an individual tool is named by its own declared name, which no rule derives from the ID (issue 1325). Those two surfaces register their dispatchers' formatters through WithResolvedNextSteps, which rewrites the hint into the call they accept before the result leaves the server, so a hint is written once, here, in the one form every surface can be resolved from.

func IdentityToContext ¶

func IdentityToContext(ctx context.Context, id UserIdentity) context.Context

IdentityToContext stores a UserIdentity in the context. Used at startup in stdio mode to make the identity available to all tool handlers.

func ImageMIMEType ¶

func ImageMIMEType(filename string) string

ImageMIMEType returns the MIME type for image file extensions. Returns an empty string for non-image files.

func IndividualToolFromActionSpec ¶

func IndividualToolFromActionSpec(spec ActionSpec, opts IndividualToolProjectionOptions) (*mcp.Tool, error)

IndividualToolFromActionSpec projects canonical action metadata into an MCP tool definition for the individual-tool surface.

func IndividualToolFromSpecs ¶

func IndividualToolFromSpecs(specs []ActionSpec, individualName string, opts IndividualToolProjectionOptions) (*mcp.Tool, error)

IndividualToolFromSpecs projects the spec that owns an individual tool name.

func InputRequiredResultFromError ¶

func InputRequiredResultFromError(err error) (*mcp.CallToolResult, bool)

InputRequiredResultFromError extracts the input-required tool result from a handler error produced by elicitation.Flow.PendingError. Surface dispatchers call this before logging so a pending multi round-trip exchange is returned to the client instead of being reported as a handler failure.

func InstanceWebURL ¶ added in v3.3.0

func InstanceWebURL(apiBase *url.URL) *url.URL

InstanceWebURL returns the web URL of the instance whose REST API is at apiBase: the API base with its trailing "api/v4/" removed, so an instance served under a relative URL root keeps the root (https://example.com/gitlab/api/v4/ gives https://example.com/gitlab/). The path always ends in "/". The userinfo, query and fragment an operator may have configured are left out, since the result is compared with URLs and never sent anywhere. apiBase itself is not changed.

func Int64UserIDFilter ¶ added in v3.3.0

func Int64UserIDFilter(field string, value StringOrInt) (*int64, gl.RequestOptionFunc, error)

Int64UserIDFilter reads a user ID filter for an option struct that types it *int64 and so cannot carry None or Any, which is how client-go's issue statistics options declare assignee_id (upstream register row 125). A user ID comes back as the pointer for the option. None and Any come back as a request option that writes the literal into the query under field, the option struct's field left nil. A filter left out returns neither, and a refusal returns only the error.

func InternalError ¶

func InternalError(err error) error

InternalError marks an error as JSON-RPC -32603: an upstream call failed or a response would not decode, and there is nothing the caller can change.

func InvalidParams ¶

func InvalidParams(err error) error

InvalidParams marks an error as JSON-RPC -32602: the caller sent something missing, empty or unparseable, and has to change it.

func IsBinaryFile ¶

func IsBinaryFile(filename string) bool

IsBinaryFile returns true when the filename has a known binary extension that is not an image. Returns false for text and image files.

func IsDeleteToolName ¶

func IsDeleteToolName(name string) bool

IsDeleteToolName reports whether name contains or ends with "delete".

func IsDownloadTooLarge ¶ added in v3.3.0

func IsDownloadTooLarge(err error) bool

IsDownloadTooLarge reports whether err is a response ceiling refusing a body (gitlabclient.ErrResponseTooLarge): the client-wide one, or the one an action set on its request with gitlabclient.WithResponseLimit. A handler asks it of an SDK call's error so that a body the read stopped gets the same way out as one the action's own ceiling refused, rather than a bare "unexpected error".

func IsHTTPStatus ¶

func IsHTTPStatus(err error, code int) bool

IsHTTPStatus reports whether GitLab answered err with the given HTTP status code, over REST or over GraphQL. Useful for handling specific API responses like 404 (feature not available on CE) or 403 (insufficient permissions).

The status is read the way ClassifyError reads it, so the two never disagree about one error: a GraphQL refusal is looked through, and a 404 is recognized by client-go's sentinel, which carries no response.

func IsImageFile ¶

func IsImageFile(filename string) bool

IsImageFile returns true when the filename has an image extension. Comparison is case-insensitive. Returns false for empty strings.

func IsInternalInspection ¶ added in v3.2.0

func IsInternalInspection(ctx context.Context) bool

IsInternalInspection reports whether ctx carries WithInternalInspection's mark.

It is exported for the layers that narrow what a fine-grained session is listed (issue 952): the tools/list filter, the find filter and the gitlab://tools filter all hand the server's own listings the whole surface, since registration counts, narrows and snapshots what it registered, and on stdio the credential those listings would otherwise be filtered for is the process's own.

func IsNotFound ¶

func IsNotFound(err error) bool

IsNotFound reports whether err represents a 404 Not Found, either via a structured GitLab ErrorResponse status code or via a plain-text error message from client-go (which may contain "404 Not Found" as text).

func IsPermissionRefusal ¶ added in v3.1.0

func IsPermissionRefusal(err error) bool

IsPermissionRefusal reports whether GitLab answered err with a refusal that can be a valid credential lacking a permission: a REST 401 or 403 whose body carries no RFC 6750 error code and does not refuse the account itself, which gitlabclient.RefusalMayBePermission decides. It is what a handler keys a hint naming a role, a license or an owner on, where IsHTTPStatus with 403 used to be.

The 401 is the reason it exists. At the routes entry 55 of docs/development/upstream-bugs.md lists, GitLab refuses a missing permission with 401, so a hint scoped to 403 was never shown there. A hint scoped to 401 alone is wrong the other way: ClassifyError describes a 401 that GitLab said was about the credential as the token itself being refused, and a role suggestion after that verdict contradicts it. This predicate is false for those answers, for every other 401 or 403 the API guard writes a code on (a DPoP refusal or a restricted language server client, which ClassifyError does not describe as the token being refused, are among them), for its 403 about a missing token scope, and for its 403 refusing an account the API will not serve (blocked, deactivated, the Terms of Service not accepted and the like), so the hint follows only a description that leaves a permission refusal open. gitlabclient.RefusalMayBePermission holds the full rule.

A handler whose route answers a 403 that means something else, a license or an archived project rather than a role, pairs it with IsHTTPStatus to tell the two apart. The 403 is kept here because it is what these routes would answer if GitLab retired entry 55, and then a handler that keys one hint on this predicate alone needs no change. The handlers that pair it with a status do, since each reads the status as the cause: the security settings routes, the three external status check merge request routes, the fork link and the merge train add. Those are the ones to revisit when entry 55 is retired.

func IsReadToolName ¶

func IsReadToolName(name string) bool

IsReadToolName reports whether name ends with a read-only suffix.

func IsTerminalStatus ¶

func IsTerminalStatus(status string) bool

IsTerminalStatus reports whether a CI/CD status represents a finished state.

func IsYOLOMode ¶

func IsYOLOMode() bool

IsYOLOMode returns true when destructive action confirmation should be skipped entirely. It reads GITLAB_MCP_YOLO_MODE (or its old spelling YOLO_MODE, warned about at startup like every other renamed setting) and falls back to AUTOPILOT, a convention other agent tooling sets. Any truthy value (1, true, yes — case-insensitive) enables the mode.

func IssueStateEmoji ¶

func IssueStateEmoji(state string) string

IssueStateEmoji returns the Markdown emoji for an issue state.

func KeysetContinuation ¶ added in v3.3.0

func KeysetContinuation(keyset KeysetPaginationInput) gl.RequestOptionFunc

KeysetContinuation returns the request option every handler of a list GitLab pages by keyset passes on its SDK call, last, after gl.WithContext. When page_token is a next_page_token a previous response published, the next link's query becomes the whole query of the request through gl.WithKeysetPaginationParameters, so each endpoint is sent the parameter it pages by (id_before or id_after, cursor, page_token or last) and the rest of the listing's arguments exactly as GitLab read them and wrote them into the link. Whatever else the call sends in its query is dropped: GitLab writes every parameter of the listing into its link, an Array one such as labels or topic in Rack's bracket form (labels[]=a), while client-go sends the same filter comma-separated under the bare name, and Rack refuses with 400 a query that carries both. Any other page_token is a raw GitLab page token, which ApplyListOptions has already put on the request, and an empty one is the first page: neither changes it.

A continuation that carries a credential or sudo is refused rather than applied, because passing it on would let a page_token authenticate, or act as another user, where no argument of the action can.

func LabelForRevision ¶ added in v3.2.0

func LabelForRevision(req mcp.Request, result *mcp.CallToolResult) *mcp.CallToolResult

LabelForRevision returns result, which a receiving middleware answers the tools/call req with in place of the SDK's tool dispatcher, carrying the resultType req's revision requires.

Revision 2026-07-28 requires resultType on every result. go-sdk v1.8.0 sets it on a tools/call result only inside its own tool dispatcher, because such a result can also be input_required, and labels after the middleware chain returns only the result types that can never be input_required. So a tool result a middleware makes, which is what a refusal is, went to a 2026-07-28 client without the field while every call the dispatcher served carried "complete". The SDK keeps the field unexported behind an unexported setter, and its own decoding is the one public way to set it: the result is written with every field it has and its resultType, and read back through mcp.CallToolResult.UnmarshalJSON.

The resultType is chosen the way the SDK's dispatcher chooses it, by whether the result carries InputRequests: "input_required" when it does, even an empty map, which the SDK reads as load shedding, and "complete" when it does not. Labeled "complete", a result asking for input would go out as {"resultType":"complete","inputRequests":...}, and a client that trusts the label drops the requests; left as it was, it would go out with no label, breaking the requirement this exists to meet.

A request of an earlier revision gets result as it is, which is what the SDK sends such a client from its own dispatcher (see [namesResultTypeRevision] for where the two tests differ), and so does a nil result, which has nothing to label. A result that cannot make the round trip is handed back unlabeled too, the answer the SDK would have sent: no refusal this server makes is one, since each is a text block and an error flag.

It is the workaround for row 66 of docs/development/upstream-bugs.md, which go-sdk fixed after v1.8.0 in e40f35d, the merge of its pull request 1226. TestSDK_MiddlewareToolResult_GoesOutUnlabeled fails on the bump that brings the fix and says what to delete.

func LinkableDestination ¶ added in v3.1.0

func LinkableDestination(url string) bool

LinkableDestination reports whether url may be written as the destination of a link or an image: an absolute http or https address, and nothing else.

The escaper above contains the delimiters, so a value cannot end the link it is in, and it says nothing about the scheme. A javascript, data or vbscript destination is a whole link that a client renders live, and it is the client's renderer that decides what a click does: goldmark drops such a destination on its own, and a chat surface that hands the href through does not. Every address this server links is one GitLab built from its own origin, so the allow list costs nothing legitimate. The check runs on the value with its control bytes gone, because "java\x00script:" is the escaped destination "javascript:" and would pass a check made on the bytes as sent.

Plain http is admitted on purpose: a self-managed instance served without TLS builds every address it sends on that scheme, and refusing it would unlink every row such an instance answers with. The scheme is read as the text before the first "://" and compared whole, so "xhttp" and "httpx" are refused, and an address is only linked when something follows the separator. A value with no separator at all has nothing following one, which is the same refusal.

func ListHints ¶

func ListHints(hints ...string) []string

ListHints prepends HintPreserveLinks to list-result next-step hints, once: an empty hint or a copy of HintPreserveLinks among the arguments is dropped, so a caller that already names it does not get it twice. The hints it returns are for the section a list formatter writes after its table. Writing that section first, on an empty builder, is a defect rather than an idiom: the guidance then opens the response, ahead of the data it is about, and any hint the formatter appends afterwards can never reach next_steps, since ExtractHints reads a section only at one end of the response.

func ListRegisteredTools ¶

func ListRegisteredTools(ctx context.Context, server *mcp.Server, clientName string) ([]*mcp.Tool, error)

ListRegisteredTools lists tools registered on a server through an ephemeral in-memory MCP client session.

func LocalFilesystemAccessAllowed ¶

func LocalFilesystemAccessAllowed() bool

LocalFilesystemAccessAllowed reports whether caller-supplied local paths are honored in this process.

func LockdownInputSchemas ¶

func LockdownInputSchemas(server *mcp.Server)

LockdownInputSchemas registers a receiving middleware that rewrites tools/list responses so every tool's inputSchema declares `additionalProperties: false` at the root and on any nested object schema reachable through "properties", "items", "anyOf", "oneOf", or "allOf". It also strips jsonschema tag metadata such as ",required" from property descriptions after the SDK generates schemas. Schemas converted from SDK types are stored back as map[string]any values, so callers inspecting tools after this middleware runs should not expect the original concrete schema type.

Background. The MCP specification (2025-11-25 §server/tools) requires inputSchema to be a valid JSON Schema object but does not mandate `additionalProperties`. JSON Schema 2020-12 default semantics treat an unspecified `additionalProperties` as `true`, which silently accepts unknown fields. When an LLM mistypes an argument name (e.g. "projetc_id" instead of "project_id"), the server forwards an empty value to the handler, which then fails with a confusing "missing parameter" error rather than the actionable "unknown property" diagnostic the LLM needs to self-correct.

Schemas that already declare `additionalProperties` (true or false) at a given level are left untouched, so meta-tool router branches that intentionally permit unknown fields for forward compatibility remain intact.

Concurrency. The MCP Go SDK does not expose a public API to enumerate registered tools at startup, so the transformation runs inside a `tools/list` middleware via [onFirstToolsList], which guards the mutation with a `sync.Once`.

Sharing. The schema a tool carries at that point is never changed in place: a compiled schema is shared by every server in the process through the compile cache, and a map may be shared through a catalog. The locked down form is derived from it, once per process for a shared schema (see DeriveSchema), so a thousand pooled servers list one set of maps.

func LogMarkupRawOffset ¶ added in v3.3.0

func LogMarkupRawOffset(s string, n int) int

LogMarkupRawOffset returns where, in the log s as written, the byte that StripLogMarkup keeps at offset n stands, n running from 0 to the length of the stripped text, whose end is the end of s: s from that offset strips to the stripped text from n. It maps n back through the two passes StripLogMarkup makes, the escape sequences of the text the section markers were removed from and then the markers of s, since a marker inside a sequence leaves a sequence only the second pass sees.

func LogToolCallAll ¶

func LogToolCallAll(ctx context.Context, req *mcp.CallToolRequest, tool string, start time.Time, result any, err error)

LogToolCallAll logs a tool call to stderr (slog). It is the standard logging function for all tool handlers. When the request contains authenticated user identity (any mode), it includes the user in the log output for audit trail purposes.

result is what the handler returned, taken so the record can say whether the call actually succeeded. A handler that reports failure in its result rather than as a Go error, which NotFoundResult does in every get handler that uses it, used to be logged as "tool call completed" with nothing distinguishing it from a call that worked. An operator could not compute an error rate from this stream, because the stream did not contain one.

func LogToolRefusal ¶

func LogToolRefusal(ctx context.Context, req *mcp.CallToolRequest, tool, reason string)

LogToolRefusal records a call the server declined to run.

These paths returned an error result to the model and wrote nothing at all: safe-mode previews, unknown actions, missing parameters and unconfirmed destructive actions each returned before reaching LogToolCallAll. They are refusals rather than failures, so they are INFO, and they are exactly the events an operator most wants to count: a deployment refusing every third call because its clients have not learned the parameter shape looks identical to a healthy one from the logs.

It is the second half of the observability item ADR-0011 already accepted: "add observability for find query, selected action, validation failure, policy block, and destructive confirmation events". Only the destructive one was delivered.

func LookupMetaActionSchema ¶

func LookupMetaActionSchema(routes map[string]ActionMap, tool, action string) (map[string]any, bool)

LookupMetaActionSchema returns the per-action params schema for a tool/action pair.

func MRStateEmoji ¶

func MRStateEmoji(state string) string

MRStateEmoji returns the Markdown emoji for a merge request state.

func MakeMetaHandler ¶

func MakeMetaHandler(toolName string, routes ActionMap, formatResult FormatResultFunc) func(ctx context.Context, req *mcp.CallToolRequest, input MetaToolInput) (*mcp.CallToolResult, any, error)

MakeMetaHandler creates a generic MCP tool handler that dispatches to action routes. The formatResult function converts the action result into an MCP response. If formatResult is nil, a default JSON formatter is used.

Destructive actions (delete, remove, revoke, unprotect, etc.) are automatically intercepted with a user confirmation prompt via MCP elicitation before execution. Confirmation can be bypassed with GITLAB_MCP_YOLO_MODE/AUTOPILOT env vars or by passing "confirm": true in the action params.

func MarkdownCodeFence ¶

func MarkdownCodeFence(content string) string

MarkdownCodeFence returns a backtick fence long enough to contain content: three backticks, or one more than the longest run inside it.

A fixed three-backtick fence is closed by any content that contains one, and the content here is a repository file, a job log, a snippet or a diff, written by whoever can push a branch or run a pipeline. Everything after the run they wrote renders as live Markdown at the top level of the response: headings, links, and the server's own guidance section. Sizing the fence to the body is the rule Markdown itself uses for nesting code, and it is why this helper exists rather than a literal.

func MarkdownFencedBlock ¶

func MarkdownFencedBlock(language, content string) string

MarkdownFencedBlock renders content as a complete fenced code block: a fence sized by MarkdownCodeFence, the info string, the body, and the matching closing fence on its own line. Pass an empty language for a bare fence.

Prefer it over writing a fence by hand wherever the body is GitLab-authored.

func MarkdownForResult ¶

func MarkdownForResult(result any) *mcp.CallToolResult

MarkdownForResult resolves a tool output to its Markdown mcp.CallToolResult. A nil input renders the success confirmation; a value of an unregistered type, or a typed nil pointer, renders nil for the dispatcher to fall back on. A pointer to a registered type is dereferenced first, which is the same question HasRegisteredMarkdownFormatter answers: the two used to disagree, so a handler returning a pointer had a formatter the coverage test could see and the runtime never called.

func MarkdownFormatterCount ¶

func MarkdownFormatterCount() int

MarkdownFormatterCount returns the number of registered Markdown formatters (string + result variants). Useful for sanity checks in tests and tools that need to know "are formatters even loaded?".

func MarkdownRegistrationProblems ¶ added in v3.1.0

func MarkdownRegistrationProblems() []string

MarkdownRegistrationProblems returns every registration the registry refused or could only half honor, sorted, for a test to assert there are none.

func MarkdownTableHeader ¶

func MarkdownTableHeader(columns ...string) string

MarkdownTableHeader returns a Markdown table header followed by a standard separator row for the supplied column labels.

func MarkdownTableRow ¶

func MarkdownTableRow(cells ...string) string

MarkdownTableRow returns a Markdown table row for the supplied cell values.

func MdCodeSpan ¶ added in v3.1.0

func MdCodeSpan(s string) string

MdCodeSpan renders a GitLab-authored value as an inline code span, for a value the reader has to copy exactly: a token, a variable key, a path, a SHA, a command.

A code span is its own containment, so nothing inside it is Markdown and no entity is written: "&#124;" and "&lt;" render literally inside one, which is what the sites that filled a span with EscapeMdTableCell were showing. What a value can still do is end the span with a backtick run of its own, so the fence is one backtick longer than the longest run inside, the rule Markdown itself uses for nesting code. Line breaks collapse to a space, since a span ends with its line, and control bytes are dropped. A value that begins or ends with a backtick is padded with a space on both sides, which CommonMark strips again. An empty value renders as nothing rather than as two bare backticks, which read as a span that never closes.

func MdCodeSpanCell ¶ added in v3.1.0

func MdCodeSpanCell(s string) string

MdCodeSpanCell renders a value as MdCodeSpan does, for a table cell: the pipe is backslash-escaped, which GFM honors inside a code span in a table and which is the one escape that works there, since the entity a cell would otherwise use renders literally inside the span.

func MdTitleLink ¶

func MdTitleLink(title, url string) string

MdTitleLink returns the title as a Markdown link if url is non-empty, otherwise returns the escaped title. Suitable for table cells. Both halves are escaped, so neither the title nor the URL can end the link they are in, and a destination that is not an http or https address is not linked at all: the address is written in a code span, after the title when the title says something else, so the reader keeps what GitLab sent and nothing in it is live. A websocket endpoint or a wiki attachment's relative path lands here as well as a hostile value, and a code span is the honest rendering of an address a client could not have opened anyway.

func MdUserHandle ¶ added in v3.1.0

func MdUserHandle(username string) string

MdUserHandle renders a username as the "@handle" GitLab shows, escaped for a card row or a cell, or nothing for an empty name, so a card never shows a bare "@".

func MdUserLink ¶ added in v3.1.0

func MdUserLink(username, webURL string) string

MdUserLink renders a username as its handle linked to the user's profile, through MdTitleLink, the escaped handle alone when the profile URL is empty, and nothing for an empty name.

func MergeRequestDiffsForPositionCheck ¶ added in v3.1.0

func MergeRequestDiffsForPositionCheck(ctx context.Context, client *gitlabclient.Client, projectID string, mrIID int64) ([]*gl.MergeRequestDiff, bool)

MergeRequestDiffsForPositionCheck lists a merge request's diffs for a position pre-check and reports whether it could.

The pre-check exists to hand a model an actionable message before GitLab answers a line outside the diff with a bare 400 or 500, and it is advisory: when the listing itself fails the second result is false and the caller skips the check rather than refusing the write. What is skipped is the message, never the judgement, because the write that follows goes to the same instance with the same credential and GitLab answers it on its own terms. A 401, 403 or 404 on the listing is the refusal the write is about to get, with the right status; a cancelled context ends the write the same way; and a transient failure on the listing leaves the write judged by GitLab alone, which is exactly what a caller had before the pre-check existed. The cause is logged at debug so that a listing which fails every time can be seen without the write having to fail.

func MergeVariables ¶

func MergeVariables(sources ...map[string]any) map[string]any

MergeVariables merges multiple variable maps into a single map. Later maps override earlier ones for duplicate keys.

func MetaActionSchema ¶

func MetaActionSchema(route ActionRoute) map[string]any

MetaActionSchema returns the params schema served for one meta-tool action: the route's input schema with the destructive confirmation property and the parameter guidance added, or a permissive placeholder when the route captured no schema. For a route of a shared catalog the result is built once per process and shared; the caller must not mutate it.

func MetaParamSchemaMode ¶

func MetaParamSchemaMode() string

MetaParamSchemaMode reports the meta-tool input schema strategy currently selected by SetMetaParamSchemaMode: "opaque", "compact" or "full". Callers that memoize a registered surface must key on it, because the same registration produces different input schemas under each mode.

func MetaSchemaURI ¶

func MetaSchemaURI(tool, action string) string

MetaSchemaURI returns the resource URI for a tool/action schema.

func MetaToolDescriptionPrefix ¶

func MetaToolDescriptionPrefix(toolName string, routes ActionMap) string

MetaToolDescriptionPrefix builds a fixed-format header that should be prepended to a meta-tool's user-supplied description. The header gives LLMs a literal JSON usage example based on a representative action and points at the gitlab://tools resource for per-action params schemas. Returns an empty string when routes is empty so callers degrade gracefully rather than emit a malformed header.

func MetaToolOutputSchema ¶

func MetaToolOutputSchema() map[string]any

MetaToolOutputSchema returns the shared action-dispatch output schema used by meta-tools.

func MetaToolSchema ¶

func MetaToolSchema(routes ActionMap) map[string]any

MetaToolSchema builds a JSON Schema for a meta-tool with the action field constrained to an enum of valid action names extracted from the routes map. Setting this as Tool.InputSchema ensures the LLM sees the exact list of valid actions in the schema, enabling first-try action selection.

The strategy used (opaque, compact, full) is read from the package-level mode set via SetMetaParamSchemaMode. Default is opaque. Callers that always want the opaque envelope regardless of global configuration should invoke BuildMetaToolSchema directly.

The opaque envelope is small and is compiled and cached by name downstream (see CompileToolSchemas). The compact and full envelopes embed every action's params schema and are served as maps, so they are shared as maps, one per distinct routes map (see [metaEnvelopeFor]).

func MustIndividualToolFromSpecs ¶

func MustIndividualToolFromSpecs(specs []ActionSpec, individualName string, opts IndividualToolProjectionOptions) *mcp.Tool

MustIndividualToolFromSpecs projects an individual tool or panics on invalid registration metadata. Use it from catalog-backed startup paths where a missing spec is a programming error.

func NodesAnswered ¶ added in v3.3.0

func NodesAnswered[N, I any](nodes []*N, convert func(N) I) (items []I, nulled int)

NodesAnswered converts the nodes of a connection page in order, leaving out each node GitLab answered null, and returns how many it left out for GraphQLPartialPage to account for (issue 1298). A connection decodes its nodes as pointers for this: decoded as values, a null node read as an item of zero values. No node at all is an empty page, never a nil one.

func NormalizeActionAlias ¶

func NormalizeActionAlias(action string, routes ActionMap) string

NormalizeActionAlias returns the action a historical spelling stands for on the meta-tool the call was sent to, and the spelling itself when the tool claims none.

The aliases are the ones the group's own routes carry (ActionRoute.CompatibilityAliases), projected by the catalog from each action's compatibility policy, which is `internal/tools/actioncompat` and so the one table the dynamic surface resolves against too. There used to be a second table in this file, keyed by legacy spelling and valued by canonical ID; a route map is keyed by bare action names, so every dotted value in it could never be found and about ninety of its ninety-three entries were unreachable. `milestone.get` was in that table and resolved on no surface.

An action the tool routes is returned as it is. An alias is another spelling of one action, and a name the tool already routes is an action of its own: rewriting it runs a different handler than the one the caller named. That is what group_board_list did on a licensed instance, where epic_board_list also exists on gitlab_group and the alias turned a request for the group's issue boards into its epic boards.

An alias two of the group's own actions claim is left alone rather than resolved to whichever the map iteration reached first. The catalog refuses such a group, so this only guards a route map assembled by hand.

func NormalizeActionAliasForParams ¶

func NormalizeActionAliasForParams(toolName, action string, params map[string]any, routes ActionMap) string

NormalizeActionAliasForParams returns the canonical action name for aliases that depend on the submitted parameter shape.

func NormalizeParamAliasesForSchema ¶

func NormalizeParamAliasesForSchema(params, schema map[string]any) map[string]any

NormalizeParamAliasesForSchema applies the same compatibility aliases used by UnmarshalParams, driven by a JSON Schema properties map instead of a Go struct type. The dynamic surface normalises with it before dispatch, and FinishToolResult, through embedParams, expands the embedded resource URI from its output, so both see the parameters as the handler's UnmarshalParams saw them.

func NormalizeResultMarkdown ¶ added in v3.1.0

func NormalizeResultMarkdown(md string) string

NormalizeResultMarkdown is the one normalization every rendered response passes through on its way into a content block: trailing spaces and tabs dropped from each line, and control bytes dropped everywhere, since a formatter that writes a GitLab field straight into its builder would otherwise deliver an escape sequence to whatever prints the text. It is in one place so the constructor a formatter happens to be registered through cannot change the rendering. See StripControlBytes.

func NormalizeText ¶

func NormalizeText(s string) string

NormalizeText replaces literal escape sequences with real characters. MCP clients may send text with literal backslash-n instead of real newlines when the JSON transport double-escapes the input.

Replacement order matters to avoid cascading conversions:

1. `\\` -> `\` (double-escaped backslash first, so `\\n` becomes `\` + literal n, not a newline)
2. `\r\n` -> `\n` (CRLF before individual CR/LF to avoid double-replacement)
3. `\r` -> `\n` (standalone carriage return)
4. `\n` -> newline (the most common case)
5. `\t` -> tab

func NotFoundResult ¶

func NotFoundResult(resource, identifier string, hints ...string) *mcp.CallToolResult

NotFoundResult creates an informational MCP tool result for resources that do not exist or are not accessible. Instead of returning a Go error (which would be logged as ERROR and produce an opaque error message for the LLM), this returns a card with actionable next steps.

The result has IsError=true to signal the tool could not fulfill the request, but the content is rich and helpful: the LLM can act on the suggestions. It is annotated for a detail, since it answers a get.

Both halves of the sentence are contained here, each by the escaper its slot takes: the identifier because it is text the caller typed and a get handler echoes it as it arrived, and the label because it is not always the constant this once claimed it was. Two packages read it off the result instead, and they disagreed about whose job the escaping was: badges escaped it at its own call site and orbit passed it through raw, which is the shape a rule stated in a comment rather than in code always ends up in. The heading takes the same label through the card writer, which applies the heading escaper.

Use this in register.go handler closures when IsHTTPStatus(err, 404) is true for "get" operations. Pass nil error back to the SDK so the call is logged at INFO level instead of ERROR.

func NoteIDFromGID ¶ added in v3.3.0

func NoteIDFromGID(gid string) (id int64, resourceEvent bool)

NoteIDFromGID reads a note's numeric ID out of the global ID GitLab answered it with, and reports whether the note is one GitLab synthesizes from a resource event: a label, state, milestone, iteration or weight change GitLab's NoteType answers with a global ID ending in the hexadecimal discussion ID (gid://gitlab/WeightNote/0f3c...), which carries no number. Such a note has ID 0 and no note action can address it; a value that is not a GitLab global ID at all is neither a number nor an event.

func NullWhenZero ¶ added in v3.3.0

func NullWhenZero[T comparable](value *T, key string, edit *BodyEdit) *T

NullWhenZero reads one optional update field that GitLab clears only with null, for an option struct whose pointer is tagged omitempty and so cannot carry one. A field left out (nil) returns nil and edits nothing. A field given its zero value, "" for a text or 0 for an ID reference, which is how a caller asks to clear it, records key as null in edit and returns nil, so the option struct leaves the key to the edit. Any other value is returned as given, for the option struct to send.

func OpenAndValidateFile ¶

func OpenAndValidateFile(path string, maxSize int64) (*os.File, os.FileInfo, error)

OpenAndValidateFile opens a caller-supplied local file for reading after confining it to the allowed upload directories, resolving it through every symlink on the way, and validating that what the resolved path names is a regular file of at most maxSize bytes. Returns the open file handle and its FileInfo.

The containment is the point: file_path names a path on the machine the server runs on, and the caller — a model following an instruction that may have come from an issue description or a job log — is not the person whose files these are. See CanonicalLocalFilePath for the roots.

func OpenFileOrBase64Source ¶

func OpenFileOrBase64Source(op, filePath, contentBase64 string) (reader io.Reader, size int64, cleanup func(), err error)

OpenFileOrBase64Source resolves the mutually-exclusive file_path / content_base64 upload input pair into a streaming reader plus the source size and a cleanup func the caller must defer. file_path is opened and validated against the configured upload size limit and streamed without buffering; content_base64 is decoded in memory. All errors are prefixed with op, matching the per-tool error convention.

func PaginationRequestOption ¶ added in v3.1.0

func PaginationRequestOption(page PaginationInput) gl.RequestOptionFunc

PaginationRequestOption carries a caller's page and per_page to a client-go method that takes no options struct to put them in. client-go models several of GitLab's paginated lists that way (a user's GPG keys and emails, system hooks, project aliases, a commit's merge requests), and without this such a method can only ever ask for GitLab's first page.

A value the caller left at zero is not sent, so GitLab applies its own default, exactly as ApplyListOptions leaves a zero out of a gl.ListOptions. The option runs after client-go has encoded the request's own query, so it adds to that query rather than replacing it.

func ParamText ¶ added in v3.1.0

func ParamText(value any) string

ParamText renders a tool argument's value the way the caller wrote it, for the identifier a not-found result names. A route wrapper reads the arguments as they were decoded, before anything coerced them, so a JSON number arrives as a float64, and %v prints one of a million or more in exponent form: a package_id of 31234567 was named "3.1234567e+07" on the dynamic, meta and individual surfaces alike. A whole number is printed as the integer it is, and anything else as fmt prints it.

It renders a value and never looks up a name: which key the value is read from is ActionRoute.WrapNotFound's concern, which hands its builder the arguments with the documented aliases already resolved.

func ParameterGuidanceIdentity ¶

func ParameterGuidanceIdentity(guidance map[string]ParameterGuidance) string

ParameterGuidanceIdentity names a guidance map by its content, for a transform key whose output depends on the guidance as well as on the schema. Nil and empty maps name the same thing, since a transform treats them alike.

By content and not by address, which was the other way to close the same hole. DeriveSchema memoizes on the identity of the input schema, and every typed route's input schema is shared, so a route from a catalog nobody retained still writes a memo entry that lives for the process. An address in that key would be the address of a guidance map that does not: once the catalog is collected the allocator may hand the address out again, and the next map at it would be served the previous route's guidance. Pinning the guidance of every catalog marked shared would close it for the routes somebody remembered to pin and leave the rest keyed on a transient address; a digest cannot be forgotten, holds nothing alive, and lets two routes that spell the same guidance share one derivation.

The cost is a hash of a few short strings per lookup, against the schema clone the memo saves.

func ParseDateField ¶ added in v3.3.0

func ParseDateField(field, value string) (*gl.ISOTime, error)

ParseDateField reads one date-only input, naming the field it came from when the value does not parse.

An RFC 3339 value is read for the calendar date it is written in, not the date it falls on in UTC: an expiry of 2026-12-31T23:00:00-05:00 names the last day of 2026, and moving it to the first of 2027 would grant a day the caller did not ask for. That is the case issue 1308 found dropped outright, for an SSH key and an invitation that then never expired.

func ParseDateFieldString ¶ added in v3.3.0

func ParseDateFieldString(field, value string) (*string, error)

ParseDateFieldString reads one date-only input on the terms of ParseDateField and returns it as YYYY-MM-DD, for the client-go options that carry a date as a plain string, the member expiries among them. Such a field used to forward whatever the caller wrote, so a value GitLab could not read was sent and refused only after the request, if at all.

func ParseDateInputs ¶ added in v3.3.0

func ParseDateInputs(inputs ...DateInput) error

ParseDateInputs parses each date-only input into its destination, on the terms of ParseTimeInputs.

func ParseGID ¶

func ParseGID(gid string) (typeName string, id int64, err error)

ParseGID extracts the type name and numeric ID from a GitLab Global ID. It returns an error if the format is invalid.

ParseGID("gid://gitlab/Vulnerability/42") → ("Vulnerability", 42, nil)

func ParseMetaSchemaURI ¶

func ParseMetaSchemaURI(uri string) (tool, action string)

ParseMetaSchemaURI extracts the tool and action segments from a schema URI.

func ParseTimeField ¶ added in v3.3.0

func ParseTimeField(field, value string) (*time.Time, error)

ParseTimeField reads one timestamp input, naming the field it came from when the value does not parse.

It replaces a parser that answered nil for a value it could not read, which every one of its 84 callers took for an absent input: a list went out with no date filter and answered more than was asked, and a note asked to be backdated was dated now, each reported as a success (issue 1308). A value that is not a timestamp is the caller's mistake, and only the caller can correct it, so it is refused.

func ParseTimeInputs ¶ added in v3.3.0

func ParseTimeInputs(inputs ...TimeInput) error

ParseTimeInputs parses each input into its destination, leaving the destination of an empty one alone, and refuses the call on the first value that does not parse, before any later one is read.

func PartialPageHint ¶ added in v3.3.0

func PartialPageHint(account string) string

PartialPageHint is the next step a list card adds when GitLab answered its page in part, naming the account GraphQLPartialPage gave, and empty for a page answered whole. The account carries GitLab's own messages, so it is escaped as the single-line list value it becomes.

func PathBelowInstanceWeb ¶ added in v3.3.0

func PathBelowInstanceWeb(apiBase *url.URL, remote string) (string, bool)

PathBelowInstanceWeb reports the path of remote below the instance's web URL, without the leading slash, when remote is an http or https URL on the instance's scheme, host and port whose path lies under the instance's relative URL root; ok is false for anything else, the root itself included.

It is the rule GitLab's own SubmoduleHelper applies with Gitlab.config.gitlab.url: a prefix match on the web URL, relative root included. It stops at http and https because an SSH clone URL never carries the relative root (GitLab builds it from gitlab_shell.ssh_path_prefix), so stripping the root from one would mangle a top-level group that happens to share the root's name. The host is compared without regard to case and a port left out is the scheme's default, which is how a browser or git reads the two.

func PipelineInputsSchema ¶

func PipelineInputsSchema[T any](property string) map[string]any

PipelineInputsSchema builds the JSON Schema for the typed input T and constrains the named map property's values to exactly the shapes BuildPipelineInputs accepts (string, number, boolean, array of strings). The generic map[string]any field alone would advertise additionalProperties:true, promising value shapes the converter rejects.

func PipelineStatusEmoji ¶

func PipelineStatusEmoji(status string) string

PipelineStatusEmoji returns the Markdown emoji for a pipeline status.

func PlainPath ¶ added in v3.3.0

func PlainPath(value string) string

PlainPath returns a repository path as GitLab names it: value decoded once when it carries a URL-encoded "/" (DecodeEncodedPathIdentifier), and value unchanged otherwise. client-go escapes a path segment itself, so a path the caller encoded and the handler passed through reached GitLab escaped twice.

func PopulateHints ¶

func PopulateHints(result *mcp.CallToolResult, setter HintSetter)

PopulateHints extracts next-step hints from the Markdown content of a CallToolResult and sets them on the output struct. It is a no-op when result is nil, contains no TextContent, or has no hints section.

func ProgressReportInterval ¶

func ProgressReportInterval(total int64) int64

ProgressReportInterval returns the byte interval between progress reports. It is the smaller of 1 MB or 5% of total, with a minimum of 64 KB.

func RFC3339 ¶ added in v3.1.0

func RFC3339(t time.Time) string

RFC3339 renders t in the wire form, RFC 3339 in UTC, or "" for a zero time.

func RFC3339Ptr ¶ added in v3.1.0

func RFC3339Ptr(t *time.Time) string

RFC3339Ptr renders an optional time in the wire form, or "" when nil.

func ReadDownload ¶ added in v3.3.0

func ReadDownload(op string, r io.Reader, hint string) ([]byte, error)

ReadDownload reads a download's body and returns it when it holds at most MaxDownloadBytes, reading one byte past the ceiling and no more to tell. A longer body is refused with hint, the way out the action names (usually the GitLab route to download from directly); so is a read a response ceiling stopped (IsDownloadTooLarge), and any other failed read is reported as one.

func ReadFileOrBase64 ¶

func ReadFileOrBase64(op, filePath, contentBase64 string) (*bytes.Reader, error)

ReadFileOrBase64 resolves the mutually-exclusive file_path / content_base64 upload input pair into an in-memory bytes.Reader, for endpoints that need a seekable or length-aware body. All errors are prefixed with op.

func RedactURL ¶ added in v3.1.0

func RedactURL(u *url.URL) string

RedactURL renders u with the three parts a secret can hide in removed: the userinfo, the query and the fragment. What survives is the scheme, the host and the path, which is what identifies the destination.

A URL reaches a model through this server whenever a tool reports where it is talking to, and each of the three dropped parts is somewhere a credential is routinely written: a proxy login in the userinfo, a signed token in the query, a fragment carried over from a browser. None of them identifies the destination, so none of them is worth the risk of echoing.

The path survives because for an instance URL it names the installation (a GitLab served under a subpath) rather than the caller, and because client-go builds its own error text from the same three parts, which leaves the two agreeing instead of this being the one place that says more. Use RedactURLToOrigin for a destination whose path is itself the secret.

func RedactURLToOrigin ¶ added in v3.1.0

func RedactURLToOrigin(raw string) string

RedactURLToOrigin parses raw and renders its origin alone: the scheme and the host. It drops what RedactURL drops and the path with it, replacing a path, query or fragment that was there with "/..." so a reader can see that something was withheld.

The path goes because for a webhook, an integration endpoint or any other callback URL the path is where the secret lives: a Slack or Teams hook is a public host with an unguessable path, and truncating such a URL to a fixed number of characters leaks the front of it, userinfo included. The host is what an auditor reads these values for, and the host is all that is left.

Text that does not parse as a URL, or that names no scheme and host, is reported as RedactedPlaceholder rather than echoed: a value that is not a URL is a value nothing here has judged.

func RegisterMarkdown ¶

func RegisterMarkdown[T any](fn func(T) string)

RegisterMarkdown registers a Markdown string formatter for type T. Subsequent calls to MarkdownForResult with a value of type T, or a pointer to one, will invoke fn and wrap the returned string in a mcp.CallToolResult annotated for the assistant.

func RegisterMarkdownAnnotated ¶ added in v3.1.0

func RegisterMarkdownAnnotated[T any](fn func(T) string, ann *mcp.Annotations)

RegisterMarkdownAnnotated registers a Markdown string formatter for type T whose results carry ann, one of the ContentList, ContentDetail and ContentMutate presets; nil means ContentAssistant. The dispatchers override it with the annotation the action's declared content kind resolves to, so a formatter reached through the catalog is annotated by the spec and a formatter reached any other way by this.

A second registration for a type is refused and recorded: the first one stays, since a registration that silently replaced another is how one output type came to render another action's heading. An interface type is refused and recorded too, because its registration lands under a key no concrete value ever looks up.

func RegisterMarkdownPair ¶

func RegisterMarkdownPair[A, B any](first func(A) string, second func(B) string)

RegisterMarkdownPair registers two Markdown string formatters.

func RegisterMarkdownResult ¶

func RegisterMarkdownResult[T any](fn func(T) *mcp.CallToolResult)

RegisterMarkdownResult registers a result formatter for type T. Use this for types that need custom mcp.CallToolResult construction (e.g. uploads with image content). A second registration for a type, or a registration for an interface type, is refused and recorded on the same terms as RegisterMarkdownAnnotated.

func RegisterMarkdownTriple ¶

func RegisterMarkdownTriple[A, B, C any](first func(A) string, second func(B) string, third func(C) string)

RegisterMarkdownTriple registers three Markdown string formatters.

func RegisterSurfaceToolFromSpec ¶

func RegisterSurfaceToolFromSpec(server *mcp.Server, spec ActionSpec, opts SurfaceToolRegisterOptions)

RegisterSurfaceToolFromSpec registers one visible MCP tool by projecting an ActionSpec and executing its route handler directly.

func RegisteredMarkdownFormatterName ¶ added in v3.1.0

func RegisteredMarkdownFormatterName(t reflect.Type) string

RegisteredMarkdownFormatterName returns the name of the formatter registered for t, the served one where two were registered, or "" when none is.

func RegisteredMarkdownTypeNames ¶

func RegisteredMarkdownTypeNames() []string

RegisteredMarkdownTypeNames returns the type names of all registered Markdown formatters (both string and result variants). Used by validation tests to verify sub-packages self-register their formatters.

func RegisteredMarkdownTypes ¶ added in v3.1.0

func RegisteredMarkdownTypes() []reflect.Type

RegisteredMarkdownTypes returns every type a Markdown formatter is registered for, string and result variants alike, sorted by name so a scan over them is deterministic. It is the seam the runtime structural gate drives: a fixture can be built for a type where only a name could not.

func RequestFromContext ¶

func RequestFromContext(ctx context.Context) *mcp.CallToolRequest

RequestFromContext extracts the MCP request from a context, or nil if absent.

func RequireProjectItem ¶ added in v3.3.0

func RequireProjectItem(ctx context.Context, operation string, projectID StringOrInt, field string, id int64) error

RequireProjectItem refuses, under operation, what a handler acting on one item of a project is handed when it names none: a context that has already ended, no project_id, or no positive id under the parameter field names. It sends nothing. The issue and snippet discussion handlers each start with these three checks, in this order and in these words.

func ResolveNextSteps ¶ added in v3.3.0

func ResolveNextSteps(text string, resolve ActionCallResolver) string

ResolveNextSteps rewrites by resolve every canonical ID the guidance section of text names, leaving an ID resolve does not answer as it was.

Only the section the server wrote is rewritten, the one ExtractHints reads. A result carries GitLab's bytes as well, a repository file, an issue body, a job log, and a call spelled in one of them is that content: rewriting it would hand the caller text that is not what GitLab holds.

func ResolveProjectWebURLs ¶

func ResolveProjectWebURLs(ctx context.Context, projects gl.ProjectsServiceInterface, projectIDs []int64) map[int64]string

ResolveProjectWebURLs fetches the web URL for each unique project ID. Failures are silently ignored — missing URLs simply produce no links.

func ResourceTemplateVariables ¶

func ResourceTemplateVariables(template string) ([]string, error)

ResourceTemplateVariables returns the names of the {variables} in a URI template, in order of appearance, without the RFC 6570 "+" reserved-expansion prefix. A brace that never closes, or a pair with nothing between them, is an error rather than the end of the scan: ExpandResourceURI answers such a template by embedding nothing, and a declaration that validation had let through would fail that quietly on every call.

func ReviewerFilter ¶ added in v3.3.0

func ReviewerFilter(field string, value StringOrInt) (*gl.ReviewerIDValue, error)

ReviewerFilter converts a reviewer_id filter into the value client-go's merge request list options send, on the terms of [parseUserIDFilter]. It returns nil for a filter left out.

func RichContentHint ¶

func RichContentHint(features, webURL string) string

RichContentHint returns an informational note directing users to the GitLab web URL for full rendering when non-portable GFM features are detected. Returns an empty string when features or webURL is empty.

func SafeModePreviewResult ¶ added in v3.1.0

func SafeModePreviewResult(p SafeModePreview) *mcp.CallToolResult

SafeModePreviewResult renders a preview as the error result the individual surface answers an intercepted call with: the tool did not run, so it produced none of the output its schema describes, and the specification is unconditional about what a declared schema obliges.

func SanitizeError ¶

func SanitizeError(err error) error

SanitizeError returns err with a rendering that reflects no upstream response body, leaving the chain intact for errors.As and errors.Is.

The four wrapping helpers in this file already do this to what they wrap, but a handler is free to wrap a client-go error itself with %w, and a good many do, so for those actions nothing between the handler and the SDK ever bounded the body. Calling this at the dispatchers, where every action's error passes on its way to the model and to the "tool call failed" log line, makes the wrapping helpers defense in depth rather than the only gate.

The same holds for what a fine-grained refusal means, which the wrapping helpers say through ClassifyError: an error that carries one and reaches a dispatcher without that description, as a GraphQL refusal a handler returns straight from GraphQLTopLevelError does, gets it here.

func SchemaForRoute ¶

func SchemaForRoute[R any]() map[string]any

SchemaForRoute returns the cached output schema for type R. Exported for use by gen_llms and audit tools.

func SchemaPropertyTakes ¶ added in v3.3.0

func SchemaPropertyTakes(name string, value, property any) bool

SchemaPropertyTakes reports whether a parameter whose schema is property takes value sent under name: the property declares no type, which leaves nothing to judge it by; or it declares the value's JSON type; or the dispatchers coerce the value into a type it declares, as they do a number written as text into an integer or a number and a whole number into the string of an ID parameter.

The dynamic surface asks it before offering an unknown parameter's nearest valid name, so that following the advice never moves a value to where the schema refuses it: job_id is three edits from job, and job takes a job's name where job_id carried its number (issue 1333).

func SchemaShared ¶

func SchemaShared(schema any) bool

SchemaShared reports whether schema was registered with ShareSchema, or produced by DeriveSchema from a registered schema.

func SetActionTimeout ¶

func SetActionTimeout(d time.Duration)

SetActionTimeout sets the deadline every action runs under. Zero or a negative value disables it.

func SetLocalFilesystemAccess ¶

func SetLocalFilesystemAccess(allowed bool)

SetLocalFilesystemAccess overrides the transport inference for this process: pass false to refuse every caller-supplied local path, true to allow the allow-listed roots. Call it before any tool handler runs.

The default is inferred from the process arguments rather than configured, so a deployment that never heard of this policy still gets the right answer: an operator who forgets a flag would otherwise be the one running the exposed server. An explicit call always wins over the inference.

func SetMetaParamSchemaMode ¶

func SetMetaParamSchemaMode(mode string)

SetMetaParamSchemaMode selects the meta-tool input schema strategy used by MetaToolSchema. Accepts "opaque" (default), "compact", or "full". Any other value is coerced to opaque so that misconfiguration cannot break the tools/list payload. Must be called before meta-tools are registered; later calls only affect schemas built after the call returns.

func SetMetaParamSchemaModeScoped ¶

func SetMetaParamSchemaModeScoped(mode string) func()

SetMetaParamSchemaModeScoped selects the meta-tool input schema strategy and returns a restore function for tests that temporarily override the global mode.

func SetUploadConfig ¶

func SetUploadConfig(maxFileSize int64)

SetUploadConfig overrides the default upload thresholds. Call before RegisterAll to propagate values into tool handler closures.

func SeverityBadge ¶ added in v3.1.0

func SeverityBadge(severity string) string

SeverityBadge renders a vulnerability or finding severity as its color glyph and the level in capitals, the one badge the security domains share. A level the table does not know is rendered escaped, since it is a value GitLab sent.

func ShareSchema ¶

func ShareSchema(schema any)

ShareSchema registers a schema as process-lived so that transforms of it are memoized by DeriveSchema. Registering keeps the schema reachable for the rest of the process, which is the point: only a schema that can never be collected has an address that can serve as its identity.

Register what the process builds once and serves from then on: the reflected type schemas, the compiled tool schemas, and the routes of a catalog cached per configuration. Never register a per-server map.

func SharedSchemaIdentity ¶

func SharedSchemaIdentity(schema any) (string, bool)

SharedSchemaIdentity returns a string naming a registered schema's identity, for callers that build a composite cache key out of several schemas. It reports false for a schema that is not shared, because the address of a map that can be collected names nothing durable.

func StripControlBytes ¶

func StripControlBytes(s string) string

StripControlBytes removes the C0 and C1 control ranges and DEL from s, keeping the three controls Markdown actually uses: tab, newline and carriage return.

Everything this package renders is GitLab-authored: an issue title, a file, a job log, a note somebody left on a merge request. None of it is written by the caller, and a good deal of it is written by whoever can open an issue or push a branch, which on a public project is anybody. It reaches the model as text and frequently reaches a person's terminal unchanged, where an escape sequence is not text but an instruction: ESC[2J clears the screen, ESC]0;…BEL renames the window. Nothing downstream filters them, so they are dropped here, at the point the text becomes part of a response.

Dropping rather than escaping is deliberate. A rendered escape would still have to be un-rendered by something to be read, and the sequences that matter carry no information a reader loses by not seeing them: what survives of ESC[2J is "[2J", which says plainly that the content tried something.

This covers the text channel and not structuredContent, and that is a decision rather than an oversight. structuredContent is marshaled by the SDK from the typed value each handler returns, so there is no funnel in this package to apply it at: closing it means either a sweep over every output struct in the 175 handler packages, or a result middleware in the server that walks each value reflectively on the way out. The second is the tempting one and it is the wrong trade. encoding/json already escapes every byte in these ranges, so what reaches a client is the six characters of a \u001b sequence, which no terminal acts on: a viewer would have to parse the JSON and print a string field raw to be affected, and such a client is showing the text channel too, which is sanitized here. Paying a reflective walk of every result for that is not worth it. If the shape of the risk changes, the place to add it is one middleware at the server boundary, not this function.

func StripLogMarkup ¶ added in v3.3.0

func StripLogMarkup(s string) string

StripLogMarkup removes the terminal markup GitLab Runner writes into a CI job log, the ANSI control sequences and the section markers, and leaves the text a person reads. StripControlBytes drops only the ESC byte of a sequence, so a log went out as "[0K[36;1mPreparing" beside "section_start:1791747389:prepare_executor", and the structured channel carried the raw bytes. A lone ESC that starts no sequence is left for StripControlBytes to drop where text becomes Markdown.

func StripMetaToolDescriptionPrefix ¶

func StripMetaToolDescriptionPrefix(description string) string

StripMetaToolDescriptionPrefix removes the generated meta-tool usage header added by MetaToolDescriptionPrefix while preserving standalone descriptions that happen to start with an example.

func SuccessResult ¶

func SuccessResult(markdown string) *mcp.CallToolResult

SuccessResult builds a success mcp.CallToolResult carrying the Markdown as its one text block, annotated for the assistant. Empty Markdown yields nil, which the dispatchers render as JSON through FinishToolResult; it is how a nil action result and a result with no formatter are answered.

func TimestampParam ¶ added in v3.3.0

func TimestampParam(name string, at *time.Time) gl.RequestOptionFunc

TimestampParam returns the request option that sends a timestamp parameter as the instant the caller gave, for a parameter GitLab declares DateTime that a client-go option struct carries as a date (upstream register row 126). Such a field encodes as YYYY-MM-DD, which GitLab reads as midnight UTC: an SSH key asked to expire at 23:00 expired 23 hours early, and a list bounded at 18:00 was bounded at the start of its day.

client-go writes its options into the JSON body of a POST, PUT or PATCH and into the query of any other method, and the option writes the timestamp under name in the same place, in RFC 3339 with the offset it was given in, replacing whatever was there. The caller leaves the option struct's own field unset, so this is the one writer of the parameter. A nil timestamp returns no option, and the request goes out as client-go built it.

func TitleFromName ¶

func TitleFromName(name string) string

TitleFromName generates a human-readable UI title from a snake_case MCP tool name by stripping the "gitlab_" prefix and converting to Title Case.

TitleFromName("gitlab_list_projects") // returns "List Projects"
TitleFromName("my_open_mrs")          // returns "My Open MRs"

func ToolResultAnnotated ¶

func ToolResultAnnotated(md string, ann *mcp.Annotations) *mcp.CallToolResult

ToolResultAnnotated wraps a Markdown string into a CallToolResult with content annotations that guide MCP clients on audience and priority. Pass nil annotations to get the same behavior as ToolResultWithMarkdown.

func ToolResultWithImage ¶

func ToolResultWithImage(md string, ann *mcp.Annotations, imageData []byte, mimeType string) *mcp.CallToolResult

ToolResultWithImage creates a CallToolResult containing both a text description (metadata) and an ImageContent block with the raw image bytes. Multimodal LLMs can "see" the image; text-only LLMs get the metadata. The text block carries ann, or the assistant default, and the image block carries ContentUser: the image is for a person's display, the text for the model's reasoning.

func ToolResultWithMarkdown ¶

func ToolResultWithMarkdown(md string) *mcp.CallToolResult

ToolResultWithMarkdown wraps a Markdown string into a CallToolResult with a single TextContent entry annotated for assistant-only audience. This prevents MCP clients (e.g. VS Code) from displaying raw Markdown inline: the LLM processes it and presents formatted output to the user. The text passes through NormalizeResultMarkdown, as every rendered response does.

func TypeIdentity ¶

func TypeIdentity(rt reflect.Type) string

TypeIdentity names a reflected type unambiguously, package path included, since two packages may declare input types with the same name. It is the form a transform name embeds when the transform depends on a type.

func UnattributedRequestError ¶

func UnattributedRequestError() error

UnattributedRequestError is UnattributedRequestMessage as a JSON-RPC internal error, for the surfaces that answer with an error value rather than a classified string.

Internal rather than invalid-request for the reason the message gives: the request was well formed and this server failed to route it.

func UnattributedRequestErrorFor ¶

func UnattributedRequestErrorFor(ctx context.Context) error

UnattributedRequestErrorFor is UnattributedRequestError for a request that is still live, and the reason it ended for one that is not.

Not every unattributed request is a wiring defect, which is what the message says it is. A POST the client abandoned takes its carrier with it, and the carrier is where the credential is read from, so the binding finds nothing and the handler resolves the credential-less client: a legitimate cause, answered with a sentence asking the caller to report a bug. The tools path never had this problem, because ClassifyError checks cancellation first and that check is what it hits.

Consulting the context is what tells them apart. A cancelled request is over and nobody is reading the answer, so what matters is only that it is not blamed on the wiring in a log an operator does read.

One cause it cannot distinguish, and does not claim to: the pool evicting the entry between the gate resolving it and the gate looking up its state. The request is alive and unattributable, and the honest thing to tell that caller is exactly what the message already says, since retrying rebuilds the entry.

func UnconfirmedWrite ¶ added in v3.3.0

func UnconfirmedWrite(client *gitlabclient.Client, resp *gl.Response, operation, object string, err, wrapped error) error

UnconfirmedWrite returns the error a GraphQL write's handler answers with, given what its client-go call returned: wrapped, the handler's own error, except for a write GitLab ran and answered without the object it returns (WriteAnsweredWithoutObject) on a fine-grained session, which is told the write was probably committed. The decision of which session that is belongs to the client's authority, which only a fine-grained credential's client carries, so a classic token's write is never described as probably committed.

func UnmarshalParams ¶

func UnmarshalParams[T any](params map[string]any) (T, error)

UnmarshalParams re-serializes params map to JSON and deserializes into T. LLMs frequently send numeric values as JSON strings (e.g. "17" instead of 17). When standard unmarshalling fails, this function retries after coercing string values that look like integers or floats into actual numbers.

Unknown keys in params (i.e. fields that do not exist on T) are rejected with an actionable error so that LLMs receive a clear diagnostic when they mistype a parameter name (e.g. "iid" instead of "snippet_id"). This mirrors the JSON Schema lockdown applied to tools/list responses (see LockdownInputSchemas) and the MCP guidance to surface validation errors as recoverable tool results so the model can self-correct. Meta-protocol keys (see [reservedParamKeys]) are stripped before unmarshalling.

func ValidActionsString ¶

func ValidActionsString(routes ActionMap) string

ValidActionsString returns a sorted, comma-separated list of action names.

func ValidateDiffPosition ¶

func ValidateDiffPosition(diffLines []DiffLine, newLine, oldLine int) error

ValidateDiffPosition checks whether a (newLine, oldLine) combination corresponds to a valid commentable position in the parsed diff lines.

Rules enforced (per GitLab API):

• new_line only → line must be an added (+) line
• old_line only → line must be a removed (-) line
• both set → line must be an unchanged context line

Returns nil when the position is valid, or a descriptive error explaining exactly why the position is invalid and what the caller should do instead.

func ValidatePackageFileName ¶

func ValidatePackageFileName(filename string) error

ValidatePackageFileName validates a filename for GitLab generic package upload. Filenames must not be empty, must not contain spaces, and must not start with a tilde or at-sign.

func ValidatePackageName ¶

func ValidatePackageName(name string) error

ValidatePackageName validates a GitLab generic package name against allowed characters. Names must start with a letter or digit and may contain A-Z a-z 0-9 . _ - + ~ / @.

func ValidateRateLimit ¶

func ValidateRateLimit(rps float64, burst int) error

ValidateRateLimit reports whether the given rps/burst pair forms a well-defined limiter configuration. Used by the server entrypoint to fail fast on bad CLI input rather than silently disabling the limiter.

func ValidateRouteBinding ¶

func ValidateRouteBinding(route ActionRoute) error

ValidateRouteBinding reports a route whose handler was replaced without its binder being replaced with it. Such a route serves the replacement on the server it was built for and the constructor's plain handler on every server a shared catalog rebinds it to, which is a defect no test of the domain package can see, since the package tests the route as it built it. The check is exact: the handler in place must be the very closure the binder installed, compared by identity rather than by the code it runs, because the compiler gives an inlined copy of a function literal a closure of its own.

A route with no binder at all passes here, because this compares the two halves against each other and there is nothing to compare. Whether a route is allowed to have no binder is a question about where the route lives, and is answered where that is known: the catalog requires one of every action but the dynamic controllers, which close over a registry rather than a client.

func WithActionDeadline ¶

func WithActionDeadline(ctx context.Context) (context.Context, context.CancelFunc)

WithActionDeadline derives the context an action runs under: the caller's, bounded by the configured deadline when there is one. The cancel function is always safe to call.

Exported for the one model-facing handler that is not a catalog action and so passes through none of the WrapAction functions: the dynamic surface's gitlab_find_action, whose cost is the catalog rather than a GitLab call and which was therefore the only registered tool with no deadline at all.

func WithHints ¶

func WithHints[O any](result *mcp.CallToolResult, out O, err error) (*mcp.CallToolResult, O, error)

WithHints extracts hints from a CallToolResult and populates them on the typed output struct, returning all three handler values in one call. This avoids evaluation-order ambiguity in multi-value return statements.

For value Out types (the common case), &out is used internally to satisfy the HintSetter pointer receiver. For pointer Out types (*T), the pointer itself implements HintSetter. If neither case applies, WithHints is a no-op.

return toolutil.WithHints(toolutil.ToolResultWithMarkdown(md), out, err)

func WithInternalInspection ¶

func WithInternalInspection(ctx context.Context) context.Context

WithInternalInspection marks ctx as belonging to a session the server opens against itself, so what it asks for is not charged to a caller's bucket.

The server lists its own tools several times while it starts: to drop the excluded ones, to learn which survived the read-only and safe-mode passes, to count them and build the gitlab://tools manifest from one listing, and to write the server card. Those requests travel the same receiving middlewares a client's do, so metering tools/list charged them to the deployment's own bucket, and on a server started with --rate-limit-burst=1 the second one was refused and the tool manifest resource failed to build. Pass this to the server's mcp.Server.Connect: the handler context descends from that one, and no header or parameter a caller controls reaches it.

Only the catalog bucket consults the mark, because only listings are asked for this way. A method that reached GitLab would be spending the credential whether the server or a client asked for it, and should still be charged.

func WrapErr ¶

func WrapErr(operation string, err error) error

WrapErr classifies the error, enriches it with a semantic message, and wraps it with the operation name. All tool handlers funnel through here so connectivity and auth problems are reported consistently.

func WrapErrWithHint ¶

func WrapErrWithHint(operation string, err error, hint string) error

WrapErrWithHint works like WrapErrWithMessage but appends an actionable hint that tells the LLM what to do next, after the classification and GitLab's message and before the cause:

"branchDelete: conflict: the resource already exists or there is a state conflict ({message: Cannot delete: protected branch}). Suggestion: use branch.unprotect first, then retry deletion: DELETE https://gitlab.example.com/api/v4/projects/1/repository/branches/main: 409 {message: Cannot delete: protected branch}"

The hint should be a concise suggestion starting with a verb (e.g., "use branch.list to verify the branch name"), and names an action by its canonical ID rather than by a tool name, which only one surface of three registers; cmd/audit_action_ids fails on one.

The hint is left out where it cannot be right: for a request this server never sent or declined to send, and for a refusal of a fine-grained token's grant, whose description already says what is missing.

func WrapErrWithMessage ¶

func WrapErrWithMessage(operation string, err error) error

WrapErrWithMessage works like WrapErr but also includes the specific GitLab error message (from ErrorResponse.Message) when available. The composition is the operation, the classification, GitLab's message in parentheses, and the sanitized cause, which carries the request line, the status and that same message once more:

"fileCreate: bad request: check your input parameters ({message: A file with this name already exists}): POST https://gitlab.example.com/api/v4/projects/1/repository/files/README.md: 400 {message: A file with this name already exists}"

Use WrapErrWithMessage for mutating operations where the specific GitLab error detail helps the LLM understand what went wrong. Use WrapErr for read-only operations where the generic classification suffices.

func WrapErrWithStatusHint ¶

func WrapErrWithStatusHint(operation string, err error, code int, hint string) error

WrapErrWithStatusHint returns WrapErrWithHint(operation, err, hint) when err matches the given HTTP status code, otherwise falls back to WrapErrWithMessage(operation, err). It compresses the common pattern:

if toolutil.IsHTTPStatus(err, 404) {
    return ..., toolutil.WrapErrWithHint(op, err, hint)
}
return ..., toolutil.WrapErrWithMessage(op, err)

into a single call. For handlers that need different hints per status, use a switch over IsHTTPStatus checks; this helper covers the dominant single- status case.

func WrapGFMBody ¶

func WrapGFMBody(body string) string

WrapGFMBody wraps user-generated GFM content in a Markdown blockquote to prevent heading hierarchy conflicts and structural breaks in the formatted output. Empty bodies return an empty string.

The quote is the containment: every line of the body is a line of a quote, so the body cannot add a heading, a list item or a section to the document it sits in. Two things happen before it. Control characters are dropped, and the server's own guidance heading is defused, so a body carrying that heading is shown as the text it is rather than parsed back out as the server's suggestions. See DefuseHintsHeading.

func WriteAnsweredWithoutObject ¶ added in v3.3.0

func WriteAnsweredWithoutObject(resp *gl.Response, err error) bool

WriteAnsweredWithoutObject reports whether err, what a client-go GraphQL write returned with resp, is GitLab having run the write and answered without the object it returns: the object answered null, which client-go reports as its not-found or its empty-response sentinel, or nulled below a non-null position, which it reports as the top-level errors that null writes.

Only an answer GitLab gave with HTTP 200 qualifies. client-go reports a 404 of the GraphQL endpoint itself with the same not-found sentinel, and that request ran nothing; an error with no response is no answer of GitLab's to read at all. Every write this is asked about is one request, so the answer is the write's own and never a lookup's made before it.

func WriteDownloadOutputFile ¶ added in v3.1.0

func WriteDownloadOutputFile(path string, write func(io.Writer) error) (_ int64, err error)

WriteDownloadOutputFile writes a download to the destination a caller named, and only once write has produced all of it. It returns the number of bytes written.

The destination is resolved and confined by [canonicalDownloadOutputPath] before anything is created, so one outside the allowed roots leaves no directory behind either. It is resolved again once its directory exists: the first pass could only vouch for the ancestors that were there at the time, and a symlink planted under a directory this call just made would otherwise decide where the bytes land.

write receives a temporary file in the destination's directory, never the destination. When write returns nil the file is synced, closed and renamed over the destination, and on Unix the directory is synced after the rename; when write returns an error, or the file cannot be put in place, the temporary file is removed and the error returned, so the destination holds exactly what it held before, or is still absent. That is the point of the indirection: a download cut off by an error answer, a dropped connection or a cancelled call used to leave an empty or truncated file at the destination, which the next reader took for the download. The directories made on the way stay, since they are empty and a retry needs them. A process killed outright leaves its temporary file, recognizable by [partialDownloadPrefix], and still never a partial destination.

The rename is also what closes the race [canonicalDownloadOutputPath] cannot: it resolves a symlink already at the destination and confines what that link names, but a local principal who can write in an allowed root could plant one after the check. A rename replaces the directory entry at the destination and does not follow it, so a symlink planted there is replaced rather than written through, on every platform. On Unix the replacement is one rename(2) and atomic. On Windows it is MoveFileEx with MOVEFILE_REPLACE_EXISTING, which Go does not promise to be atomic and which fails while another process holds the destination open without sharing its deletion, a running program for one, or when the destination is marked read-only; it then keeps its previous content and the error says so.

A replaced destination is a new file, and a hard link to the old file keeps the old content. On Unix the new file is readable and writable by the owner alone (created with mode 0600), like every file this creates, whatever the file it replaces allowed; on Windows it takes the access the directory grants to new files, not the old file's own ACL, since Go creates it with no security descriptor of its own and the rename carries the one it inherited. On Unix, whether it may be replaced at all is decided by the directory's permissions, as for any rename, rather than by the old file's own.

func WriteGraphQLPagination ¶ added in v3.1.0

func WriteGraphQLPagination(b *strings.Builder, p GraphQLPaginationOutput, shown int)

WriteGraphQLPagination writes the cursor summary of a GraphQL list after a blank line, the one way a cursor-paginated list ends: the line used to be written four ways across ten packages, one of them with no blank line in front of it, which glued it to the last row of the table.

func WriteHints ¶

func WriteHints(b *strings.Builder, hints ...string)

WriteHints appends the server's guidance section to the Markdown builder: a horizontal rule, the "💡 Next steps" heading, and one bullet per hint. Each hint is a short string describing a related action the model can take (e.g. "Use action 'package.delete' to remove this package"). If no hints are provided, no section is written.

The section separates itself from whatever precedes it. The rule is written after exactly one blank line, whatever the builder ended with. A formatter that stopped mid-line used to get "text\n---", which CommonMark reads as a setext heading: its last line became an H2, the rule vanished into it, and nothing downstream could find the section, so its hints never reached next_steps. Trailing newlines are trimmed first so the blank line is one and not three. On an empty builder the section opens the response, after the one newline [leadingHintsBlock] accepts, rather than at the very first byte, where a "---" reads as YAML front matter to a renderer that looks for it.

Whether or not there are hints, any guidance heading already in the builder is defused first. This is the one place every formatter passes through on its way to a response, the raw file, job trace, snippet and discussion renderers that embed GitLab bytes verbatim included, so doing it here covers them all without each renderer having to remember, and covers the ones added later.

A hint is written as it is given, control bytes aside: it is the server's own sentence, and a GitLab-authored value inside one has to be escaped by the formatter that composed it. The escaping gate follows this write back through every caller, and at L1-08 every hint a domain formatter passes classifies safe; the ten arguments that do not are this package's own plumbing of those hints through an options struct, a renderer constructor, a method receiver or a registered formatter's output type, which the classifier does not follow to the literal the domain wrote. The write is therefore declared below rather than judged, and the declaration retires when the classifier follows those shapes: it fails the gate as stale the moment nothing needs it.

A blank hint is dropped, and a call whose every hint is blank writes no section at all. A hint reaches a formatter as a field of its result as often as it does as a literal, and a result built from a zero value carries those fields empty: written out, each became a bare "- " and the first of them, landing directly under the sentence above it, turned that sentence into a setext heading. Guidance with no text in it is not guidance, so the shape that damages the document is the one that gets dropped rather than each caller having to remember to check.

func WriteHookSecretKeys ¶ added in v3.1.0

func WriteHookSecretKeys(b *strings.Builder, urlVariableKeys, customHeaderKeys []string)

WriteHookSecretKeys writes the tables of a webhook's URL variables and custom headers, keys only, with every value redacted: both are secrets GitLab itself never sends back, and the key is what a reader needs to know which ones are set. Either list may be empty, in which case its table is not written.

func WriteListFooter ¶ added in v3.1.0

func WriteListFooter(b *strings.Builder, p PaginationOutput, linked bool, hints ...string)

WriteListFooter closes a list result: the pagination footer through WritePagination, then the guidance section. When linked is true the table carried a link column and HintPreserveLinks leads the hints, as ListHints arranges; when it is false the hint is dropped even if the caller passed it, since an instruction to keep the links of a table that has none is noise the model has to read past.

func WriteListHeading ¶ added in v3.1.0

func WriteListHeading(b *strings.Builder, title string, shown int, p PaginationOutput)

WriteListHeading writes the H2 a list result opens with, "## Title (N)", and the summary line WriteListSummary adds for a multi-page result.

N is what the response can vouch for: the total GitLab sent when it sent one, the count shown with "more available" when the page has a successor but no total (keyset pagination and search send none), the count shown with its page number on a later page that has no successor and no total, and the count shown otherwise. A heading that printed the page length under a larger total, a zero total above a table of rows, or the rows of a last page as if they were the whole list, was the commonest way a list misled its reader.

func WriteListSummary ¶

func WriteListSummary(b *strings.Builder, shown int, p PaginationOutput)

WriteListSummary appends a brief "Showing N of M results (page X of Y)" line between the heading and the table body. It is a no-op when there is only a single page, because the heading count already conveys everything, and it names no total when GitLab sent none rather than saying "of 0".

func WritePagination ¶

func WritePagination(b *strings.Builder, p PaginationOutput)

WritePagination appends the pagination footer after a blank line, whatever the builder ends with, so the footer opens a paragraph of its own rather than continuing the last table row or list item as a lazy line. A pagination that says nothing (no page, no total, no page size) writes nothing, since "Page 0 of 0 | 0 items total" is an answer GitLab never gave.