Katana Openapi Client

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

Python 3.12+ TypeScript OpenAPI 3.1.0 CI codecov

Packages

Package	Language	Version	Description
katana-openapi-client	Python	PyPI	Full-featured API client with transport-layer resilience
katana-mcp-server	Python	PyPI	Model Context Protocol server for AI assistants
katana-openapi-client	TypeScript	npm	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:

1. Environment variable: KATANA_API_KEY
2. .env file: Create with KATANA_API_KEY=your-key
3. 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.