Documentation
¶
Overview ¶
Package openapi assembles per-tool JSON Schemas for MCP tools from a dereferenced OpenAPI document.
The input is the JSON of an OpenAPI 3.1 document whose Schema Objects are already JSON Schema 2020-12 (except OpenAPI 3.0's `nullable: true`, which Parse normalizes to a null-permitting type) and is fully dereferenced: every "#/components/schemas/X" reference inlined while components.schemas is retained for name->schema lookups. With no "$ref" in the document, every assembled schema is self-contained — no "$defs" attachment and nothing for the MCP SDK's JSON Schema resolver to chase.
Parse unmarshals the document once into typed jsonschema.Schema values; the Schemas methods then compose self-contained schemas. They expose an operation's parameters (ParamsSchema/ParamSchema, optionally a named subset), its application/json request body (BodySchema), a named component (Ref), a response wrapper (OutputObject/OutputItems/OutputValue), and its summary (Summary). Returned component and parameter schemas are deep-cloned (via jsonschema's CloneSchemas), so they never alias the parsed document and callers — and the MCP SDK — may mutate them freely.
Methods panic on a name/path/operation/parameter the document does not define: static, programmer-level errors that surface immediately in tests. The panic value wraps ErrUndefined. Only Parse, whose input is runtime bytes, returns an error.
Index ¶
- Variables
- func Object(properties map[string]*jsonschema.Schema, required []string) *jsonschema.Schema
- func OutputValue(jsonType string) *jsonschema.Schema
- type Schemas
- func (s *Schemas) BodySchema(method, path string) *jsonschema.Schema
- func (s *Schemas) OutputItems(name string) *jsonschema.Schema
- func (s *Schemas) OutputObject(name string) *jsonschema.Schema
- func (s *Schemas) ParamSchema(method, path, name string) *jsonschema.Schema
- func (s *Schemas) ParamsSchema(method, path string, names ...string) *jsonschema.Schema
- func (s *Schemas) Ref(name string) *jsonschema.Schema
- func (s *Schemas) Summary(method, path string) string
Constants ¶
This section is empty.
Variables ¶
var ErrParse = errors.New("openapi parse")
ErrParse is wrapped with the decode error when Parse cannot decode the document.
var ErrUndefined = errors.New("openapi undefined")
ErrUndefined is wrapped in the panic value when a method is asked for a name/path/operation/parameter the document does not define. A recovering caller can match it with errors.Is(recover().(error), ErrUndefined).
Functions ¶
func Object ¶
func Object( properties map[string]*jsonschema.Schema, required []string, ) *jsonschema.Schema
Object assembles a self-contained object schema from properties and required field names. An empty required slice is omitted from the schema.
func OutputValue ¶
func OutputValue(jsonType string) *jsonschema.Schema
OutputValue builds an output schema for a scalar response, wrapped under a "value" property of the given JSON Schema type (e.g. "number").
Types ¶
type Schemas ¶
type Schemas struct {
// contains filtered or unexported fields
}
Schemas assembles per-tool JSON Schemas from a parsed OpenAPI document.
func Parse ¶
Parse decodes a dereferenced OpenAPI document into a Schemas. It returns an error wrapping ErrParse when doc is not valid JSON.
func (*Schemas) BodySchema ¶
func (s *Schemas) BodySchema(method, path string) *jsonschema.Schema
BodySchema returns a deep clone of an operation's application/json request-body schema (used by POST/PUT tools), self-contained and embeddable freely. It panics if the operation is unknown or has no application/json request body.
func (*Schemas) OutputItems ¶
func (s *Schemas) OutputItems(name string) *jsonschema.Schema
OutputItems builds an output schema for a slice response, wrapped under an "items" array (the MCP structuredContent contract requires an object root).
func (*Schemas) OutputObject ¶
func (s *Schemas) OutputObject(name string) *jsonschema.Schema
OutputObject builds an output schema for a single-object response whose body is the named component, returned inlined (a deep clone via Ref) so the schema carries the top-level "type":"object" the MCP SDK requires. It panics if name is unknown or the component is not an object.
func (*Schemas) ParamSchema ¶
func (s *Schemas) ParamSchema(method, path, name string) *jsonschema.Schema
ParamSchema returns a single parameter's self-contained schema, for embedding inside an Object. It panics if the parameter is not found.
func (*Schemas) ParamsSchema ¶
func (s *Schemas) ParamsSchema( method, path string, names ...string, ) *jsonschema.Schema
ParamsSchema builds an object input schema from an operation's path + query parameters (used by GET tools). With no names it includes every parameter; with names, only that subset in the order given — letting a tool expose a curated slice of an operation's parameters. A parameter is required exactly when the spec marks it so. It panics if the operation is unknown or a requested name is not one of its parameters.
Source Files