Documentation
¶
Overview ¶
Package toolkit registers typed MCP tools with a fluent value builder.
AddRead registers a read-only tool. AddWrite registers a write tool that uses MCP elicitation. A gated write validates twice but mutates only after an accepted response. Validators must not have side effects. The gate confirms user intent; it is not an authorization boundary.
WithAnnotations replaces all default hints. ReadOnlyHint must match the tool category, and a read tool must not set DestructiveHint to true. Invalid combinations panic during registration.
AddReadFunc and AddWriteFunc register custom handlers without adding validation or elicitation. Custom handlers can call Tool.Call or Tool.Gate. Bind method values after completing the builder chain because Tool is a value type.
MCP structured results require an object root. Items, Value, WrapItems, and WrapValue provide object envelopes for slice and scalar results.
Index ¶
- Variables
- func AddRead[In, Out any](t Tool[In, Out])
- func AddReadFunc[In, Out any](t Tool[In, Out], callFunc mcp.ToolHandlerFor[In, Out])
- func AddWrite[In, Out any](t Tool[In, Out])
- func AddWriteFunc[In, Out any](t Tool[In, Out], callFunc mcp.ToolHandlerFor[In, Out])
- func InputSchema[In any]() *jsonschema.Schema
- type CallFunc
- type ElicitParamsFunc
- type Items
- type Tool
- func (t Tool[In, Out]) Call(ctx context.Context, _ *mcp.CallToolRequest, in In) (*mcp.CallToolResult, Out, error)
- func (t Tool[In, Out]) Gate(ctx context.Context, req *mcp.CallToolRequest, in In) (*mcp.CallToolResult, Out, error)
- func (t Tool[In, Out]) WithAnnotations(a mcp.ToolAnnotations) Tool[In, Out]
- func (t Tool[In, Out]) WithElicitParamsFunc(f ElicitParamsFunc[In]) Tool[In, Out]
- func (t Tool[In, Out]) WithGateID(id string) Tool[In, Out]
- func (t Tool[In, Out]) WithOutputSchema(schema *jsonschema.Schema) Tool[In, Out]
- func (t Tool[In, Out]) WithValidateFunc(f ValidateFunc[In]) Tool[In, Out]
- type ValidateFunc
- type Value
Constants ¶
This section is empty.
Variables ¶
var ( ErrElicitOnRead = errors.New("elicitation set on a read-only tool") ErrGateIDOnRead = errors.New("gate id set on a read-only tool") ErrDestructiveRead = errors.New( "DestructiveHint true on a read-only tool", ) ErrReadOnlyMismatch = errors.New( "ReadOnlyHint does not match the tool's access " + "(set it true on a read, false on a write)", ) )
Registration errors panic when tool settings conflict with access.
var ( ErrUserDeclined = elicit.ErrUserDeclined ErrUserCanceled = elicit.ErrUserCanceled ErrUnexpectedElicitAction = elicit.ErrUnexpectedElicitAction ErrElicitationFailed = elicit.ErrElicitationFailed )
Elicitation errors are aliases for the elicit package sentinels.
Functions ¶
func AddReadFunc ¶ added in v0.1.4
func AddReadFunc[In, Out any]( t Tool[In, Out], callFunc mcp.ToolHandlerFor[In, Out], )
AddReadFunc registers an unvalidated read-only tool handler.
func AddWriteFunc ¶ added in v0.1.4
func AddWriteFunc[In, Out any]( t Tool[In, Out], callFunc mcp.ToolHandlerFor[In, Out], )
AddWriteFunc registers a write handler without validation or elicitation.
func InputSchema ¶
func InputSchema[In any]() *jsonschema.Schema
InputSchema reflects a JSON Schema from In; panics on reflection failure.
Types ¶
type ElicitParamsFunc ¶
type ElicitParamsFunc[In any] = elicit.ParamsFunc[In]
ElicitParamsFunc builds the elicitation prompt for a write tool.
type Items ¶
type Items[T any] struct { Items []T `json:"items"` }
Items wraps a slice result under the "items" key.
func (Items[T]) MarshalJSON ¶
MarshalJSON normalizes a nil slice to "items":[] rather than null.
type Tool ¶
type Tool[In, Out any] struct { // contains filtered or unexported fields }
Tool is a fluent registration builder, distinct from the SDK's mcp.Tool.
func New ¶
func New[In, Out any]( server *mcp.Server, name, description string, inputSchema *jsonschema.Schema, call CallFunc[In, Out], ) Tool[In, Out]
New starts a tool registration, inferring In/Out from call.
func (Tool[In, Out]) Call ¶ added in v0.8.0
func (t Tool[In, Out]) Call( ctx context.Context, _ *mcp.CallToolRequest, in In, ) (*mcp.CallToolResult, Out, error)
Call validates the input and invokes the tool function.
func (Tool[In, Out]) Gate ¶ added in v0.8.0
func (t Tool[In, Out]) Gate( ctx context.Context, req *mcp.CallToolRequest, in In, ) (*mcp.CallToolResult, Out, error)
Gate requests confirmation, then calls the tool on an accepted retry.
func (Tool[In, Out]) WithAnnotations ¶ added in v0.8.0
func (t Tool[In, Out]) WithAnnotations( a mcp.ToolAnnotations, ) Tool[In, Out]
WithAnnotations replaces the default hints and requires matching access.
func (Tool[In, Out]) WithElicitParamsFunc ¶
WithElicitParamsFunc sets the write tool's elicitation prompt builder.
func (Tool[In, Out]) WithGateID ¶ added in v0.8.0
WithGateID sets the confirmation key and panics when used with AddRead.
func (Tool[In, Out]) WithOutputSchema ¶
func (t Tool[In, Out]) WithOutputSchema( schema *jsonschema.Schema, ) Tool[In, Out]
WithOutputSchema sets the optional output schema the SDK validates against.
func (Tool[In, Out]) WithValidateFunc ¶
WithValidateFunc sets a validator run on decoded input before the call.
type ValidateFunc ¶
ValidateFunc validates decoded input before the call.
Source Files