convez.ai
MCP ServerIntegração & APIsAvançado
dougborg

Katana Manufacturing ERP - Cliente API OpenAPI

dougborg/katana-openapi-client

Clientes API resilientes para Katana ERP com MCP server para IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Ecossistema de clientes multilingues para a API do Katana Manufacturing ERP, com suporte Python e TypeScript. Inclui implementação MCP para integração com assistentes de IA como Claude, com features como retentativas automáticas, rate limiting inteligente e paginação automática.

Instalação

$npx convez-ai dougborg/katana-openapi-client

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
5
Acompanhando
0
Saúde
85%
Último commit
há 3 dias
Versão
mcp-v0.122.0
Issues abertas
111
Contribuidores
5

Casos de uso

  • Integração com sistemas de manufatura e gestão de produção
  • Automação de fluxos de trabalho em ERP via IA
  • Desenvolvimento de aplicações que consomem API de ERP

Veredito

Solução madura e bem-arquitetada para integração com ERP Katana. O suporte MCP é valor agregado relevante para automação com IA, mas o público é restrito a usuários específicos da plataforma Katana.

README

A tradução para o português deste README ainda está na fila.

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

PackageLanguageVersionDescription
katana-openapi-clientPythonPyPIFull-featured API client with transport-layer resilience
katana-mcp-serverPythonPyPIModel Context Protocol server for AI assistants
katana-openapi-clientTypeScriptnpmTypeScript/JavaScript client with full type safety

Features Comparison

FeaturePython ClientTypeScript ClientMCP Server
Automatic retriesYesYesYes (via Python client)
Rate limit handlingYesYesYes
Auto-paginationYesYesYes
Type safetyFull (Pydantic)Full (TypeScript)Full (Pydantic)
Sync + AsyncYesAsync onlyAsync only
Browser supportNoYesNo
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:

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 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.

Ver o original no GitHub

Bom para

Relacionados