Documentation
¶
Overview ¶
Package tools holds the inputs of the tools of ratd: their names, types and JSON schemas. ratd serves these schemas, and rat reads them to build the requests it relays: from protocol 2026-07-28 on, an argument whose schema carries an x-mcp-header annotation travels in an HTTP header as well (SEP-2243), which ParamHeaders computes. A rat and a ratd of the same version thus agree on the tools, without rat learning them from ratd (tools/list): rat only needs the schemas, not what the tools do, which stays in ratd. The code of rat does not change with the tools, but a rat built with an older ratd does not know the annotations of newer tools.
The schemas are inferred from the types, as the MCP SDK infers them (Schemas), with the annotations added by hand: the jsonschema struct tag only carries descriptions. No tool annotates an argument yet. Two limits to know before annotating one, both of the Go SDK v1.8.0:
- an invalid annotation (not on a string, an integer nor a boolean, a header name out of the HTTP token characters, a duplicate) makes the SDK client drop the tool from tools/list, which the tests of ratd listing its tools catch;
- an annotated string argument must not be empty: the SDK client then sends an empty header, which its server reads as missing, refusing the call.
Index ¶
- Constants
- func ParamHeaders(schema *jsonschema.Schema, arguments json.RawMessage) map[string]string
- func Schemas() (map[string]*jsonschema.Schema, error)
- func Wait(arguments json.RawMessage) time.Duration
- type NameInput
- type NoInput
- type ReadFileInput
- type ReadWindowInput
- type SendKeysInput
- type SendTextInput
- type WaitWindowInput
- type WriteFileInput
Constants ¶
const ( // HeaderAnnotation is the schema keyword binding an argument to an HTTP header (SEP-2243). HeaderAnnotation = "x-mcp-header" // ParamHeaderPrefix starts the name of the header of an annotated argument. ParamHeaderPrefix = "Mcp-Param-" )
const ( ListWindows = "list_windows" CreateWindow = "create_window" CloseWindow = "close_window" SendText = "send_text" SendKeys = "send_keys" ReadWindow = "read_window" WaitWindow = "wait_window" WriteFile = "write_file" ReadFile = "read_file" )
Names of the tools.
const ( // DefaultWaitSeconds is how long wait_window waits at most, unless told. DefaultWaitSeconds = 20 // MaxWaitSeconds is the longest wait_window waits. A harness cuts a tool call at a limit of its // own, which ratd can not see, nor push back: it answers without a stream, with no progress to // send meanwhile. Several harnesses cut at 60 seconds by default (Cline, Zed, OpenCode, Continue, // the Cursor CLI, and Claude Code reaching ratd over HTTP, checked in their code in 2026-10): a // wait of 60 seconds would race them, its answer coming after the cut, and the agent getting an // error from its harness instead. 50 leaves room for the network and for ratd to answer. MaxWaitSeconds = 50 )
Variables ¶
This section is empty.
Functions ¶
func ParamHeaders ¶
func ParamHeaders(schema *jsonschema.Schema, arguments json.RawMessage) map[string]string
ParamHeaders returns the headers carrying the annotated arguments of a tool call (SEP-2243), by name: an argument of the arguments given, whose property in schema carries an x-mcp-header annotation. Missing or null arguments have none, as have values that are not a string, a boolean or an integer JavaScript represents exactly. The values are encoded as the MCP SDK checks them: an integer in decimal, a boolean as true or false, a string as is when made of printable ASCII without spaces around, otherwise in base64 between =?base64? and ?=.
func Schemas ¶
func Schemas() (map[string]*jsonschema.Schema, error)
Schemas returns the input schema of each tool, by name: inferred from its type as the MCP SDK infers it, then annotated. New schemas at each call: ratd builds them once and serves the same ones to every request, as the schema cache of the SDK keys them by pointer.
func Wait ¶
func Wait(arguments json.RawMessage) time.Duration
Wait returns how long a call of wait_window with arguments waits at most: max_seconds, or DefaultWaitSeconds when missing or not a number, MaxWaitSeconds at most. ratd refuses a value out of bounds, but rat, which bounds its request with it, reads it before.
Types ¶
type NameInput ¶
type NameInput struct {
Name string `json:"name" jsonschema:"the name of the window: letters, digits, '_' and '-', up to 32 characters, not digits only"`
}
NameInput is the input of a tool acting on a window it names: create_window, close_window.
type NoInput ¶
type NoInput struct{}
NoInput is the input of a tool taking no argument: list_windows.
type ReadFileInput ¶
type ReadFileInput struct {
Path string `json:"path" jsonschema:"absolute, or starting with ~/ for the home directory"`
StartLine int `json:"start_line,omitempty" jsonschema:"the first line to read, from 1; negative counts from the end (-1 is the last line)"`
MaxLines uint `json:"max_lines,omitempty" jsonschema:"the most lines to read, all by default"`
LineNumbers bool `` /* 151-byte string literal not displayed */
}
ReadFileInput is the input of read_file. start_line 0 is no start: lines count from 1, and the schema can not tell 0 from a missing number. max_lines is unsigned: the schema then refuses a negative number.
type ReadWindowInput ¶
type ReadWindowInput struct {
Window string `json:"window" jsonschema:"the name of the window"`
ScrollbackRows uint `json:"scrollback_rows,omitempty" jsonschema:"rows of history to include above the screen"`
}
ReadWindowInput is the input of read_window. The rows are unsigned: the schema then refuses a negative number.
type SendKeysInput ¶
type SendKeysInput struct {
Window string `json:"window" jsonschema:"the name of the window"`
Keys []string `json:"keys" jsonschema:"the key names, pressed in order"`
}
SendKeysInput is the input of send_keys.
type SendTextInput ¶
type SendTextInput struct {
Window string `json:"window" jsonschema:"the name of the window"`
Text string `` /* 146-byte string literal not displayed */
Enter bool `` /* 129-byte string literal not displayed */
}
SendTextInput is the input of send_text. Enter is required, with no default: the agent decides every time whether the text runs, and forgetting it fails validation instead of silently leaving a command unrun (false) or running text meant to wait (true).
type WaitWindowInput ¶
type WaitWindowInput struct {
Window string `json:"window" jsonschema:"the name of the window"`
MaxSeconds uint `json:"max_seconds,omitempty" jsonschema:"the most seconds to wait"`
}
WaitWindowInput is the input of wait_window. max_seconds 0 is DefaultWaitSeconds: the schema can not tell 0 from a missing number, and bounds the others (see Schemas).
type WriteFileInput ¶
type WriteFileInput struct {
Path string `json:"path" jsonschema:"absolute, or starting with ~/ for the home directory"`
Content string `json:"content" jsonschema:"the whole content of the file, written as is"`
}
WriteFileInput is the input of write_file. The content is required, and may be empty.
Source Files