mcputil

Documentation

Overview

Package mcputil provides common utilities for MCP (Model Context Protocol) servers. It includes helpers for batch operations, input validation, and result creation.

This package simplifies the creation of MCP servers by providing reusable patterns for:

• Batch operation handling (HandleBatchBuild)
• Input validation (ValidateRequired)
• Standardized result creation (ErrorResult, SuccessResult, SuccessResultWithArtifact)

Index

• func AddValidationError(out *mcptypes.ConfigValidateOutput, field, message string)
• func AddValidationWarning(out *mcptypes.ConfigValidateOutput, message string)
• func AddValidationWarningWithField(out *mcptypes.ConfigValidateOutput, field, message string)
• func ErrorResult(message string) *mcp.CallToolResult
• func ErrorResultWithArtifact(message string, artifact any) (*mcp.CallToolResult, any)
• func FormatBatchResult(operationType string, artifacts []any, errorMsgs []string) (*mcp.CallToolResult, any)
• func HandleBatchBuild[T any](ctx context.Context, specs []T, ...) (artifacts []any, errorMsgs []string)
• func NewValidateOutput() *mcptypes.ConfigValidateOutput
• func SuccessResult(message string) *mcp.CallToolResult
• func SuccessResultWithArtifact(message string, artifact any) (*mcp.CallToolResult, any)
• func ValidateOutputResult(out *mcptypes.ConfigValidateOutput) *mcp.CallToolResult
• func ValidateRequired(fields map[string]string) *mcp.CallToolResult
• func ValidateRequiredWithPrefix(prefix string, fields map[string]string) *mcp.CallToolResult
• type BatchResult

Functions

func AddValidationError

func AddValidationError(out *mcptypes.ConfigValidateOutput, field, message string)

AddValidationError adds a validation error to the output and sets Valid to false. Use this when a configuration field fails validation and the configuration should not be used.

Parameters:

• out: the ConfigValidateOutput to add the error to
• field: the JSON path to the invalid field (e.g., "spec.args[0]")
• message: a human-readable error description

Example usage:

mcputil.AddValidationError(out, "spec.timeout", "must be a positive integer")

func AddValidationWarning

func AddValidationWarning(out *mcptypes.ConfigValidateOutput, message string)

AddValidationWarning adds a validation warning to the output without changing Valid. Use this for non-fatal issues like deprecated configurations or suboptimal settings.

Parameters:

• out: the ConfigValidateOutput to add the warning to
• message: a human-readable warning description

Example usage:

mcputil.AddValidationWarning(out, "deprecated field 'oldName' will be removed in v2.0")

func AddValidationWarningWithField

func AddValidationWarningWithField(out *mcptypes.ConfigValidateOutput, field, message string)

AddValidationWarningWithField adds a validation warning with a field reference. Use this for warnings that relate to a specific configuration field.

Parameters:

• out: the ConfigValidateOutput to add the warning to
• field: the JSON path to the relevant field (e.g., "spec.timeout")
• message: a human-readable warning description

Example usage:

mcputil.AddValidationWarningWithField(out, "spec.oldField", "deprecated, use 'newField' instead")

func ErrorResult

func ErrorResult(message string) *mcp.CallToolResult

ErrorResult creates a standardized MCP error result.

Parameters:

• message: error message to display

Example usage:

return mcputil.ErrorResult(fmt.Sprintf("Build failed: %v", err)), nil, nil

func ErrorResultWithArtifact

func ErrorResultWithArtifact(message string, artifact any) (*mcp.CallToolResult, any)

ErrorResultWithArtifact creates an error result that also returns an artifact. This is useful when you want to return partial data even when an operation fails (e.g., returning a TestReport even when tests fail).

Parameters:

• message: error message to display
• artifact: the artifact to return (typically contains partial or error information)

Returns:

• result: the MCP CallToolResult with IsError set to true
• artifact: the artifact (passed through for MCP handler return)

Example usage:

result, artifact := mcputil.ErrorResultWithArtifact("Tests failed", testReport)
return result, artifact, nil

func FormatBatchResult

func FormatBatchResult(operationType string, artifacts []any, errorMsgs []string) (*mcp.CallToolResult, any)

FormatBatchResult creates an MCP result for batch operations. It returns an error result if there were any failures, otherwise a success result. The artifacts are wrapped in a BatchResult object to comply with MCP client expectations.

Parameters:

• operationType: description of what was built (e.g., "binaries", "containers")
• artifacts: successful artifacts
• errorMsgs: error messages from failed operations

func HandleBatchBuild

func HandleBatchBuild[T any](
	ctx context.Context,
	specs []T,
	handler func(context.Context, T) (*mcp.CallToolResult, any, error),
) (artifacts []any, errorMsgs []string)

HandleBatchBuild is a generic handler for batch build operations. It takes a slice of build specs and a handler function for single builds. The handler should return (result, artifact, error) as per MCP conventions.

Returns:

• artifacts: slice of successfully created artifacts
• errorMsgs: slice of error messages (one per failed spec)

Example usage:

artifacts, errorMsgs := mcputil.HandleBatchBuild(ctx, specs,
    func(ctx context.Context, spec BuildInput) (*mcp.CallToolResult, any, error) {
        return handleBuildTool(ctx, req, spec)
    })

func NewValidateOutput

func NewValidateOutput() *mcptypes.ConfigValidateOutput

NewValidateOutput creates a new ConfigValidateOutput with Valid set to true and empty error/warning slices. This is the starting point for building validation results.

Example usage:

out := mcputil.NewValidateOutput()
if someField == "" {
    mcputil.AddValidationError(out, "spec.someField", "required field is missing")
}
return mcputil.ValidateOutputResult(out), nil, nil

func SuccessResult

func SuccessResult(message string) *mcp.CallToolResult

SuccessResult creates a standardized MCP success result.

Parameters:

• message: success message to display

Example usage:

return mcputil.SuccessResult("Build completed successfully"), nil, nil

func SuccessResultWithArtifact

func SuccessResultWithArtifact(message string, artifact any) (*mcp.CallToolResult, any)

SuccessResultWithArtifact creates a success result that returns an artifact. This is the most common pattern for MCP tool responses.

Parameters:

• message: success message to display
• artifact: the artifact to return (typically forge.Artifact or similar)

Returns:

• result: the MCP CallToolResult
• artifact: the artifact (passed through for MCP handler return)

Example usage:

result, artifact := mcputil.SuccessResultWithArtifact("Built successfully", myArtifact)
return result, artifact, nil

func ValidateOutputResult

func ValidateOutputResult(out *mcptypes.ConfigValidateOutput) *mcp.CallToolResult

ValidateOutputResult converts a ConfigValidateOutput to an MCP CallToolResult. This should be called at the end of validation to produce the final MCP response.

The result is:

• A success result (IsError=false) if Valid is true
• An error result (IsError=true) if Valid is false

The output is serialized as JSON in the result content.

Example usage:

out := mcputil.NewValidateOutput()
// ... perform validation, add errors/warnings ...
return mcputil.ValidateOutputResult(out), out, nil

func ValidateRequired

func ValidateRequired(fields map[string]string) *mcp.CallToolResult

ValidateRequired checks if required fields are present and returns an MCP error result if not. Returns nil if all fields are valid.

Parameters:

• fields: map of field name to field value

Example usage:

if result := mcputil.ValidateRequired(map[string]string{
    "name": input.Name,
    "stage": input.Stage,
}); result != nil {
    return result, nil, nil
}

func ValidateRequiredWithPrefix

func ValidateRequiredWithPrefix(prefix string, fields map[string]string) *mcp.CallToolResult

ValidateRequiredWithPrefix checks required fields and uses a custom error prefix. This allows customizing the error message (e.g., "Build failed:" vs "Test run failed:").

Parameters:

• prefix: error message prefix (e.g., "Build failed", "Test run failed")
• fields: map of field name to field value

Example usage:

if result := mcputil.ValidateRequiredWithPrefix("Build failed", map[string]string{
    "name": input.Name,
    "src": input.Src,
}); result != nil {
    return result, nil, nil
}

Types

type BatchResult

type BatchResult struct {
	Artifacts []any  `json:"artifacts"`
	Summary   string `json:"summary"`
	Count     int    `json:"count"`
}

BatchResult wraps an array of artifacts in an object for MCP structured content. Claude Code's MCP client requires structured content to always be an object, never a bare array.