runtime

Documentation

Overview

Package runtime provides helpers imported by code generated by protoc-gen-go-mcp.

These functions handle the boundary between MCP request/response types and proto messages:

• BindProto: unmarshal MCP tool arguments (JSON) into a proto request
• BindParams: populate a proto request from URI template parameters
• BindPromptArgs: populate a proto request from prompt argument values
• ProtoTextResult: marshal a proto response as MCP text content
• ProtoStructuredResult: marshal as MCP structured content
• ProtoSummaryStructuredResult: structured content with rendered summary template
• ProtoResourceResult: marshal as MCP resource content
• ProtoPromptResult: marshal as MCP prompt messages
• RPCError: convert errors (including gRPC status with details) to MCP error results

Keep this package minimal — every dependency here is a transitive dep for all consumers of generated code.

Index

• func BindElicitResult[T any, PT interface{ ... }](content map[string]any) (PT, error)
• func BindParams(params map[string]string, msg proto.Message) error
• func BindPromptArgs(args map[string]any, msg proto.Message) error
• func BindProto(req core.ToolRequest, msg proto.Message) error
• func ProtoPromptResult(msg proto.Message) (core.PromptResult, error)
• func ProtoResourceResult(msg proto.Message, uri, mimeType string) (core.ResourceResult, error)
• func ProtoStructuredResult(msg proto.Message) (core.ToolResult, error)
• func ProtoSummaryStructuredResult(msg proto.Message, summaryTemplate string) (core.ToolResult, error)
• func ProtoTextResult(msg proto.Message) (core.ToolResult, error)
• func RPCError(err error) (core.ToolResult, error)

Functions

func BindElicitResult

func BindElicitResult[T any, PT interface {
	*T
	proto.Message
}](content map[string]any) (PT, error)

BindElicitResult unmarshals an elicitation result content map into a typed proto message. Returns a pointer to the populated message.

Usage in generated code:

approval, err := runtime.BindElicitResult[SummaryApproval](result.Content)
// approval is *SummaryApproval

func BindParams

func BindParams(params map[string]string, msg proto.Message) error

BindParams populates a proto message from URI template parameters. Each key is a field path (dot-separated for nested fields, e.g. "pos.q") and each string value is coerced to the target field type.

func BindPromptArgs

func BindPromptArgs(args map[string]any, msg proto.Message) error

BindPromptArgs populates a proto message from prompt argument values. Prompt arguments arrive as map[string]any (JSON-decoded). Each value is re-marshaled to JSON and the full map is unmarshaled via protojson.

func BindProto

func BindProto(req core.ToolRequest, msg proto.Message) error

BindProto unmarshals MCP tool request arguments into a proto message. Arguments arrive as JSON (from the LLM) and are decoded via protojson.

func ProtoPromptResult

func ProtoPromptResult(msg proto.Message) (core.PromptResult, error)

ProtoPromptResult marshals a proto message to JSON and returns it as a PromptResult with a single assistant text message.

func ProtoResourceResult

func ProtoResourceResult(msg proto.Message, uri, mimeType string) (core.ResourceResult, error)

ProtoResourceResult marshals a proto message and returns it as a ResourceResult with the given URI and MIME type.

For JSON resources (application/json), the message is serialized via protojson. For non-JSON resources (text/html, text/yaml, text/markdown, etc.), the function extracts a raw string from a single "content" field if present. This ensures the MCP resource text contains the actual content, not a JSON wrapper — matching what a hand-written resource handler would return.

func ProtoStructuredResult

func ProtoStructuredResult(msg proto.Message) (core.ToolResult, error)

ProtoStructuredResult marshals a proto message and returns it as a StructuredResult. The text field contains the JSON string; structuredContent contains the parsed object.

func ProtoSummaryStructuredResult

func ProtoSummaryStructuredResult(msg proto.Message, summaryTemplate string) (core.ToolResult, error)

ProtoSummaryStructuredResult marshals a proto message and returns it as a StructuredResult where the text content is a rendered summary template. The template uses {field_name} placeholders interpolated from the response message's JSON representation.

func ProtoTextResult

func ProtoTextResult(msg proto.Message) (core.ToolResult, error)

ProtoTextResult marshals a proto message to JSON and returns it as a TextResult.

func RPCError

func RPCError(err error) (core.ToolResult, error)

RPCError wraps an RPC error as an MCP error result. If the error is a gRPC status error, the status code and any attached details (proto Any messages) are extracted and returned as structured error content so agents can parse and recover programmatically. For non-gRPC errors, falls back to a plain text error result.