API

This page lists the public API surface. Docs and examples should import these exports only, not package internals. Ohtools 0.1 is Bun-only.

When to use this: use it as the lookup page after you know which concept or guide applies.

import { Ohtools, defineTool, jsonSchema } from "@bosun-sh/ohtools";

@bosun-sh/ohtools

Builder exports:

• Ohtools: app builder for tools, groups, metadata, plugins, adapters, build, and runtime.
• defineTool: creates a reusable typed tool definition with an exact ID.
• defineGroup: creates a reusable group contribution for hierarchy.
• plugin: creates a named plugin builder.
• PluginBuilder and GroupBuilder: reusable composition builders.

Runtime and registry exports:

• buildRegistry, buildGraph, createRuntime, exploreRegistry, runRegistry, and serializeGraph.
• assertValidId for public ID validation.
• Types including DefinedTool, DefinedGroup, ToolSpec, ToolDefinition, GroupDefinition, AdapterDefinition, BuiltOhtoolsApp, OhtoolsRegistry, OhtoolsRuntime, ExploreRequest, ExploreResult, RunRequest, RunResult, DefaultEnv, OhtoolsError, OhtoolsErrorCode, and schema-related JSON types.

Builder Example

import { Ohtools, defineTool, jsonSchema } from "@bosun-sh/ohtools";
import { Effect } from "effect";

const hello = defineTool({
  id: "hello",
  description: "Return a greeting.",
  input: jsonSchema<{ name: string }>({
    type: "object",
    properties: { name: { type: "string" } },
    required: ["name"],
    additionalProperties: false
  }),
  output: jsonSchema<{ message: string }>({
    type: "object",
    properties: { message: { type: "string" } },
    required: ["message"],
    additionalProperties: false
  }),
  run: ({ name }) => ({ message: `Hello, ${name}` })
});

const runtime = new Ohtools().tool(hello).runtime();
const result = await Effect.runPromise(runtime.runTool(hello, { name: "Ada" }));

result.output.message;

Schemas

Schema exports from the root package:

• schema: wrap a custom runtime parser.
• jsonSchema: wrap a JSON Schema object with Ohtools validation.
• parseWithSchema: run a schema definition against a value.
• InferSchema: infer the TypeScript type carried by a schema definition.

The @bosun-sh/ohtools/schemas subpath exports the same schema helpers for consumers that only need schema utilities.

Generated Docs

Generated docs exports:

• generateDocs
• generateDocsJson
• generateDocsMarkdown
• GeneratedDocsFormat
• GeneratedDocsJson
• GeneratedToolDoc
• GeneratedNextStepDoc

Errors

Error exports:

• makeError
• validationError
• normalizeError
• formatError
• isOhtoolsError

Use OhtoolsErrorCode for stable adapter and runtime error handling.

@bosun-sh/ohtools/adapters/mcp

• mcpAdapter: attaches MCP stdio support when configured with { stdio: true }.
• mcpToolDescriptors: returns descriptors for executable tools plus ohtools.explore and ohtools.graph.
• mcpResources: returns graph, tool, and group resources.

MCP support is stdio-only in 0.1. HTTP, SSE, and streamable HTTP transports are not implemented.

@bosun-sh/ohtools/adapters/cli

• cliAdapter: attaches the CLI adapter definition.
• runCli: command runner used by the ohtools binary.
• CliAdapterOptions, CliEnvelope, and CliErrorEnvelope.

The CLI supports list, explore, run, and graph.

Continue with Basic Example for a runnable package or MCP Adapter for adapter behavior.