feat(mcp): migrate to StockTrim architecture with unified item creation

Implements Phase 1 of StockTrim architecture migration, establishing
production-proven patterns from the sister project.

**Architecture Changes:**
- Convert ServerContext to @DataClass pattern
- Add services layer with get_services() dependency injection helper
- Organize tools into foundation/ and workflows/ two-tier structure
- Add ItemType enum matching Katana API discriminator

**New Services Layer:**
- services/dependencies.py: Services dataclass + get_services() helper
- Provides clean DI pattern for accessing KatanaClient
- Documents which helpers exist vs need generated API

**Tool Organization:**
- foundation/items.py: Unified item management (search + create)
- foundation/inventory.py: Stock operations (migrated from tools/)
- workflows/: Empty for now (Phase 3 implementation)

**New Unified Item Interface:**
- create_item: Single tool for products, materials, and services
- Type-aware routing based on ItemType discriminator
- Simplified interface with common fields
- Handles API differences (UNSET conversion, variant models)
- search_items: Renamed from search_products for consistency

**Breaking Changes:**
- Import paths changed: tools.inventory → tools.foundation.inventory
- Import paths changed: tools.inventory → tools.foundation.items
- search_products renamed to search_items

**Testing:**
- Updated all test imports to new structure
- Fixed version assertions (0.1.0a1 → 0.3.0)
- All 1663 tests passing
- MyPy type checking passed
- Ruff linting passed

**Files Changed:**
- 7 new files (services, foundation, workflows structure)
- 5 modified files (server.py, tools/__init__.py, tests)
- 1 renamed file (inventory.py → foundation/inventory.py)

**Benefits:**
- Matches production-proven StockTrim patterns
- Cleaner dependency injection with get_services()
- Better organization for scaling to more tools
- Unified item interface - huge UX win for users

Closes Phase 1 of StockTrim migration (#112)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Doug Borg

katana_mcp_server/src/katana_mcp/server.py

@@ -14,6 +14,7 @@
 import os
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
 from typing import Any
 
 from dotenv import load_dotenv
@@ -30,16 +31,18 @@
 logger = logging.getLogger(__name__)
 
 
+@dataclass
 class ServerContext:
-    """Context object that holds the KatanaClient instance for the server lifespan."""
+    """Context object that holds the KatanaClient instance for the server lifespan.
 
-    def __init__(self, client: KatanaClient):
-        """Initialize server context with KatanaClient.
+    This dataclass provides type-safe access to the KatanaClient throughout
+    the server lifecycle, following the StockTrim architecture pattern.
 
-        Args:
-            client: Initialized KatanaClient instance
-        """
-        self.client = client
+    Attributes:
+        client: Initialized KatanaClient instance for API operations
+    """
+
+    client: KatanaClient
 
 
 @asynccontextmanager
@@ -95,7 +98,6 @@ async def lifespan(server: FastMCP) -> AsyncIterator[ServerContext]:
             logger.info("KatanaClient initialized successfully")
 
             # Create context with client for tools to access
-            # Note: client is KatanaClient but mypy sees it as AuthenticatedClient
             context = ServerContext(client=client)  # type: ignore[arg-type]
 
             # Yield context to server - tools can access via lifespan dependency

katana_mcp_server/src/katana_mcp/services/__init__.py

@@ -0,0 +1,12 @@
+"""Services layer for dependency injection in MCP tools.
+
+This module provides clean dependency injection patterns for accessing
+the KatanaClient and other services from MCP tool contexts.
+"""
+
+from .dependencies import Services, get_services
+
+__all__ = [
+    "Services",
+    "get_services",
+]

katana_mcp_server/src/katana_mcp/services/dependencies.py

@@ -0,0 +1,71 @@
+"""Dependency injection helpers for MCP tools.
+
+This module provides a clean pattern for extracting services from the MCP context,
+following the StockTrim architecture pattern.
+"""
+
+from dataclasses import dataclass
+
+from fastmcp import Context
+
+from katana_public_api_client import KatanaClient
+
+
+@dataclass
+class Services:
+    """Container for services available to tools.
+
+    This dataclass provides type-safe access to services that tools need.
+    Currently contains only the KatanaClient, but can be extended with
+    additional services as needed.
+
+    Attributes:
+        client: The KatanaClient instance for API operations
+    """
+
+    client: KatanaClient
+
+
+def get_services(context: Context) -> Services:
+    """Extract services from MCP context.
+
+    This helper provides a single extraction point for all service dependencies,
+    making tool implementations cleaner and more testable.
+
+    Usage in tools:
+        ```python
+        services = get_services(context)
+
+        # Use existing helpers (variants, products, materials, services, inventory)
+        products = await services.client.products.list()
+
+        # For other endpoints (purchase_orders, sales_orders, etc), use generated API:
+        from katana_public_api_client.api.purchase_order import (
+            create_purchase_order,
+        )
+
+        po_response = await create_purchase_order.asyncio_detailed(
+            client=services.client, json_body=...
+        )
+        ```
+
+    Note:
+        Only a limited set of helpers currently exist on KatanaClient:
+        - variants
+        - products
+        - materials
+        - services
+        - inventory
+
+        For other endpoints (purchase_orders, manufacturing_orders, sales_orders),
+        you must use the generated API modules directly from katana_public_api_client.api.*
+        or implement your own helper methods.
+
+    Args:
+        context: FastMCP context containing lifespan_context with ServerContext
+
+    Returns:
+        Services: Dataclass containing client and other services
+    """
+    server_context = context.request_context.lifespan_context  # type: ignore[attr-defined]
+    return Services(client=server_context.client)  # type: ignore[attr-defined]

katana_mcp_server/src/katana_mcp/tools/__init__.py

@@ -1,32 +1,42 @@
 """MCP tools for Katana Manufacturing ERP.
 
-This module contains tool implementations that provide actions with side effects
-for interacting with the Katana API.
+This module contains tool implementations organized into foundation and workflow layers.
+
+Tool Organization:
+-----------------
+- **Foundation tools** (tools/foundation/): Low-level operations mapping to API endpoints
+  - items.py: Search and manage items (variants, products, materials, services)
+  - inventory.py: Stock checking, low stock alerts, inventory operations
+
+- **Workflow tools** (tools/workflows/): High-level intent-based operations
+  - Coming in Phase 3
 
 Tool Registration Pattern:
 --------------------------
 Each tool module exports a register_tools(mcp) function that registers its tools
 with the FastMCP instance. This avoids circular imports.
 
 When adding new tool modules:
-1. Create the new module (e.g., sales_orders.py)
+1. Create the new module (e.g., foundation/purchase_orders.py)
 2. Define tools as regular async functions (no decorators)
 3. Add a register_tools(mcp: FastMCP) function that calls mcp.tool() on each function
-4. Import and call the registration function from server.py
+4. Import and call the registration function from foundation/__init__.py or workflows/__init__.py
 """
 
 from fastmcp import FastMCP
 
-from .inventory import register_tools as register_inventory_tools
+from .foundation import register_all_foundation_tools
+from .workflows import register_all_workflow_tools
 
 
 def register_all_tools(mcp: FastMCP) -> None:
-    """Register all tools from all modules.
+    """Register all tools from all modules (foundation + workflow).
 
     Args:
         mcp: FastMCP server instance to register tools with
     """
-    register_inventory_tools(mcp)
+    register_all_foundation_tools(mcp)
+    register_all_workflow_tools(mcp)
 
 
 __all__ = [

katana_mcp_server/src/katana_mcp/tools/foundation/__init__.py

@@ -0,0 +1,29 @@
+"""Foundation tools for Katana MCP Server.
+
+Foundation tools are low-level operations that map closely to API endpoints.
+They provide granular control and are the building blocks for workflow tools.
+
+Organization:
+- items.py: Search and manage items (variants, products, materials, services)
+- inventory.py: Stock checking, low stock alerts, inventory operations
+"""
+
+from fastmcp import FastMCP
+
+from .inventory import register_tools as register_inventory_tools
+from .items import register_tools as register_items_tools
+
+
+def register_all_foundation_tools(mcp: FastMCP) -> None:
+    """Register all foundation tools from all modules.
+
+    Args:
+        mcp: FastMCP server instance to register tools with
+    """
+    register_items_tools(mcp)
+    register_inventory_tools(mcp)
+
+
+__all__ = [
+    "register_all_foundation_tools",
+]

…server/src/katana_mcp/tools/inventory.py …katana_mcp/tools/foundation/inventory.pykatana_mcp_server/src/katana_mcp/tools/inventory.py renamed to katana_mcp_server/src/katana_mcp/tools/foundation/inventory.py katana_mcp_server/src/katana_mcp/tools/inventory.py renamed to katana_mcp_server/src/katana_mcp/tools/foundation/inventory.py

@@ -1,4 +1,8 @@
-"""Inventory management tools for Katana MCP Server."""
+"""Inventory management tools for Katana MCP Server.
+
+Foundation tools for checking stock levels, monitoring low stock,
+and managing inventory operations.
+"""
 
 from __future__ import annotations
 
@@ -7,6 +11,8 @@
 from fastmcp import Context, FastMCP
 from pydantic import BaseModel, Field
 
+from katana_mcp.services import get_services
+
 logger = logging.getLogger(__name__)
 
 # ============================================================================
@@ -52,10 +58,9 @@ async def _check_inventory_impl(
     logger.info(f"Checking inventory for SKU: {request.sku}")
 
     try:
-        # Access KatanaClient from lifespan context
-        server_context = context.request_context.lifespan_context  # type: ignore[attr-defined]
-        client = server_context.client  # type: ignore[attr-defined]
-        product = await client.inventory.check_stock(request.sku)
+        # Access services using helper
+        services = get_services(context)
+        product = await services.client.inventory.check_stock(request.sku)
 
         if not product:
             # Product not found - return zero stock
@@ -166,10 +171,11 @@ async def _list_low_stock_items_impl(
     )
 
     try:
-        # Access KatanaClient from lifespan context
-        server_context = context.request_context.lifespan_context  # type: ignore[attr-defined]
-        client = server_context.client  # type: ignore[attr-defined]
-        products = await client.inventory.list_low_stock(threshold=request.threshold)
+        # Access services using helper
+        services = get_services(context)
+        products = await services.client.inventory.list_low_stock(
+            threshold=request.threshold
+        )
 
         # Limit results
         limited_products = products[: request.limit]
@@ -224,123 +230,6 @@ async def list_low_stock_items(
     return await _list_low_stock_items_impl(request, context)
 
 
-# ============================================================================
-# Tool 3: search_products
-# ============================================================================
-
-
-class SearchProductsRequest(BaseModel):
-    """Request model for searching products."""
-
-    query: str = Field(..., description="Search query (name, SKU, etc.)")
-    limit: int = Field(default=20, description="Maximum results to return")
-
-
-class ProductInfo(BaseModel):
-    """Product information."""
-
-    id: int
-    sku: str
-    name: str
-    is_sellable: bool
-    stock_level: int | None = None
-
-
-class SearchProductsResponse(BaseModel):
-    """Response containing search results."""
-
-    products: list[ProductInfo]
-    total_count: int
-
-
-async def _search_products_impl(
-    request: SearchProductsRequest, context: Context
-) -> SearchProductsResponse:
-    """Implementation of search_products tool.
-
-    Args:
-        request: Request with search query and limit
-        context: Server context with KatanaClient
-
-    Returns:
-        List of matching product variants with extended names
-
-    Raises:
-        ValueError: If query is empty or limit is invalid
-        Exception: If API call fails
-    """
-    if not request.query or not request.query.strip():
-        raise ValueError("Search query cannot be empty")
-    if request.limit <= 0:
-        raise ValueError("Limit must be positive")
-
-    logger.info(
-        f"Searching variants for query: '{request.query}' (limit={request.limit})"
-    )
-
-    try:
-        # Access KatanaClient from lifespan context
-        server_context = context.request_context.lifespan_context  # type: ignore[attr-defined]
-        client = server_context.client  # type: ignore[attr-defined]
-
-        # Search variants (which have SKUs) with parent product/material info
-        variants = await client.variants.search(request.query, limit=request.limit)
-
-        # Build response - format names matching Katana UI
-        products_info = []
-        for variant in variants:
-            # Build variant name using domain model method
-            # Format: "Product Name / Config1 / Config2 / ..."
-            name = variant.get_display_name()
-
-            # Determine if variant is sellable (products are sellable, materials are not)
-            is_sellable = variant.type_ == "product" if variant.type_ else False
-
-            products_info.append(
-                ProductInfo(
-                    id=variant.id,
-                    sku=variant.sku or "",
-                    name=name,
-                    is_sellable=is_sellable,
-                    stock_level=None,  # Variants don't have stock_level directly
-                )
-            )
-
-        response = SearchProductsResponse(
-            products=products_info,
-            total_count=len(products_info),
-        )
-
-        logger.info(f"Found {response.total_count} variants matching '{request.query}'")
-        return response
-
-    except Exception as e:
-        logger.error(f"Failed to search products for query '{request.query}': {e}")
-        raise
-
-
-async def search_products(
-    request: SearchProductsRequest, context: Context
-) -> SearchProductsResponse:
-    """Search for products by name or SKU.
-
-    Performs a search across product catalog to find items matching
-    the search query. Useful for quick product lookup.
-
-    Args:
-        request: Request with search query and limit
-        context: Server context with KatanaClient
-
-    Returns:
-        List of matching products with basic info
-
-    Example:
-        Request: {"query": "widget", "limit": 10}
-        Returns: {"products": [...], "total_count": 5}
-    """
-    return await _search_products_impl(request, context)
-
-
 def register_tools(mcp: FastMCP) -> None:
     """Register all inventory tools with the FastMCP instance.
 
@@ -349,4 +238,3 @@ def register_tools(mcp: FastMCP) -> None:
     """
     mcp.tool()(check_inventory)
     mcp.tool()(list_low_stock_items)
-    mcp.tool()(search_products)