WardrikRest

Copy Markdown

Tools for agents from an HTTP API's description: one tool per operation, with the API's own sign-in and keys. Use it for an API that has no MCP server, or one whose server falls short.

def deps do
  [
    {:wardrik_rest, "~> 0.1.0-rc.1"}
  ]
end

Usage

{:ok, analytics} =
  WardrikRest.API.load(
    {WardrikRest.Discovery,
     url: "https://analyticsdata.googleapis.com/$discovery/rest?version=v1beta"},
    name: "ga4",
    base_url: "https://analyticsdata.googleapis.com/",
    auth: %{"oauth2" => {:credential, "google"}},
    only: ["properties_runReport", "properties_getMetadata"],
    read_only: ["properties_runReport"]
  )

WardrikCore.start_agent(
  agent_id: "agt_marketing",
  model: "anthropic:claude-haiku-4-5",
  capabilities: [{WardrikRest, apis: [analytics]}],
  credentials: {MyApp.Credentials, []}
)

The agent gets ga4__properties_runReport and ga4__properties_getMetadata.

  • Load an API once, as your app starts or adds it.
  • only keeps tool definitions small. Each one goes into every model call.
  • GETs and the operations in read_only are read-only. The rest ask a person unless the policy allows them.

Credentials

auth maps each scheme the description names to a source:

  • {:credential, name} - a person's token from WardrikCore.Credentials. Until they sign in, the call waits for them. A refused token is refreshed once.
  • {:key, name} - a key from WardrikCore.Keys, such as one an org pasted.

headers adds headers the description doesn't name, such as a developer token. schemes adds schemes it doesn't name, such as %{"token" => :bearer} for an API that documents its sign-in elsewhere. Secrets go only to base_url, and never into arguments, answers or errors.

Formats

A source is a reader and what it reads, as {WardrikRest.Discovery, url: url}.

  • OpenAPI 3.0 and 3.1, in JSON or YAML: WardrikRest.OpenAPI, from a url, a path or a decoded document. JSON and form-encoded bodies are sent; file uploads and HTTP basic aren't yet.
  • Google Discovery documents: WardrikRest.Discovery, from a url or a decoded document.
  • Other formats: a module with the WardrikRest.Reader behaviour, whose read/1 returns a WardrikRest.Spec. Its schemas refer to the spec's types by name, and tools are fitted from them.

License

Apache-2.0