Getting Started

This page takes you from an empty directory to a tool app an agent can inspect before it runs anything. Use the published @bosun-sh/ohtools package for npm-backed CLI, install, and version operations. Ohtools 0.1 is Bun-only; Node, Deno, browser runtimes, HTTP, SSE, and streamable HTTP are not supported in this release.

What you will build: a small TypeScript app with one typed tool, local CLI commands, and a shape that can later be exposed through MCP stdio.

npx @bosun-sh/ohtools create my-tools
cd my-tools
bun install
bun run ohtools:list

The scaffold creates src/ohtools.ts, runnable package scripts, and a local .agents/skills/ohtools skill. That skill gives future coding agents the project contract before they edit tools, plugins, adapters, docs, or examples.

Agent Setup

Give coding agents the Ohtools project contract before they edit tools, plugins, adapters, docs, or examples. The prompt is available as a copy action, and the shared skill can be installed into projects that do not already include the scaffolded local skill.

npx skills add https://github.com/bosun-sh/skills --skill ohtools

Add Ohtools To An Existing Project

Use init when you already have a Bun TypeScript project:

npx @bosun-sh/ohtools init

Manual setup is also supported:

bun add @bosun-sh/ohtools effect @modelcontextprotocol/sdk

Create src/ohtools.ts:

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

export default new Ohtools().tool("hello", {
  description: "Return a greeting.",
  input: jsonSchema<{ name: string }>({
    type: "object",
    properties: { name: { type: "string" } },
    required: ["name"],
    additionalProperties: false
  }),
  run: ({ name }) => ({ message: `Hello, ${name}` })
});

Inspect And Run

Agents should explore the registry before invoking handlers. Explore is side-effect free: it reads tool and group descriptors, but it does not call run.

bunx ohtools --app ./src/ohtools.ts list
bunx ohtools --app ./src/ohtools.ts explore hello
bunx ohtools --app ./src/ohtools.ts run hello --input '{"name":"Ada"}'

The CLI prints JSON envelopes by default. Successful commands return { "ok": true, "data": ... }; failures return { "ok": false, "error": ... }.

Expose The Same App

When an MCP client owns the process lifecycle, attach the MCP adapter and start it from a Bun entrypoint. MCP support is stdio-only in 0.1.

import { Ohtools } from "@bosun-sh/ohtools";
import { mcpAdapter } from "@bosun-sh/ohtools/adapters/mcp";

export const app = new Ohtools({ name: "my-tools" }).adapter(mcpAdapter({ stdio: true }));

Continue with First Tool for typed handlers, MCP Server for stdio launch wiring, and Skill Flow when agents will maintain the project.