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

Category	Endpoints	Description
Products & Inventory	25+	Products, variants, materials, stock levels
Orders	20+	Sales orders, purchase orders, fulfillment
Manufacturing	15+	BOMs, manufacturing orders, operations
Business Relations	10+	Customers, suppliers, addresses
Configuration	6+	Locations, webhooks, custom fields

Total: 76+ endpoints with 150+ fully-typed data models

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 (76+)
│   ├── models/                      # Generated data models (150+)
│   └── docs/                        # Package documentation
├── katana_mcp_server/               # MCP server package
│   ├── src/katana_mcp/
│   │   ├── server.py                # FastMCP server
│   │   ├── tools/                   # MCP tools (12)
│   │   └── resources/               # MCP resources (5)
│   └── 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 - Complete usage guide
• Python Client Cookbook - Practical recipes
• MCP Server Architecture - MCP design patterns
• MCP Server Development - Development guide
• TypeScript Client Guide - TypeScript usage

Architecture Decisions

Key architectural decisions are documented as ADRs (Architecture Decision Records):

Python Client ADRs (katana_public_api_client/docs/adr/):

• ADR-001: Transport-Layer Resilience
• ADR-002: OpenAPI Code Generation
• ADR-003: Transparent Pagination
• ADR-006: Response Unwrapping

MCP Server ADRs (katana_mcp_server/docs/adr/):

• ADR-010: MCP Server Architecture

TypeScript Client ADRs (packages/katana-client/docs/adr/):

• ADR-001: Composable Fetch Wrappers
• ADR-002: Hey API Code Generation
• ADR-003: Biome for Linting

Shared/Monorepo ADRs (docs/adr/):

• ADR-009: Migrate to uv

Shared Documentation

• Contributing Guide - How to contribute
• uv Usage Guide - Package manager guide
• Monorepo Release Guide - Semantic release setup

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

This project uses semantic-release with conventional commits:

# 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"

# TypeScript client changes
git commit -m "feat(ts): add browser support"

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

See MONOREPO_SEMANTIC_RELEASE.md for details.

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.