outfitter

Outfitter

Outfitter is shared infrastructure for building AI-agent-ready tools. CLIs, MCP servers, daemons—with patterns that work for both humans and machines.

Status: Active Development

Quick Start

bunx outfitter init my-project --preset cli --yes
cd my-project
bun install
bun run dev

Output:

my-project v0.1.0

Usage: my-project [command] [options]

Commands:
  example    Run example command
  help       Display help for command

That scaffolds a working CLI with typed commands, output mode detection, and proper error handling. Four commands to useful software.

Why Outfitter

We kept solving the same problems across projects: config loading, error handling, CLI output modes, MCP server boilerplate. Every tool needed the same foundation.

So we extracted it.

Outfitter is opinionated infrastructure for the Bun ecosystem. The patterns assume you're building tools that agents will consume—structured output, typed errors, predictable behavior. Humans benefit too; agents just make the stakes clearer.

The core idea: handlers are pure functions returning Result types. CLI and MCP are thin adapters over the same logic. Write the handler once, expose it everywhere.

v0.6 Highlights (Streaming, Safety, Completeness)

• Streaming (@outfitter/cli, @outfitter/contracts, @outfitter/mcp) — NDJSON output with --stream, transport-agnostic ctx.progress on HandlerContext, and MCP progress adapter support (notifications/progress).
• Safety (@outfitter/cli, @outfitter/mcp) — .destructive(true) auto-adds --dry-run, .readOnly(true) / .idempotent(true) metadata maps to MCP annotations, and error envelopes include retryable + retry_after.
• Completeness (@outfitter/cli) — output truncation adds pagination hints and full-output file pointers, and .relatedTo() builds an action graph for tier-4 related-command hints.
• Reference project (examples/reference/) — end-to-end example showing v0.4-v0.6 patterns across shared handlers, CLI, and MCP.

For migration details and before/after examples, see v0.6 Migration.

v0.5 Highlights (Builder Pattern)

• Builder core (@outfitter/cli) — .input(schema) auto-derives flags from Zod, .context(factory) adds typed async context, .hints() / .onError() keep hints transport-local, createSchemaPreset() enables schema-driven presets, and runHandler() + output.envelope() unify lifecycle/output/exit mapping.
• Agent-navigable UX (@outfitter/cli) — self-documenting root command and tiered hint generation (command tree, error category recovery, schema-derived params).
• Contracts (@outfitter/contracts) — canonical ActionHint / CLIHint / MCPHint types plus enriched ErrorCategory metadata via errorCategoryMeta().
• MCP (@outfitter/mcp) — defineResourceTemplate() now supports Zod-validated typed URI template params.
• Config + Testing — loadConfig() schema argument is now optional; testCommand() / testTool() include new input, context, json, envelope, and hints support.
• DX — outfitter check action-registry, outfitter upgrade --codemods, and richer starter examples (outfitter init cli ... --example todo, outfitter init mcp ... --example files).

For migration details and before/after examples, see v0.5 Migration.

Packages

Three tiers, one goal: shared infrastructure that works for humans and machines.

• Stable — APIs locked, breaking changes rare
• Active — APIs evolving based on usage
• Early — APIs will change, not production-ready

Foundation (Stable)

APIs everything else depends on.

Package	What it does
@outfitter/contracts	Result/Error patterns, handler contract, and utilities like parseInput(), wrapError(), fromFetch(), expectOk(), expectErr()
@outfitter/types	Type utilities and branded types

Runtime (Active)

The building blocks for applications.