Katana Manufacturing ERP - API Ecosystem

Multi-language client ecosystem for the Katana Manufacturing ERP API. Production-ready clients with automatic resilience, rate limiting, and pagination.

Packages

Package	Language	Description
katana-openapi-client	Python	Full-featured API client with transport-layer resilience
katana-mcp-server	Python	Model Context Protocol server for AI assistants
katana-openapi-client	TypeScript	TypeScript/JavaScript client with full type safety

Features Comparison

Feature	Python Client	TypeScript Client	MCP Server
Automatic retries	Yes	Yes	Yes (via Python client)
Rate limit handling	Yes	Yes	Yes
Auto-pagination	Yes	Yes	Yes
Type safety	Full (Pydantic)	Full (TypeScript)	Full (Pydantic)
Sync + Async	Yes	Async only	Async only
Browser support	No	Yes	No
AI Integration	-	-	Claude, Cursor, etc.

Quick Start

Python Client

pip install katana-openapi-client

import asyncio
from katana_public_api_client import KatanaClient
from katana_public_api_client.api.product import get_all_products


async def main():
    async with KatanaClient() as client:
        response = await get_all_products.asyncio_detailed(client=client)
        products = response.parsed.data
        print(f"Found {len(products)} products")


asyncio.run(main())

TypeScript Client

npm install katana-openapi-client

import { KatanaClient } from 'katana-openapi-client';

const client = await KatanaClient.create();
const response = await client.get('/products');
const { data } = await response.json();
console.log(`Found ${data.length} products`);

MCP Server (Claude Desktop)

pip install katana-mcp-server

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "katana": {
      "command": "uvx",
      "args": ["katana-mcp-server"],
      "env": {
        "KATANA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuration

All packages support the same authentication methods:

Environment variable: KATANA_API_KEY
.env file: Create with KATANA_API_KEY=your-key
Direct parameter: Pass api_key to client constructor

# .env file
KATANA_API_KEY=your-api-key-here
KATANA_BASE_URL=https://api.katanamrp.com/v1  # Optional

API Coverage

All clients provide access to the complete Katana API. The canonical endpoint surface is the OpenAPI spec at docs/katana-openapi.yaml; the Python and TypeScript clients are generated from it, and the MCP server wraps a curated subset of high-level tools on top of the Python client.

Python / TypeScript clients — every operation in the spec, with generated types for all request and response models.
MCP server — a higher-level tool surface (search, modify, fulfill, verify, plus preview/apply pairs for write operations); the live tool list is exposed via the katana://help/tools resource.

Project Structure

katana-openapi-client/               # Monorepo root
├── pyproject.toml                   # Workspace configuration (uv)
├── uv.lock                          # Unified lock file
├── docs/
│   ├── katana-openapi.yaml          # OpenAPI 3.1.0 specification
│   ├── adr/                         # Shared architecture decisions
│   └── *.md                         # Shared documentation
├── katana_public_api_client/        # Python client package
│   ├── katana_client.py             # Resilient client with retries
│   ├── api/                         # Generated API modules
│   ├── models/                      # Generated data models
│   ├── models_pydantic/             # Generated pydantic models
│   └── docs/                        # Package documentation
├── katana_mcp_server/               # MCP server package
│   ├── src/katana_mcp/
│   │   ├── server.py                # FastMCP server
│   │   ├── tools/                   # MCP tools
│   │   ├── resources/               # MCP resources
│   │   └── typed_cache/             # SQLite-backed typed cache
│   └── docs/                        # Package documentation
└── packages/
    └── katana-client/               # TypeScript client package
        ├── src/
        │   ├── client.ts            # Resilient client
        │   └── generated/           # Generated SDK
        └── docs/                    # Package documentation

Documentation

Package Documentation

Each package has its own documentation in its docs/ directory:

Python Client Guide — usage, response helpers, pagination, retries
Python Client Cookbook — practical recipes
OpenAPI Spec Authoring — 3.1 conventions, generator/regen lockstep, breaking-change markers
MCP Server Architecture — MCP design patterns
MCP Server Development — development workflow
MCP Prefab UI — card builders and renderer pitfalls
MCP Typed Cache — SQLite cache, FTS5, soft-state filtering
TypeScript Client Guide — TypeScript usage

Architecture Decisions

Architecture Decision Records live under each package's docs/adr/ directory plus shared monorepo ADRs under docs/adr/. Each ADR directory has a README.md index that lists every ADR in that scope with its current status — those indexes are the canonical list and stay current as ADRs are added or superseded.

Shared / monorepo ADRs — cross-cutting decisions
Python client ADRs — client package decisions
MCP server ADRs — MCP package decisions
TypeScript client ADRs — TS package decisions

Shared Documentation

Contributing Guide — how to contribute
uv Usage Guide — package manager guide
Release Guide — release-please setup and release process

Development

Prerequisites

Python 3.12+ for Python packages
Node.js 18+ for TypeScript package
uv package manager (install)

Setup

# Clone repository
git clone https://github.com/dougborg/katana-openapi-client.git
cd katana-openapi-client

# Install all dependencies
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Create .env file
cp .env.example .env  # Add your KATANA_API_KEY

Common Commands

# Run all checks (lint, type-check, test)
uv run poe check

# Run tests
uv run poe test

# Format code
uv run poe format

# Regenerate Python client from OpenAPI spec
uv run poe regenerate-client

Commit Standards

Conventional commits drive per-package release-please versioning (bump type from the commit type; which package(s) bump from which paths the commit touches):

# Python client changes
git commit -m "feat(client): add new inventory helper"
git commit -m "fix(client): handle pagination edge case"

# MCP server changes
git commit -m "feat(mcp): add manufacturing order tools"
git commit -m "fix(mcp): improve error handling"

# Documentation only (no release)
git commit -m "docs: update README"

Use ! for breaking changes: feat(client)!: drop Python 3.11 support.

See RELEASE.md for details.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Metadata

Release files for katana-openapi-client 0.85.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for katana-openapi-client 0.85.0
File	Size	Uploaded
katana_openapi_client-0.85.0.tar.gz	3.0 MB	Sep 21, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for katana-openapi-client 0.85.0
File	Interpreter	ABI	Platform	Reset
katana_openapi_client-0.85.0-py3-none-any.whl 1.2 MB Sep 21, 2026	Python 3	none	any	Details

Total release size: 4.2 MB

Release files / katana_openapi_client-0.85.0.tar.gz

Download URL	katana_openapi_client-0.85.0.tar.gz
Size	3.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`75266fd8e4f52a6f312e2d6857ff07b4a69ef7f53b45dcc585ab8e125b8beed4`
BLAKE2b-256 checksum How to use checksums	`f6508c1fe40914fff3e32e8f00104a510055704d6d9be658ff5b5b3b3d193d05`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dougborg/katana-openapi-client
Publishing commit: github.com/dougborg/katana-openapi-client/tree/1e40d780a92dbed93b9261230eda5b090d5cfad5

Workflow

Publishing configuration: github.com/dougborg/katana-openapi-client/blob/1e40d780a92dbed93b9261230eda5b090d5cfad5/.github/workflows/publish.yml
Publishing logs: github.com/dougborg/katana-openapi-client/actions/runs/35658945561/attempts/1

Artifact

Subject: katana_openapi_client-0.85.0.tar.gz
SHA-256 checksum: 75266fd8e4f52a6f312e2d6857ff07b4a69ef7f53b45dcc585ab8e125b8beed4 Verifying attestations

Release files / katana_openapi_client-0.85.0-py3-none-any.whl

Download URL	katana_openapi_client-0.85.0-py3-none-any.whl
Size	1.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`5c5f06cb31d0c21329d4216c06d71a10cbd0dbf3b40bb4a96521b2ba8815407f`
BLAKE2b-256 checksum How to use checksums	`97dca3107d447ffd43f16c9be2f959929d21bb3e084248ebd2aebf2bea512cb6`
Upload date	Sep 21, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/dougborg/katana-openapi-client
Publishing commit: github.com/dougborg/katana-openapi-client/tree/1e40d780a92dbed93b9261230eda5b090d5cfad5

Workflow

Publishing configuration: github.com/dougborg/katana-openapi-client/blob/1e40d780a92dbed93b9261230eda5b090d5cfad5/.github/workflows/publish.yml
Publishing logs: github.com/dougborg/katana-openapi-client/actions/runs/35658945561/attempts/1

Artifact

Subject: katana_openapi_client-0.85.0-py3-none-any.whl
SHA-256 checksum: 5c5f06cb31d0c21329d4216c06d71a10cbd0dbf3b40bb4a96521b2ba8815407f Verifying attestations