toolutil

func AccessLevelDescription ¶

func AccessLevelDescription(level gl.AccessLevelValue) string

AccessLevelDescription maps GitLab access level integers to human-readable labels.

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.

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 corrects pagination metadata when the GitLab API does not return X-Total and X-Total-Pages headers (e.g., the Search API). It infers TotalItems and TotalPages from the actual item count received and the presence of a NextPage indicator.

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.

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

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

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: discriminated oneOf with full per-action params schemas.
• compact: discriminated oneOf 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.

func CanonicalDownloadOutputPath ¶

func CanonicalDownloadOutputPath(path string) (string, error)

CanonicalDownloadOutputPath resolves a caller-supplied destination for a file the server is about to write and returns it canonicalized, provided it lies under the working directory, the OS temporary directory, or a directory listed in GITLAB_MCP_ALLOWED_DOWNLOAD_DIRS. It refuses every path when the server is reached over HTTP.

The destination does not exist yet and neither may its parents, so the deepest existing ancestor is what gets resolved through symlinks; the segments below it cannot be symlinks because they do not exist. A leaf that does exist must be a regular file: a symlink there would redirect the write to whatever it names, which is how an "output path" becomes a way to overwrite an SSH key.

Call it again after creating the parent directories. The second call resolves a parent that now exists, which is what turns the check from a promise about the path into a check on the directory being written to.

An existing regular file is overwritten, deliberately, and there is no caller opt-in to refuse it. The audit that produced the symlink check asked for one, and the trade is not worth taking: an opt-in is a new field on DownloadInput, which is a served input schema, so it lands in the tool snapshots, all three llms artifacts, the token-footprint tables and the per-domain docs. What it buys is bounded by two things that are already true. The destination can only be inside the working directory, the OS temporary directory or a directory the operator allow-listed, so the file at risk is one in the workspace rather than one belonging to the system; and under stdio, which is the only transport where a caller-supplied path is honored at all, whatever is driving this server holds its own filesystem write and can overwrite that same file directly. The opt-in would be one bool plus a regeneration pass if the calculus ever changes, but the residual risk it removes is smaller than the surface it adds.

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

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 CreateDownloadOutputFile ¶

func CreateDownloadOutputFile(path string) (*os.File, error)

CreateDownloadOutputFile creates the destination a download writes to, refusing a symlink at the leaf where the platform can.

CanonicalDownloadOutputPath refuses a destination that is already a symlink, but it refuses a path, and the file is created by a later syscall: a local principal who can write in an allowed root can put a symlink there in between and redirect the write to whatever the server may overwrite. The creation is the only place that race can be closed, so it happens here rather than at the call site.

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

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.

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.

func EmbeddedResourcesEnabled ¶

func EmbeddedResourcesEnabled() bool

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

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. It returns the error message as Markdown content for display.

func ErrorResultMarkdown ¶

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

ErrorResultMarkdown creates an MCP tool error result with Markdown formatting. The result has IsError = true for MCP clients that distinguish error results.

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 is 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 in a heading after being neutralized in a cell.

func EscapeMdLinkDestination ¶

func EscapeMdLinkDestination(url string) string

EscapeMdLinkDestination renders url as the destination of a Markdown link.

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.

Only '<' is escaped. Everything a renderer obeys instead of reading opens with it (a tag, a comment, an autolink), so that is the whole of the containment, and '>' is 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.

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 and the first mutation payload error becomes "op: message".

func ExecGraphQLNoteMutation ¶

func ExecGraphQLNoteMutation[N any](ctx context.Context, gql gl.GraphQLInterface, m GraphQLNoteMutation) (*N, error)

ExecGraphQLNoteMutation runs a work item note mutation and returns the mutated note node decoded as N, applying the shared error conventions described on GraphQLNoteMutation.

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 path-escaped value of the parameter of that name, so a project given as "group/project" lands in the URI as group%2Fproject, which is the form the resource templates accept; {+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 a GitLab ErrorResponse in the error chain. 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.

What survives is flattened onto one line and truncated to 300 characters. 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 (nineteen list formatters do this), or after the body, so it closes it. 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 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) string

FormatCICDVariableDetailMarkdown renders a CI/CD variable with standard update/delete next-step hints shared by project and group variables.

func FormatCICDVariableListMarkdown ¶

func FormatCICDVariableListMarkdown(variables []CICDVariableMarkdown, pagination PaginationOutput, opts CICDVariableListMarkdownOptions) string

FormatCICDVariableListMarkdown renders CI/CD variables as a Markdown table.

func FormatCICDVariableMarkdown ¶

func FormatCICDVariableMarkdown(v CICDVariableMarkdown, opts CICDVariableMarkdownOptions) string

FormatCICDVariableMarkdown renders a single CI/CD variable as a Markdown detail table.

func FormatDiscussionListMarkdown ¶

func FormatDiscussionListMarkdown(discussions []DiscussionMarkdown, opts DiscussionListMarkdownOptions) string

FormatDiscussionListMarkdown renders discussion threads as Markdown.

func FormatDiscussionMarkdown ¶

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

FormatDiscussionMarkdown renders a single discussion thread as Markdown.

func FormatDiscussionNoteMarkdown ¶

func FormatDiscussionNoteMarkdown(note DiscussionNoteMarkdown, hints ...string) string

FormatDiscussionNoteMarkdown renders a single discussion note as Markdown.

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 FormatGraphQLDiscussionListMarkdown ¶

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

FormatGraphQLDiscussionListMarkdown maps GraphQL discussion outputs and renders them with cursor pagination metadata.

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 FormatLabelListMarkdown ¶

func FormatLabelListMarkdown(labels []LabelMarkdown, pagination PaginationOutput, opts LabelMarkdownOptions) string

FormatLabelListMarkdown renders project or group labels as a paginated table.

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 Markdown summary.

func FormatNoteListMarkdown ¶

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

FormatNoteListMarkdown renders a list of GitLab notes as Markdown.

func FormatNoteMarkdown ¶

func FormatNoteMarkdown(note NoteMarkdown, opts NoteMarkdownOptions) string

FormatNoteMarkdown renders a single GitLab note as Markdown.

func FormatPagination ¶

func FormatPagination(p PaginationOutput) string

FormatPagination renders pagination metadata as a compact Markdown line.

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 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 Markdown detail table.

func FormatStorageMoveListMarkdown ¶

func FormatStorageMoveListMarkdown(moves []StorageMoveMarkdown, opts StorageMoveListMarkdownOptions) string

FormatStorageMoveListMarkdown renders repository storage moves as a Markdown table with the domain-specific entity column supplied by the caller.

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.

func FormatTemplateAttributeListMarkdown ¶

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

FormatTemplateAttributeListMarkdown renders a common Key/Name/Attribute template list without changing the JSON schema used by existing template tools.

func FormatTemplateCollectionMarkdown ¶

func FormatTemplateCollectionMarkdown[T any](templates []T, pagination PaginationOutput, convert func(T) TemplateMarkdown, title, emptyMessage string, hints ...string) string

FormatTemplateCollectionMarkdown maps package-specific template outputs and renders them as a shared Markdown list.

func FormatTemplateContentMarkdown ¶

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

FormatTemplateContentMarkdown renders a GitLab template body inside a fenced code block.

func FormatTemplateDetailMarkdown ¶

func FormatTemplateDetailMarkdown(detail TemplateDetailMarkdown) string

FormatTemplateDetailMarkdown renders a shared template detail layout.

func FormatTemplateListMarkdown ¶

func FormatTemplateListMarkdown(templates []TemplateMarkdown, pagination PaginationOutput, opts TemplateListMarkdownOptions) string

FormatTemplateListMarkdown renders GitLab template list entries as Markdown.

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.

func GraphQLMutationError ¶

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

GraphQLMutationError formats mutation payload errors, if any.

func GraphQLTopLevelError ¶

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

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

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 — matches spec.Route.OutputType) or a value of any kind (used by tests). Pointer types are dereferenced to their element type for the registry lookup. 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 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 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 IsHTTPStatus ¶

func IsHTTPStatus(err error, code int) bool

IsHTTPStatus reports whether err wraps a GitLab ErrorResponse with the given HTTP status code. Useful for handling specific API responses like 404 (feature not available on CE) or 403 (insufficient permissions).

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 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 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 ListHints ¶

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

ListHints prepends HintPreserveLinks to list-result next-step hints.

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 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. Returns nil for nil input (caller should handle), returns nil when no formatter is registered for the concrete type.

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 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 MarkdownTableSeparator ¶

func MarkdownTableSeparator(columns int) string

MarkdownTableSeparator returns a standard left-aligned Markdown separator row for the requested number of columns.

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.

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 NormalizeActionAlias ¶

func NormalizeActionAlias(action string, routes ActionMap) string

NormalizeActionAlias returns the canonical action name for common shortened action spellings when the canonical action exists on the target meta-tool.

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. It is used by evaluation code that validates simulated calls.

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 structured Markdown result 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.

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 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 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 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 ParseOptionalTime ¶

func ParseOptionalTime(s string) *time.Time

ParseOptionalTime parses an RFC3339 string and returns a *time.Time. Returns nil if the string is empty or unparseable.

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 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 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 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 will invoke fn and wrap the returned string in a mcp.CallToolResult.

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

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 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 RequestFromContext ¶

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

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

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

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 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 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 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 standard success mcp.CallToolResult with Markdown and the structured output for both human-readable and programmatic consumption. If markdown is empty, the result contains only a structured JSON annotation.

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.

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.

Control characters are dropped here as well as in the helpers that build the Markdown, because this is the last point every rendered response passes through and a formatter that writes a GitLab field straight into its builder would otherwise deliver an escape sequence to whatever prints the text. See StripControlBytes.

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 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 count them, to drop the excluded ones, to learn which survived the read-only and safe-mode passes, to build the gitlab://tools manifest, 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. Example:

"branchDelete: bad request (Cannot delete: protected branch).
 Suggestion: use gitlab_branch_unprotect first, then retry deletion: <original>"

The hint should be a concise suggestion starting with a verb (e.g., "use gitlab_branch_list to verify the branch name").

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. This produces richer errors like:

"fileCreate: bad request (A file with this name already exists): POST .../files: 400"

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 WriteDescription ¶

func WriteDescription(b *strings.Builder, description string)

WriteDescription writes a GitLab-authored description field.

A description is prose somebody typed into GitLab, and the "- **Description**: %s" line it used to be interpolated into puts it at column zero after a list bullet: its second line is no longer part of the item, so an embedded heading is a heading of the response and an embedded bullet is an item of the server's own list. A one-line description keeps the compact form with the cell escaping applied; anything longer becomes a blockquote, which is what the merge request, wiki and release renderers already do.

func WriteEmpty ¶

func WriteEmpty(b *strings.Builder, resource string)

WriteEmpty writes a standardized empty-result message to the builder. The resource parameter should be a clear, specific plural noun (e.g. "merge requests", "pipeline variables", "protected branches").

func WriteHints ¶

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

WriteHints appends a "💡 Next steps" section to the Markdown builder. Each hint is a short string describing a related action the LLM can take (e.g. "Use action 'delete' to remove this package"). If no hints are provided, no section is written.

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 — including the raw file, job trace, snippet and discussion renderers that embed GitLab bytes verbatim — so doing it here covers them all without each renderer having to remember, and covers the ones added later.

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.

func WriteMdURL ¶

func WriteMdURL(b *strings.Builder, url string)

WriteMdURL appends the "- **URL**: ..." line, rendering url as a link whose label and destination are the same address.

It replaces a pair of format constants that read "- **URL**: [%[1]s](%[1]s)" and were used at 31 call sites. One value filling both halves of a link is a shape no argument can be escaped into safely, so each of those call sites hand-wrote a link with nothing in front of it, and the audit flagged every one of them twice. Escaping belongs here, once, rather than in a decision each of 22 packages makes for itself.

func WriteMdURLNewline ¶

func WriteMdURLNewline(b *strings.Builder, url string)

WriteMdURLNewline appends the same line as WriteMdURL, preceded by a blank line, for a formatter that closes a section with it.

func WritePagination ¶

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

WritePagination appends a newline-wrapped pagination summary to the builder.