Documentation
¶
Overview ¶
Package engine is the framework-agnostic core: it turns ir.Operations into MCP tools (with raw JSON Schema inputs) and wires each tool's handler to the HTTP Executor. It knows nothing about OpenAPI, Gin, Echo or any source.
Index ¶
- func DefaultShape(r *Response) string
- func InputSchema(op ir.Operation) json.RawMessage
- func Register(s *server.MCPServer, tools []Tool)
- func WithHeaders(ctx context.Context, h map[string]string) context.Context
- type AnnotateFunc
- type AuditEvent
- type AuditFunc
- type BuildConfig
- type Executor
- type RateLimit
- type Response
- type ShapeFunc
- type Tool
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DefaultShape ¶
DefaultShape returns the body verbatim, prefixed with the HTTP status when it is not a 2xx so the LLM can reason about failures.
func InputSchema ¶
func InputSchema(op ir.Operation) json.RawMessage
InputSchema assembles a single JSON Schema object describing every input an LLM must provide to call the operation. The convention is deliberately flat and predictable:
- each path/query/header parameter becomes a top-level property keyed by its name, carrying the parameter's own JSON Schema;
- a JSON request body becomes a single "body" property holding the body schema.
This keeps the mapping back to an HTTP request unambiguous in the executor.
Types ¶
type AnnotateFunc ¶
type AnnotateFunc func(op ir.Operation, base mcp.ToolAnnotation) mcp.ToolAnnotation
AnnotateFunc lets callers adjust a tool's safety annotations after they are derived from the HTTP method — e.g. to force destructiveHint on a POST that charges a card. base is the method-derived annotation.
type AuditEvent ¶
type AuditEvent struct {
OperationID string
Method string
Path string
Status int
Duration time.Duration
Err error
}
AuditEvent records one tool invocation for observability. Logging every call — what was invoked, against which upstream path, with what result — is part of running an LLM-facing API safely.
type AuditFunc ¶
type AuditFunc func(AuditEvent)
AuditFunc receives an AuditEvent after each tool call completes.
type BuildConfig ¶
type BuildConfig struct {
Executor *Executor
Shape ShapeFunc // nil → DefaultShape
Audit AuditFunc // nil → no audit logging
Limit RateLimit // zero → unlimited
Annotator AnnotateFunc // nil → method-derived annotations only
}
BuildConfig holds everything Build needs beyond the operations themselves. All fields are optional except Executor.
type Executor ¶
type Executor struct {
// BaseURL is the upstream API root, e.g. "https://api.internal".
BaseURL string
// Client is the HTTP client used for upstream calls. Defaults to a client
// with a 30s timeout when nil.
Client *http.Client
// StaticHeaders are sent on every request (e.g. an injected API key).
StaticHeaders map[string]string
}
Executor turns a resolved operation + arguments into a real upstream HTTP call. It is the only component that talks to the downstream API.
func (*Executor) Call ¶
func (e *Executor) Call(ctx context.Context, op ir.Operation, args map[string]any) (*Response, error)
Call executes op with the given tool arguments and returns the upstream response. Path params are substituted into the URL, query/header params are attached, and the "body" argument (if any) is sent as a JSON body.
type RateLimit ¶
type RateLimit struct {
// PerSecond is the sustained refill rate (tokens added per second).
PerSecond float64
// Burst is the bucket capacity — the most calls allowed back-to-back.
Burst int
}
RateLimit caps how often a single tool may be invoked. It is applied per-operation (each tool gets its own bucket), so one chatty tool can't starve the others. A zero PerSecond disables limiting.
type Response ¶
Response is the raw upstream result handed back to the curation layer for optional shaping before it reaches the LLM.
type ShapeFunc ¶
ShapeFunc renders an upstream response into the text returned to the LLM. It is the hook the curation layer uses to truncate or field-select large payloads. When nil, DefaultShape is used.
Source Files