Documentation
¶
Overview ¶
Package toolkit provides a type-safe fluent builder for registering MCP tools.
New[In, Out](server, name, description, inputSchema, call) infers In/Out from call, so generic type params are rarely written at call sites. The input schema is required (the SDK panics on nil). Chain optional config, then register:
- WithOutputSchema(schema) — when set, the SDK validates structured results.
- WithValidateFunc(f) — runs on decoded input before the call (and before elicitation for writes).
- WithElicitParamsFunc(f) — builds the confirmation prompt for write tools.
- AddRead(tool) — registers a read-only tool (ReadOnly + Idempotent hints); panics if an elicit-params func was set (meaningless for reads).
- AddWrite(tool) — registers a state-mutating tool (Destructive hint) gated by MCP elicitation: the client must support elicitation (else ErrNoElicitation); the call runs only on an accept action (decline -> ErrUserDeclined, cancel -> ErrUserCanceled).
toolkit re-exports the elicit sentinels (ErrUserDeclined, ErrUserCanceled, ErrNoElicitation, ErrUnexpectedElicitAction, ErrElicitationFailed) so callers need not import elicit. The shared handler pipeline (runValidated) wraps any validator/gate/call error with the tool name via %w, so a validate/elicit sentinel raised inside a tool stays matchable after registration.
InputSchema[In]() reflects a schema from a plain Go struct via jsonschema.For, panicking on failure like mcp.AddTool does. Tool is a value type — builder methods return a copy, not a pointer.
Handlers are marshalled as-is (no auto-wrapping), so a handler returning a bare slice or scalar would violate MCP's object-root structuredContent contract. result.go provides envelopes: Items[T]/Value[T] (shapes {"items":…} / {"value":…}) and the WrapItems/WrapValue adapters that consume a (slice|scalar, error) pair directly. Items.MarshalJSON normalizes a nil slice to [] so an array-typed output schema still accepts it.
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
- type ValidateFunc
- type Value
Constants ¶
This section is empty.
Variables ¶
var ( ErrUserDeclined = elicit.ErrUserDeclined ErrUserCanceled = elicit.ErrUserCanceled ErrNoElicitation = elicit.ErrNoElicitation ErrUnexpectedElicitAction = elicit.ErrUnexpectedElicitAction ErrElicitationFailed = elicit.ErrElicitationFailed )
Re-exported so callers can match elicit sentinels without importing elicit.
Functions ¶
func AddReadFunc ¶ added in v0.1.4
func AddReadFunc[In, Out any]( t Tool[In, Out], callFunc mcp.ToolHandlerFor[In, Out], )
AddReadFunc registers a read-only tool running callFunc as-is, unvalidated.
func AddWriteFunc ¶ added in v0.1.4
func AddWriteFunc[In, Out any]( t Tool[In, Out], callFunc mcp.ToolHandlerFor[In, Out], )
AddWriteFunc registers a state-mutating tool running callFunc as-is, ungated.
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]) WithElicitParamsFunc ¶
WithElicitParamsFunc sets the write tool's elicitation prompt builder.
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