README
¶
openapi-to-agent-tools (o2t)
Turn OpenAPI 3.x into Agent-ready tools — with risk, side-effect, and confirmation metadata — in one command.
Most OpenAPI→tool converters stop at name + JSON Schema.
o2t also drafts governance fields (risk_level, side_effect, idempotency, confirmation), explains why, and lints weak enterprise specs — so you can safely plug real APIs into Agents / MCP / OpenAI functions.
Offline by default. No login. No telemetry. Apache-2.0.
Demo (30 seconds)
go install github.com/legendnero/openapi-to-agent-tools/cmd/o2t@v0.1.0
# or: download a release binary from GitHub Releases
o2t import --spec ./examples/petstore/openapi.yaml --out ./tools
o2t lint ./tools
o2t export --in ./tools --format openai --out ./export
Imported OpenAPI: Petstore (3.0.3)
Generated: 5 tools → ./tools
Risk: 2 low · 2 medium · 1 high · 0 critical
Next: o2t lint ./tools && o2t export --in ./tools --format openai --out ./export
Tip: 1 high/critical tools — review confirmation & permissions before Agent use.
High-risk APIs (payments / admin):
o2t import --spec ./examples/payments-write/openapi.yaml --out ./tools-pay
o2t lint ./tools-pay
# → risk high/critical + confirmation=required drafts
Messy specs (shows lint value):
o2t import --spec ./examples/messy-spec/openapi.yaml --out ./tools-messy
o2t lint ./tools-messy --format json
# → MISSING_DESCRIPTION, WEAK_SCHEMA, EMPTY_OUTPUT_SCHEMA, ...
Why not just another OpenAPI→MCP generator?
| Typical converters | o2t | |
|---|---|---|
| Output | name + parameters | ToolDraft + governance + source lineage |
| Risk / write ops | ignored | risk_level, side_effect, confirmation |
| Explainability | black box | annotations.governance_reasons |
| Quality gate | none | o2t lint + --fail-on for CI |
| Targets | often one format | platform · openai · langchain · mcp |
| Privacy | varies | offline, telemetry off |
Install
Binary (recommended)
Download from Releases
(linux / darwin / windows · amd64 / arm64).
From source (Go 1.22+)
go install github.com/legendnero/openapi-to-agent-tools/cmd/o2t@latest
# or
git clone https://github.com/LegendNero/openapi-to-agent-tools.git
cd openapi-to-agent-tools
make build && ./bin/o2t version
What you get
Each OpenAPI operation becomes a ToolDraft (apiVersion: agent.tools/v1):
apiVersion: agent.tools/v1
kind: ToolDraft
metadata:
name: delete.pet
source:
method: DELETE
path: /pets/{petId}
spec_hash: sha256:...
spec:
description: Permanently remove a pet.
risk_level: high
side_effect: delete
idempotency: idempotent
confirmation: required
input_schema: { type: object, properties: { petId: { type: string } }, required: [petId] }
annotations:
governance_reasons:
- method DELETE → delete/high/required
Frozen contract: SPEC.md.
CLI
o2t version
o2t doctor
o2t import --spec <file|url> --out <dir> [--format yaml|json] [--include-deprecated]
o2t lint <tools-dir|file> [--format text|json] [--fail-on warning|error]
o2t export --in <dir> --format platform|openai|langchain|mcp --out <dir>
| Exit | Meaning |
|---|---|
| 0 | success |
| 1 | generic error |
| 2 | spec parse / load failure |
| 3 | lint fail-on threshold |
| 4 | export failure |
Tips: disable with --no-tips or O2T_NO_TIPS=1.
Optional upgrade link: O2T_UPGRADE_URL=https://your-product.example.
Examples
| Path | Purpose |
|---|---|
examples/petstore |
Happy-path OpenAPI 3.0 |
examples/petstore31 |
OpenAPI 3.1 JSON |
examples/payments-write |
POST/DELETE + payment/admin keywords |
examples/messy-spec |
Missing descriptions / weak types |
Docs
Open Core / commercial
This CLI is the open tip of the spear: convert + lint + export.
Not in OSS: multi-tenant publish approval, budget hard limits, SSO, enterprise gateway, FinOps control plane.
o2t push intentionally returns “not enabled” in v0.1.
If you need agent tool catalogs that are governed, budgeted, and auditable at company scale, start here and grow into a control plane — without locking your local workflow.
Non-goals (v0.1)
- Live write trials against production APIs
- GraphQL / gRPC import
- Login-gated generation
- Default telemetry
Contributing
See CONTRIBUTING.md. Security: SECURITY.md.
License
Apache-2.0 — see LICENSE.
Directories