Skip to content

Katana OpenAPI Client Documentation

Welcome to the documentation site for the Katana OpenAPI Client monorepo — a production-ready set of clients for the Katana Manufacturing ERP API, with automatic resilience built in at the HTTP transport layer.

The site is generated from the per-package docs that live next to each package's source. Each section below links straight to the canonical doc for that area; the indexes themselves are the source of truth and stay current as features ship.

What's in the monorepo

This repository is a workspace with three published packages — a Python API client, a TypeScript API client, and the MCP server that wraps the Python client. For installation, current version, and a quick-start example for each, follow the link to the package's docs:

  • Python client — katana-openapi-client on PyPI. Sync + async API, transport-layer retries / rate-limiting / pagination, full pydantic models. Generated from docs/katana-openapi.yaml.
  • MCP server — katana-mcp-server on PyPI. Model Context Protocol server that wraps the Python client with high-level tools (search, modify, fulfill, verify, plus preview/apply pairs for write operations) for use with Claude Desktop, Cursor, and other MCP hosts.
  • TypeScript client — katana-openapi-client on npm. Async API with the same resilience guarantees as the Python client; works in browsers. (No docsite mirror — TS package docs live alongside the package source.)

The root README.md is the front door — it has the multi-package install table, a side-by-side feature comparison, and the cross-cutting setup steps. Read that first if you're new to the project.

Architecture in one paragraph

Resilience (retries, rate limiting, pagination) is implemented at the httpx transport layer, not as a wrapper. Every generated API method gets it automatically — including new endpoints added by spec regeneration. No decorators, no method-by-method opt-in. See ADR-0001 for the full rationale.

Documentation by package

Python client

  • Guide — installation, response unwrapping helpers (unwrap_data, unwrap_as, is_success), pagination, retries, logging.
  • Cookbook — task-oriented recipes.
  • Testing — httpx.MockTransport patterns, conftest fixtures.
  • Spec authoring — OpenAPI 3.1 conventions, generator / regen lockstep, breaking-change markers.
  • Changelog — release notes.
  • ADRs — client architectural decisions.

MCP server

The live MCP tool list is exposed at runtime via the katana://help/tools resource — that's the canonical inventory, not anything in this docsite.

TypeScript client

The TS client docs live with the package source on GitHub — packages/katana-client/. The current published version is on the npm page.

Reference

  • OpenAPI specification — interactive viewer for docs/katana-openapi.yaml, the canonical endpoint surface that drives both generated clients.
  • API reference — auto-generated from the Python source via mkdocstrings; one page per module.

Process and contribution

Architecture decision records

ADRs live next to the package they govern. Each directory has a README.md index listing every ADR with its current status — those indexes are the canonical list and stay current as ADRs are added or superseded.

Support

MIT licensed — LICENSE.