@ontrove/extend/toolkit

@ontrove/extend/toolkit — the thin standard library for authoring hosted Trove MCP servers. It owns the MCP protocol, JSON-RPC, schema validation, auth-context injection, secret access, and error envelopes, so authors write only the handlers (see the hosted-MCP SDK reference).

Example

import { defineToolkit, z, ToolError } from "@ontrove/extend/toolkit";

export default defineToolkit({
  tools: [
    {
      name: "lookup_order",
      description: "Look up an internal order by ID.",
      input: z.object({ orderId: z.string().describe("e.g. 'ORD-10423'.") }),
      async handler({ orderId }, ctx) {
        const token = await ctx.secret("ORDERS_API_TOKEN");
        const res = await ctx.fetch(`https://orders.acme.internal/v1/${orderId}`, {
          headers: { authorization: `Bearer ${token}` },
        });
        if (res.status === 404) throw new ToolError(`Order ${orderId} not found`);
        return { text: `Order ${orderId}: ok`, structured: await res.json() };
      },
    },
  ],
});

Classes

Class	Description
ToolError	An intentional, model-visible tool error.

Interfaces

Interface	Description
DefineOptions	Options for defineToolkit — primarily injection points for tests.
FetchHandler	A minimal fetch handler shape, matching the fetch signature the hosted runtime exposes for each request.
FetchJsonOpts	Options for ToolContext.fetchJson. Supply schema (as part of the call, not this base type) to validate and type the result via z.infer.
JsonSchema	A JSON Schema object for a tool’s inputSchema, as surfaced in tools/list.
OAuth2ClientCredentials	Declarative OAuth2 client-credentials auth. When set on ToolkitConfig, the SDK mints, caches, and attaches a Bearer token to egress automatically, so handlers never touch the token dance. The client id/secret are resolved from the vault by name (both must appear in the manifest secrets), and the tokenUrl host and apiHost must appear in the manifest egress.
ToolAnnotations	Behavioral hints for a tool (MCP annotations, spec 2025-06-18 / 2025-11-25).
ToolCall	A normalized tool-call request as POSTed by the gateway into the hosted runtime. callbackBase is the Trove-provided origin the SDK’s ctx callbacks target; it is appended to the egress allowlist server-side.
ToolCallErr	A normalized failed tool result, as returned to the gateway.
ToolCallOk	A normalized successful tool result, as returned to the gateway.
ToolContext	The invocation context handed to every tool handler — a small capability object with no ambient authority.
ToolDefinition	A single tool definition. The input Zod schema is compiled to JSON Schema for tools/list and used to validate arguments before handler runs.
ToolErrorOptions	Options for ToolError.
ToolkitConfig	The configuration passed to defineToolkit.
ToolkitDefinition	The compiled server, produced by defineToolkit. It carries the tools/list descriptors and a normalized request handler the runtime entry wires to the hosted runtime’s fetch.
ToolListEntry	The tools/list-shaped descriptor of a single tool.
ToolResult	The object a handler returns. text is the model-visible body; structured is optional JSON-serializable data some clients display. When the tool declares an output schema, structured is surfaced to the host as the spec structuredContent object alongside the text mirror.
TroveClient	A scoped client over the calling user’s own Trove knowledge base.
TroveDocument	A full document fetched by id.
TroveIngestDoc	A document to write into the knowledge base via TroveClient.ingest.
TroveIngestFallback	The artifact to capture when the preferred one turns out not to exist. See TroveIngestDoc.fallback.
TroveIngestFeed	-
TroveIngestResult	The result of an TroveClient.ingest call.
TroveSearchOpts	Parameters to TroveClient.search.
TroveSearchResult	A single semantic-search hit from the user’s knowledge base.

Type Aliases

Type Alias	Description
FetchLike	The fetch implementation the SDK uses for callbacks and egress. Injectable so tests can supply a mock; defaults to the global fetch.
ToolCallResult	The discriminated union of normalized tool-call outcomes.
ToolErrorCode	Stable machine-readable error codes the SDK emits.

Functions

Function	Description
compileInputSchema	Compile a Zod schema to a JSON Schema object suitable for inputSchema.
defineToolkit	-
dispatch	Dispatch one normalized call against a server definition.
listTools	The tools/list descriptors for a server.
toFetchHandler	Wrap a server definition as a runtime fetch handler.
tool	Identity helper that keeps a tool’s schema type, so its handler’s arguments are typed for real.
toToolkitManifest	The manifest half of a toolkit, as the JSON a catalog commits.