{"id":32693086,"url":"https://github.com/dougborg/katana-openapi-client","last_synced_at":"2026-05-26T20:01:20.390Z","repository":{"id":304695038,"uuid":"1019595633","full_name":"dougborg/katana-openapi-client","owner":"dougborg","description":"Modern TypeScript and Python Katana Manufacturing MRP API clients with automatic retries, rate limiting, and smart pagination. Now with an alpha MCP implementation!","archived":false,"fork":false,"pushed_at":"2026-05-26T16:54:12.000Z","size":25390,"stargazers_count":2,"open_issues_count":128,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T17:32:07.534Z","etag":null,"topics":["client","katana","mcp-server","mrp","openapi-specification","openapi3-1","python3","typescript"],"latest_commit_sha":null,"homepage":"https://dougborg.github.io/katana-openapi-client/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dougborg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["dougborg"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-07-14T15:13:01.000Z","updated_at":"2026-05-26T16:45:54.000Z","dependencies_parsed_at":"2025-08-18T20:24:53.154Z","dependency_job_id":"38abb5fc-f9a0-488d-ace2-20305d2041ce","html_url":"https://github.com/dougborg/katana-openapi-client","commit_stats":null,"previous_names":["dougborg/katana-open-api-client","dougborg/katana-openapi-client"],"tags_count":221,"template":false,"template_full_name":null,"purl":"pkg:github/dougborg/katana-openapi-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fkatana-openapi-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fkatana-openapi-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fkatana-openapi-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fkatana-openapi-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dougborg","download_url":"https://codeload.github.com/dougborg/katana-openapi-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dougborg%2Fkatana-openapi-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33536659,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","katana","mcp-server","mrp","openapi-specification","openapi3-1","python3","typescript"],"created_at":"2025-11-01T16:03:00.183Z","updated_at":"2026-05-26T20:01:20.268Z","avatar_url":"https://github.com/dougborg.png","language":"Python","funding_links":["https://github.com/sponsors/dougborg"],"categories":[],"sub_categories":[],"readme":"# Katana Manufacturing ERP - API Ecosystem\n\nMulti-language client ecosystem for the\n[Katana Manufacturing ERP API](https://help.katanamrp.com/api). Production-ready clients\nwith automatic resilience, rate limiting, and pagination.\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![TypeScript](https://img.shields.io/badge/typescript-5.0+-blue.svg)](https://www.typescriptlang.org/)\n[![OpenAPI 3.1.0](https://img.shields.io/badge/OpenAPI-3.1.0-green.svg)](https://spec.openapis.org/oas/v3.1.0)\n[![CI](https://github.com/dougborg/katana-openapi-client/actions/workflows/ci.yml/badge.svg)](https://github.com/dougborg/katana-openapi-client/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/dougborg/katana-openapi-client/branch/main/graph/badge.svg)](https://codecov.io/gh/dougborg/katana-openapi-client)\n\n## Packages\n\n| Package                                            | Language   | Version                                                                                                                      | Description                                              |\n| -------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |\n| [katana-openapi-client](katana_public_api_client/) | Python     | [![PyPI](https://img.shields.io/pypi/v/katana-openapi-client.svg?label=)](https://pypi.org/project/katana-openapi-client/)   | Full-featured API client with transport-layer resilience |\n| [katana-mcp-server](katana_mcp_server/)            | Python     | [![PyPI](https://img.shields.io/pypi/v/katana-mcp-server.svg?label=)](https://pypi.org/project/katana-mcp-server/)           | Model Context Protocol server for AI assistants          |\n| [katana-openapi-client](packages/katana-client/)   | TypeScript | [![npm](https://img.shields.io/npm/v/katana-openapi-client.svg?label=)](https://www.npmjs.com/package/katana-openapi-client) | TypeScript/JavaScript client with full type safety       |\n\n## Features Comparison\n\n| Feature             | Python Client   | TypeScript Client | MCP Server              |\n| ------------------- | --------------- | ----------------- | ----------------------- |\n| Automatic retries   | Yes             | Yes               | Yes (via Python client) |\n| Rate limit handling | Yes             | Yes               | Yes                     |\n| Auto-pagination     | Yes             | Yes               | Yes                     |\n| Type safety         | Full (Pydantic) | Full (TypeScript) | Full (Pydantic)         |\n| Sync + Async        | Yes             | Async only        | Async only              |\n| Browser support     | No              | Yes               | No                      |\n| AI Integration      | -               | -                 | Claude, Cursor, etc.    |\n\n## Quick Start\n\n### Python Client\n\n```bash\npip install katana-openapi-client\n```\n\n```python\nimport asyncio\nfrom katana_public_api_client import KatanaClient\nfrom katana_public_api_client.api.product import get_all_products\n\nasync def main():\n    async with KatanaClient() as client:\n        response = await get_all_products.asyncio_detailed(client=client)\n        products = response.parsed.data\n        print(f\"Found {len(products)} products\")\n\nasyncio.run(main())\n```\n\n### TypeScript Client\n\n```bash\nnpm install katana-openapi-client\n```\n\n```typescript\nimport { KatanaClient } from 'katana-openapi-client';\n\nconst client = await KatanaClient.create();\nconst response = await client.get('/products');\nconst { data } = await response.json();\nconsole.log(`Found ${data.length} products`);\n```\n\n### MCP Server (Claude Desktop)\n\n```bash\npip install katana-mcp-server\n```\n\nAdd to Claude Desktop config\n(`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"katana\": {\n      \"command\": \"uvx\",\n      \"args\": [\"katana-mcp-server\"],\n      \"env\": {\n        \"KATANA_API_KEY\": \"your-api-key-here\"\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\nAll packages support the same authentication methods:\n\n1. **Environment variable**: `KATANA_API_KEY`\n1. **`.env` file**: Create with `KATANA_API_KEY=your-key`\n1. **Direct parameter**: Pass `api_key` to client constructor\n\n```bash\n# .env file\nKATANA_API_KEY=your-api-key-here\nKATANA_BASE_URL=https://api.katanamrp.com/v1  # Optional\n```\n\n## API Coverage\n\nAll clients provide access to the complete Katana API. The canonical endpoint surface is\nthe OpenAPI spec at [`docs/katana-openapi.yaml`](docs/katana-openapi.yaml); the Python\nand TypeScript clients are generated from it, and the MCP server wraps a curated subset\nof high-level tools on top of the Python client.\n\n- **Python / TypeScript clients** — every operation in the spec, with generated types\n  for all request and response models.\n- **MCP server** — a higher-level tool surface (search, modify, fulfill, verify, plus\n  preview/apply pairs for write operations); the live tool list is exposed via the\n  `katana://help/tools` resource.\n\n## Project Structure\n\n```text\nkatana-openapi-client/               # Monorepo root\n├── pyproject.toml                   # Workspace configuration (uv)\n├── uv.lock                          # Unified lock file\n├── docs/\n│   ├── katana-openapi.yaml          # OpenAPI 3.1.0 specification\n│   ├── adr/                         # Shared architecture decisions\n│   └── *.md                         # Shared documentation\n├── katana_public_api_client/        # Python client package\n│   ├── katana_client.py             # Resilient client with retries\n│   ├── api/                         # Generated API modules\n│   ├── models/                      # Generated data models\n│   ├── models_pydantic/             # Generated pydantic models\n│   └── docs/                        # Package documentation\n├── katana_mcp_server/               # MCP server package\n│   ├── src/katana_mcp/\n│   │   ├── server.py                # FastMCP server\n│   │   ├── tools/                   # MCP tools\n│   │   ├── resources/               # MCP resources\n│   │   └── typed_cache/             # SQLite-backed typed cache\n│   └── docs/                        # Package documentation\n└── packages/\n    └── katana-client/               # TypeScript client package\n        ├── src/\n        │   ├── client.ts            # Resilient client\n        │   └── generated/           # Generated SDK\n        └── docs/                    # Package documentation\n```\n\n## Documentation\n\n### Package Documentation\n\nEach package has its own documentation in its `docs/` directory:\n\n- **[Python Client Guide](katana_public_api_client/docs/guide.md)** — usage, response\n  helpers, pagination, retries\n- **[Python Client Cookbook](katana_public_api_client/docs/cookbook.md)** — practical\n  recipes\n- **[OpenAPI Spec Authoring](katana_public_api_client/docs/spec-authoring.md)** — 3.1\n  conventions, generator/regen lockstep, breaking-change markers\n- **[MCP Server Architecture](katana_mcp_server/docs/architecture.md)** — MCP design\n  patterns\n- **[MCP Server Development](katana_mcp_server/docs/development.md)** — development\n  workflow\n- **[MCP Prefab UI](katana_mcp_server/docs/prefab/README.md)** — card builders and\n  renderer pitfalls\n- **[MCP Typed Cache](katana_mcp_server/docs/typed_cache/README.md)** — SQLite cache,\n  FTS5, soft-state filtering\n- **[TypeScript Client Guide](packages/katana-client/docs/guide.md)** — TypeScript usage\n\n### Architecture Decisions\n\nArchitecture Decision Records live under each package's `docs/adr/` directory plus\nshared monorepo ADRs under `docs/adr/`. Each ADR directory has a `README.md` index that\nlists every ADR in that scope with its current status — those indexes are the canonical\nlist and stay current as ADRs are added or superseded.\n\n- **[Shared / monorepo ADRs](docs/adr/README.md)** — cross-cutting decisions\n- **[Python client ADRs](katana_public_api_client/docs/adr/README.md)** — client package\n  decisions\n- **[MCP server ADRs](katana_mcp_server/docs/adr/README.md)** — MCP package decisions\n- **[TypeScript client ADRs](packages/katana-client/docs/adr/README.md)** — TS package\n  decisions\n\n### Shared Documentation\n\n- **[Contributing Guide](docs/CONTRIBUTING.md)** — how to contribute\n- **[uv Usage Guide](docs/UV_USAGE.md)** — package manager guide\n- **[Monorepo Release Guide](docs/MONOREPO_SEMANTIC_RELEASE.md)** — semantic release\n  setup\n\n## Development\n\n### Prerequisites\n\n- **Python 3.12+** for Python packages\n- **Node.js 18+** for TypeScript package\n- **uv** package manager\n  ([install](https://docs.astral.sh/uv/getting-started/installation/))\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/dougborg/katana-openapi-client.git\ncd katana-openapi-client\n\n# Install all dependencies\nuv sync --all-extras\n\n# Install pre-commit hooks\nuv run pre-commit install\n\n# Create .env file\ncp .env.example .env  # Add your KATANA_API_KEY\n```\n\n### Common Commands\n\n```bash\n# Run all checks (lint, type-check, test)\nuv run poe check\n\n# Run tests\nuv run poe test\n\n# Format code\nuv run poe format\n\n# Regenerate Python client from OpenAPI spec\nuv run poe regenerate-client\n```\n\n### Commit Standards\n\nThis project uses semantic-release with conventional commits:\n\n```bash\n# Python client changes\ngit commit -m \"feat(client): add new inventory helper\"\ngit commit -m \"fix(client): handle pagination edge case\"\n\n# MCP server changes\ngit commit -m \"feat(mcp): add manufacturing order tools\"\ngit commit -m \"fix(mcp): improve error handling\"\n\n# TypeScript client changes\ngit commit -m \"feat(ts): add browser support\"\n\n# Documentation only (no release)\ngit commit -m \"docs: update README\"\n```\n\nSee [MONOREPO_SEMANTIC_RELEASE.md](docs/MONOREPO_SEMANTIC_RELEASE.md) for details.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdougborg%2Fkatana-openapi-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdougborg%2Fkatana-openapi-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdougborg%2Fkatana-openapi-client/lists"}