Documentation
¶
Overview ¶
Package mcputil contains helpers shared across the MCP tools, resources, and prompts packages: client/project resolution, input validation, log truncation, tool annotation factories, and result builders.
Index ¶
- Constants
- func ClampPerPage(perPage int64) int64
- func Destructive(title string, idempotent bool) *mcp.ToolAnnotations
- func DryRunResult(action string) (*mcp.CallToolResult, any, error)
- func Mutating(title string, idempotent bool) *mcp.ToolAnnotations
- func PlainResult(text string) *mcp.CallToolResult
- func ReadLog(r io.Reader) (string, error)
- func ReadOnly(title string) *mcp.ToolAnnotations
- func RequireEnum(val, name string, allowed ...string) error
- func RequireID(id int64, name string) error
- func RequireString(val, name string) error
- func ResolveClientAndProject(f *cmdutil.Factory, repo string) (*api.Client, string, error)
- func TextResult(v any) (*mcp.CallToolResult, any, error)
- func ToolError(err error) (*mcp.CallToolResult, any, error)
- func ToolErrorf(format string, args ...any) (*mcp.CallToolResult, any, error)
Constants ¶
const ( // MaxPerPage caps the per_page value the server will request from GitLab. // The GitLab API server-side cap is 100; we enforce it here so AI-supplied // values never silently exceed intent. MaxPerPage = int64(100) // MaxLogBytes is the maximum job log size we read into memory at once. MaxLogBytes = int64(1 << 20) // 1 MiB )
Variables ¶
This section is empty.
Functions ¶
func ClampPerPage ¶
ClampPerPage returns perPage clamped to [1, MaxPerPage], defaulting to 30.
func Destructive ¶
func Destructive(title string, idempotent bool) *mcp.ToolAnnotations
Destructive returns annotations for a tool that may delete or otherwise irrevocably change data — clients are expected to confirm before invoking.
func DryRunResult ¶
func DryRunResult(action string) (*mcp.CallToolResult, any, error)
DryRunResult builds a successful CallToolResult describing the action that would have been taken. Use from destructive tools when in.DryRun is true. Pattern: `if in.DryRun { return dryRun(fmt.Sprintf("delete branch %q", name)) }`.
func Mutating ¶
func Mutating(title string, idempotent bool) *mcp.ToolAnnotations
Mutating returns annotations for a tool that creates or updates state but does not destroy data. Set idempotent=true when repeated calls with the same arguments produce no further effect (e.g. resolve, approve).
func PlainResult ¶
func PlainResult(text string) *mcp.CallToolResult
PlainResult wraps a plain string in a CallToolResult.
func ReadLog ¶
ReadLog reads at most MaxLogBytes from r and appends a truncation notice if the input exceeded the limit.
func ReadOnly ¶
func ReadOnly(title string) *mcp.ToolAnnotations
ReadOnly returns annotations for a tool that does not modify state.
func RequireEnum ¶
RequireEnum returns an error when val is non-empty but not one of allowed. Empty values pass through so callers can keep enum fields optional.
func RequireString ¶
RequireString validates that a string field is non-empty after trimming.
func ResolveClientAndProject ¶
ResolveClientAndProject returns an authenticated API client and the OWNER/REPO path. repo may be empty (falls back to the factory's git remote), "OWNER/REPO", or "HOST/OWNER/REPO".
func TextResult ¶
func TextResult(v any) (*mcp.CallToolResult, any, error)
TextResult marshals v as compact JSON and wraps it in a CallToolResult.
The MCP spec (2025-06-18) requires CallToolResult.structuredContent to be a JSON *object*, not an array or scalar. Many GitLab endpoints return arrays (mr_list, issue_list, pipeline_jobs, *_list, ...); emitting a top-level array as structuredContent breaks strict clients and gateways — e.g. LiteLLM's pydantic validator rejects it with a dict_type error, which makes the tool unusable end-to-end even though the server responded 200.
So we only attach the structured payload when v marshals to an object. The full data is always present in the text content regardless, so array tools lose nothing — clients read the JSON from the text block as before.
func ToolError ¶
func ToolError(err error) (*mcp.CallToolResult, any, error)
ToolError builds a CallToolResult with IsError=true and the error message as a text content. Use for input-validation and downstream API errors so MCP clients treat them as tool errors rather than protocol errors.
func ToolErrorf ¶
ToolErrorf builds a tool error with a formatted message.
Types ¶
This section is empty.
Source Files