The highest tagged major version is
Documentation
¶
Overview ¶
Package schema provides schema-builder functions for constructing OpenAI-compatible function-calling (tool) definitions in Go. It builds on the types defined in github.com/v8tix/mcp-toolkit/model.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var JSONSchemaKinds = map[reflect.Kind]string{ reflect.String: "string", reflect.Int: "integer", reflect.Int8: "integer", reflect.Int16: "integer", reflect.Int32: "integer", reflect.Int64: "integer", reflect.Float32: "number", reflect.Float64: "number", reflect.Bool: "boolean", reflect.Slice: "array", reflect.Map: "object", reflect.Struct: "object", }
JSONSchemaKinds maps Go reflect.Kind values to their JSON Schema type strings. Exported so callers (tests, validators, custom schema builders) can reuse the same mapping without duplicating it.
Functions ¶
func FormatToolDefinition ¶
func FormatToolDefinition(name, description string, params model.InputSchema, strict bool) model.ToolDefinition
FormatToolDefinition builds a ToolDefinition from explicit name, description, and parameter schema. When strict is true, additionalProperties is set to false and Strict is enabled — both required by the OpenAI structured-output spec.
Example ¶
package main
import (
"fmt"
"github.com/v8tix/mcp-toolkit/schema"
)
type queryArgs struct {
Query string `json:"query" desc:"Search query."`
Topic string `json:"topic,omitempty" desc:"Category." enum:"general,news,finance"`
Limit *int `json:"limit,omitempty" desc:"Max results."`
}
func main() {
params := schema.NewInputSchemaFromStruct(queryArgs{})
// strict=false for schemas that cannot satisfy OpenAI strict mode requirements.
def := schema.FormatToolDefinition("search_web", "Search the web.", params, false)
fmt.Println(def.Function.Name)
fmt.Println(def.Function.Strict)
}
Output: search_web false
func NewInputSchemaFromStruct ¶
func NewInputSchemaFromStruct(v any) model.InputSchema
NewInputSchemaFromStruct derives an InputSchema from a struct's json, desc, and enum tags using reflection. This makes the struct the single source of truth: adding or removing a field automatically updates the tool definition schema.
Struct tag conventions:
- `json:"name"` → property name (required)
- `json:"name,omitempty"` → optional parameter
- `desc:"..."` → description shown to the model — always provide one
- `enum:"a,b,c"` → restricts a string parameter to the listed values
Required/optional rules (mirrors json serialisation conventions):
- Non-pointer field without omitempty → added to "required"
- Non-pointer field with omitempty → optional (has a default)
- Pointer field → optional (may be absent)
Panics with a descriptive message if v is nil or not a struct / *struct.
Example ¶
package main
import (
"fmt"
"github.com/v8tix/mcp-toolkit/schema"
)
type queryArgs struct {
Query string `json:"query" desc:"Search query."`
Topic string `json:"topic,omitempty" desc:"Category." enum:"general,news,finance"`
Limit *int `json:"limit,omitempty" desc:"Max results."`
}
func main() {
s := schema.NewInputSchemaFromStruct(queryArgs{})
fmt.Println(s.Type)
fmt.Println(s.Properties["query"].Description)
fmt.Println(s.Properties["topic"].Enum)
fmt.Println(s.Required)
}
Output: object Search query. [general news finance] [query]
func NewStrictTool ¶
func NewStrictTool(name, description string, args any) model.ToolDefinition
NewStrictTool is the primary convenience constructor for defining a tool. It combines NewInputSchemaFromStruct and FormatToolDefinition into a single call and always enables strict mode, which is the recommended setting.
args must be a struct (or pointer to struct) whose fields are annotated with json, desc, and enum tags — see NewInputSchemaFromStruct for the full convention.
Example ¶
package main
import (
"fmt"
"github.com/v8tix/mcp-toolkit/schema"
)
type queryArgs struct {
Query string `json:"query" desc:"Search query."`
Topic string `json:"topic,omitempty" desc:"Category." enum:"general,news,finance"`
Limit *int `json:"limit,omitempty" desc:"Max results."`
}
func main() {
def := schema.NewStrictTool("search_web", "Search the web.", queryArgs{})
fmt.Println(def.Type)
fmt.Println(def.Function.Name)
fmt.Println(def.Function.Strict)
}
Output: function search_web true
Types ¶
This section is empty.
Source Files