Skip to content

README.md

Latest commit

 

History

History
278 lines (208 loc) · 9.56 KB

README.md

File metadata and controls

278 lines (208 loc) · 9.56 KB

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.

Python 3.12+ TypeScript OpenAPI 3.1.0 CI codecov

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:

Architecture Decisions

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

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

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

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

Shared/Monorepo ADRs (docs/adr/):

Shared Documentation

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.