mcp

type Arg struct {
	// Name is the argument name as the agent passes it.
	Name string
	// In is where the REST request carries it: path, query, header or body.
	In string
	// Required mirrors the parameter flag or the body required list.
	Required bool
	// Description is the parameter or property description.
	Description string
	// Schema is the schema of the argument with its ref resolved, except a
	// nullable reference to a shared component, kept as {allOf: [{$ref}],
	// nullable: true} so the component stays named. Function.InputSchema
	// gives the resolved JSON Schema of every argument.
	Schema *reference.Schema
	// contains filtered or unexported fields
}

type AuthFunc func(ctx context.Context, token string) (http.Header, error)

type Caller interface {
	// Call invokes the function by catalog name with a flat argument object
	// and returns the response body. Errors carry the ez code of the REST
	// error.
	Call(ctx context.Context, name string, args map[string]any) (json.RawMessage, error)
}

type Catalog struct {
	Modules []*Module
	Terms   []*Term
	// contains filtered or unexported fields
}

type Composite struct {
	// Module is the module name the function is listed under.
	Module string
	// Name is the function name inside the module, snake_case.
	Name string
	// Summary is the one-line description shown by search_functions.
	Summary string
	// Description is the longer text shown by describe_function.
	Description string
	// ReadOnly marks the composite as safe for read-only scripts.
	ReadOnly bool
	// Input and Output are zero values of the argument and result types.
	// Their JSON Schemas are derived by reflection, which follows the Go
	// types: a field whose JSON form differs from its Go type, such as
	// json:",string" or json.RawMessage, is advertised as the Go type.
	Input  any
	Output any
	// Run executes the composite with the decoded arguments.
	Run func(ctx context.Context, call Caller, args json.RawMessage) (any, error)
}

type Concept struct {
	// Text is the paragraph explaining the term.
	Text string
	// Aliases are other names the agent may use for the term, in any language.
	Aliases []string
}

type Config struct {
	// Name identifies the server to clients. Defaults to info.title.
	Name string
	// Version is reported to clients. Defaults to info.version.
	Version string
	// Spec is the OpenAPI 3.x document, JSON or YAML.
	Spec []byte
	// Handler serves the REST API. call_function builds an HTTP request and
	// dispatches it to Handler in-process, so auth, validation and errors
	// are exactly those of the REST API.
	Handler http.Handler
	// Instructions is the application paragraph placed before the generated
	// module list in the server instructions.
	Instructions string
	// Auth maps the bearer token of an MCP request to the headers the REST
	// API authenticates with. Defaults to BearerPassthrough().
	Auth AuthFunc
	// WhoAmI names the catalog function that whoami calls with no arguments,
	// for example "users.me"; New refuses a function with a required
	// argument. Empty makes whoami report the server identity only.
	WhoAmI string
	// Composites are hand-written functions added to the catalog.
	Composites []Composite
	// Concepts adds glossary entries for terms that are not schemas, or sets
	// the description and aliases of a schema term. Keys are term names.
	Concepts map[string]Concept
	// Script enables and bounds run_script.
	Script ScriptConfig
	// Tools names catalog functions, operations or composites, that the server
	// also exposes as first-class MCP tools next to the fixed set, for clients
	// that should call them without search_functions and describe_function
	// first. Each name is a full catalog name, "module.function", and becomes a
	// tool named by Function.ToolName, units.list as units-list. New refuses a
	// name the catalog does not have, one whose tool name does not match
	// ^[a-zA-Z0-9_-]{1,64}$, one with an argument name that does not match
	// ^[a-zA-Z0-9_.-]{1,64}$ (the Claude API's rule for property names), one
	// whose input schema has more than 1000 nodes, or a name given twice.
	Tools []string
	// MaxOutputBytes caps the text of one tool result. Longer results are cut
	// with a hint to narrow the request. Defaults to 24000 (about 6k tokens).
	MaxOutputBytes int
	// OnError, when set, receives failures the agent sees only as generic
	// text: a panic in a tool handler or in a function a script calls, with
	// its stack, and internal failures of the script runtime. Optional.
	OnError func(ctx context.Context, err error)
}

type Function struct {
	// Name is the full name, "module.function".
	Name string
	// Module is the module name.
	Module string
	// Summary is the one-line description.
	Summary string
	// Description is the longer text, may be empty.
	Description string
	// Method and Path are the HTTP operation; empty for composites.
	Method string
	Path   string
	// Args is the flat argument list: path, query and header parameters
	// followed by the body properties. When a body property name collides
	// with a parameter the body is exposed as one "body" argument instead.
	Args []*Arg
	// Returns is the term name of the success response, or empty.
	Returns string
	// ReturnSchema is the resolved success response schema, or nil.
	ReturnSchema *reference.Schema
	// Deprecated mirrors the operation flag.
	Deprecated bool
	// Composite is true for hand-written functions.
	Composite bool
	// ReadOnly is true for GET and HEAD operations and read-only composites.
	ReadOnly bool
	// Destructive is true for DELETE operations.
	Destructive bool
	// contains filtered or unexported fields
}

type Module struct {
	// Name is the snake_case tag name.
	Name string
	// Description is the tag description, when the document has one.
	Description string
	// Functions are sorted by name.
	Functions []*Function
}

type ScriptConfig struct {
	// Enabled registers the run_script tool.
	Enabled bool
	// Allow, when set, decides per caller whether run_script may run: it
	// receives the JSON the WhoAmI function returned for the caller's
	// credentials. Use it to limit scripts to operators, for example by
	// role. Nil allows every caller WhoAmI accepts.
	Allow func(ctx context.Context, whoami json.RawMessage) bool
	// AllowWrites lets scripts call functions that are not read-only.
	AllowWrites bool
	// Timeout stops the script, function calls included. Defaults to 5s.
	Timeout time.Duration
	// MaxCalls bounds the function calls one script may make. Defaults to 200.
	MaxCalls int
	// MaxConcurrent bounds the scripts running at once across all callers;
	// defaults to 4. Each caller runs one script at a time.
	MaxConcurrent int
}

type Server struct {
	// contains filtered or unexported fields
}

type Term struct {
	// Name is the display name, unique within the catalog.
	Name string
	// Description is the schema description or the concept text.
	Description string
	// Aliases are other names that resolve to the term.
	Aliases []string
	// Schema is the component schema, or nil for concept-only terms.
	Schema *reference.Schema
	// AcceptedBy lists the functions whose arguments reference the schema.
	AcceptedBy []string
	// ReturnedBy lists the functions whose success response is the schema.
	ReturnedBy []string
}

type Tool struct {
	Name        string
	Description string
	// InputSchema is the JSON Schema of the tool's arguments.
	InputSchema json.RawMessage
	// The hints are the tool's annotations as an MCP client reads them. A
	// destructiveHint or openWorldHint the server leaves unset is true, the
	// MCP default, and Destructive is false for a read-only tool, where MCP
	// gives the hint no meaning. A write promoted from Config.Tools that is
	// not Function.Destructive is therefore Destructive: MCP reads a false
	// destructiveHint as additive updates only, which PUT and PATCH are not.
	// Idempotent is idempotentHint as set, also on a read-only tool, where
	// MCP gives it no meaning either, so a read-only run_script reports false
	// and the other read-only tools true.
	ReadOnly    bool
	Idempotent  bool
	Destructive bool
	OpenWorld   bool
}