feat(mcp): implement FastMCP elicitation pattern for destructive operations (#173)

* Initial plan

* feat(mcp): add FastMCP elicitation pattern to destructive operations

- Added ConfirmationSchema for user confirmation via elicit()
- Implemented ctx.elicit() in create_purchase_order tool
- Implemented ctx.elicit() in receive_purchase_order tool
- Implemented ctx.elicit() in create_manufacturing_order tool
- Implemented ctx.elicit() in fulfill_order tool (both manufacturing and sales)
- Updated test fixtures to mock elicit() behavior
- Fixed type narrowing for elicitation results

Co-authored-by: dougborg <1261222+dougborg@users.noreply.github.com>

* test(mcp): fix wrapper test to call implementation directly

The wrapper function with @unpack_pydantic_params expects unpacked args from FastMCP,
so tests should call the implementation function directly.

Co-authored-by: dougborg <1261222+dougborg@users.noreply.github.com>

* chore: configure yamllint with 120 char line length

- Created .yamllint.yml config file
- Set line-length max to 120 characters
- Ignore .github/ directory (workflow files)
- Ignore docs/katana-openapi.yaml (OpenAPI spec)
- Updated pyproject.toml to match new line length limit
- All yamllint checks now pass

Co-authored-by: dougborg <1261222+dougborg@users.noreply.github.com>

* refactor(mcp): extract ConfirmationSchema to shared module

- Created katana_mcp/tools/schemas.py for shared Pydantic schemas
- Moved ConfirmationSchema from 3 separate files to shared location
- Updated imports in purchase_orders.py, manufacturing_orders.py, and orders.py
- Fixes DRY principle violation identified in PR review

This ensures consistency and makes future changes easier to manage.

Co-authored-by: dougborg <1261222+dougborg@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: dougborg <1261222+dougborg@users.noreply.github.com>

Author: Copilot

.github/FUNDING.yml

@@ -1,7 +1,6 @@
 # These are supported funding model platforms
 
-github:
-  - @dougborg
+github: [dougborg]
 patreon: # Replace with a single Patreon username
 open_collective: # Replace with a single Open Collective username
 ko_fi: # Replace with a single Ko-fi username

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -58,7 +58,9 @@ body:
     id: terms
     attributes:
       label: Code of Conduct
-      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/dougborg/katana-open-api-client/blob/main/CODE_OF_CONDUCT.md)
+      description: >-
+        By submitting this issue, you agree to follow our
+        [Code of Conduct](https://github.com/dougborg/katana-open-api-client/blob/main/CODE_OF_CONDUCT.md)
       options:
         - label: I agree to follow this project's Code of Conduct
           required: true

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -43,7 +43,9 @@ body:
     id: terms
     attributes:
       label: Code of Conduct
-      description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/dougborg/katana-open-api-client/blob/main/CODE_OF_CONDUCT.md)
+      description: >-
+        By submitting this issue, you agree to follow our
+        [Code of Conduct](https://github.com/dougborg/katana-open-api-client/blob/main/CODE_OF_CONDUCT.md)
       options:
         - label: I agree to follow this project's Code of Conduct
           required: true

.github/dependabot.yml

@@ -1,5 +1,6 @@
 # Dependabot configuration for automated dependency updates
-# See: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+# See:
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 #
 # NOTE: Python dependency updates are currently disabled because this project uses uv
 # for package management (see ADR-009), and Dependabot does not yet support the uv

.github/workflows/copilot-setup-steps.yml

@@ -20,7 +20,10 @@ jobs:
     # Set the permissions to the lowest permissions possible needed for your steps.
     # Copilot will be given its own token for its operations.
     permissions:
-      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      # If you want to clone the repository as part of your setup steps, for example
+      # to install dependencies, you'll need the `contents: read` permission. If you
+      # don't clone the repository in your setup steps, Copilot will do this for you
+      # automatically after the steps complete.
       contents: read
 
     # You can define any steps you want, and they will run before the agent starts.

.github/workflows/release.yml

@@ -73,8 +73,11 @@ jobs:
       - name: Check for client changes
         id: check
         run: |
-          # Check if there are any commits with (client) scope or no scope since last client release
-          if git log $(git describe --tags --abbrev=0 --match="client-v*" 2>/dev/null || echo "HEAD~10")..HEAD --pretty=format:"%s" | grep -qE '^(feat|fix|perf)(\(client\))?:'; then
+          # Check if there are any commits with (client) scope or no scope since last
+          # client release
+          if git log $(git describe --tags --abbrev=0 --match="client-v*" 2>/dev/null || \
+            echo "HEAD~10")..HEAD --pretty=format:"%s" | \
+            grep -qE '^(feat|fix|perf)(\(client\))?:'; then
             echo "has_changes=true" >> $GITHUB_OUTPUT
           else
             echo "has_changes=false" >> $GITHUB_OUTPUT
@@ -89,11 +92,17 @@ jobs:
           verbosity: 2
 
       - name: Build client package
-        if: (steps.release.outcome == 'success' && steps.release.outputs.released == 'true') || inputs.force_publish_client == true
+        if: >-
+          (steps.release.outcome == 'success' &&
+          steps.release.outputs.released == 'true') ||
+          inputs.force_publish_client == true
         run: uv build
 
       - name: Upload client build artifacts
-        if: (steps.release.outcome == 'success' && steps.release.outputs.released == 'true') || inputs.force_publish_client == true
+        if: >-
+          (steps.release.outcome == 'success' &&
+          steps.release.outputs.released == 'true') ||
+          inputs.force_publish_client == true
         uses: actions/upload-artifact@v5
         with:
           name: client-dist
@@ -132,7 +141,9 @@ jobs:
         id: check
         run: |
           # Check if there are any commits with (mcp) scope since last mcp release
-          if git log $(git describe --tags --abbrev=0 --match="mcp-v*" 2>/dev/null || echo "HEAD~10")..HEAD --pretty=format:"%s" | grep -qE '^(feat|fix|perf)\(mcp\):'; then
+          if git log $(git describe --tags --abbrev=0 --match="mcp-v*" 2>/dev/null || \
+            echo "HEAD~10")..HEAD --pretty=format:"%s" | \
+            grep -qE '^(feat|fix|perf)\(mcp\):'; then
             echo "has_changes=true" >> $GITHUB_OUTPUT
           else
             echo "has_changes=false" >> $GITHUB_OUTPUT
@@ -148,11 +159,17 @@ jobs:
           directory: katana_mcp_server
 
       - name: Build MCP package
-        if: (steps.release.outcome == 'success' && steps.release.outputs.released == 'true') || inputs.force_publish_mcp == true
+        if: >-
+          (steps.release.outcome == 'success' &&
+          steps.release.outputs.released == 'true') ||
+          inputs.force_publish_mcp == true
         run: cd katana_mcp_server && uv build
 
       - name: Upload MCP build artifacts
-        if: (steps.release.outcome == 'success' && steps.release.outputs.released == 'true') || inputs.force_publish_mcp == true
+        if: >-
+          (steps.release.outcome == 'success' &&
+          steps.release.outputs.released == 'true') ||
+          inputs.force_publish_mcp == true
         uses: actions/upload-artifact@v5
         with:
           name: mcp-dist

.github/workflows/update-mcp-dependency.yml

@@ -28,22 +28,22 @@ jobs:
         run: |
           # Get the most recent client-v* tag
           LATEST_CLIENT_TAG=$(git tag --list 'client-v*' --sort=-version:refname | head -n 1)
-          
+
           if [ -z "$LATEST_CLIENT_TAG" ]; then
             echo "No client tags found"
             echo "has_release=false" >> $GITHUB_OUTPUT
             exit 0
           fi
-          
+
           # Extract version from tag (client-v0.28.0 -> 0.28.0)
           CLIENT_VERSION="${LATEST_CLIENT_TAG#client-v}"
           echo "client_version=$CLIENT_VERSION" >> $GITHUB_OUTPUT
-          
+
           # Check if this tag was created in the last workflow run
           # Get the timestamp of the tag
           TAG_DATE=$(git log -1 --format=%ct "$LATEST_CLIENT_TAG")
           WORKFLOW_DATE=$(date -d "${{ github.event.workflow_run.created_at }}" +%s)
-          
+
           # If tag is newer than workflow start (created during the workflow)
           if [ "$TAG_DATE" -ge "$WORKFLOW_DATE" ]; then
             echo "New client release detected: $CLIENT_VERSION"
@@ -59,9 +59,9 @@ jobs:
         run: |
           CLIENT_VERSION="${{ steps.check-release.outputs.client_version }}"
           CURRENT_DEP=$(grep "katana-openapi-client>=" katana_mcp_server/pyproject.toml | sed 's/.*>=\([0-9.]*\).*/\1/')
-          
+
           echo "current_version=$CURRENT_DEP" >> $GITHUB_OUTPUT
-          
+
           if [ "$CURRENT_DEP" = "$CLIENT_VERSION" ]; then
             echo "MCP dependency already up to date"
             echo "needs_update=false" >> $GITHUB_OUTPUT
@@ -82,10 +82,12 @@ jobs:
         if: steps.check-current.outputs.needs_update == 'true'
         run: |
           CLIENT_VERSION="${{ steps.check-release.outputs.client_version }}"
-          
+
           # Update the dependency in pyproject.toml
-          sed -i "s/katana-openapi-client>=.*\",/katana-openapi-client>=$CLIENT_VERSION\",/" katana_mcp_server/pyproject.toml
-          
+          sed -i \
+            "s/katana-openapi-client>=.*\",/katana-openapi-client>=$CLIENT_VERSION\",/" \
+            katana_mcp_server/pyproject.toml
+
           # Verify the change
           echo "Updated dependency:"
           grep "katana-openapi-client>=" katana_mcp_server/pyproject.toml
@@ -105,22 +107,27 @@ jobs:
           title: "feat(mcp): update client dependency to v${{ steps.check-release.outputs.client_version }}"
           body: |
             ## Automated Dependency Update
-            
+
             This PR updates the MCP server's client dependency to match the latest client release.
-            
+
             **Changes:**
-            - Update `katana-openapi-client` dependency from `>=${{ steps.check-current.outputs.current_version }}` to `>=${{ steps.check-release.outputs.client_version }}`
+            - Update `katana-openapi-client` dependency from
+              `>=${{ steps.check-current.outputs.current_version }}` to
+              `>=${{ steps.check-release.outputs.client_version }}`
             - Update `uv.lock` to reflect the new dependency
-            
+
             **Release Information:**
             - Client version: v${{ steps.check-release.outputs.client_version }}
             - Tag: client-v${{ steps.check-release.outputs.client_version }}
-            
+
             **Next Steps:**
-            When this PR is merged, it will trigger a new MCP server release with the conventional commit message `feat(mcp):`, which will bump the MCP server's MINOR version.
-            
+            When this PR is merged, it will trigger a new MCP server release with the
+            conventional commit message `feat(mcp):`, which will bump the MCP server's
+            MINOR version.
+
             ---
-            *This PR was automatically created by the [Update MCP Client Dependency workflow](.github/workflows/update-mcp-dependency.yml).*
+            *This PR was automatically created by the
+            [Update MCP Client Dependency workflow](.github/workflows/update-mcp-dependency.yml).*
           branch: auto/update-mcp-dependency-v${{ steps.check-release.outputs.client_version }}
           delete-branch: true
           labels: |

.yamllint.yml

@@ -0,0 +1,44 @@
+# yamllint configuration for katana-openapi-client
+# See https://yamllint.readthedocs.io/ for documentation
+
+extends: default
+
+rules:
+  line-length:
+    max: 120
+    level: error
+    # Ignore line length in OpenAPI spec files
+    ignore: |
+      /docs/katana-openapi.yaml
+
+  document-start:
+    # Don't require --- at start of YAML files
+    present: false
+
+  truthy:
+    # Allow various boolean representations
+    allowed-values: ['true', 'false', 'yes', 'no', 'True', 'False']
+
+  comments:
+    min-spaces-from-content: 1
+
+  indentation:
+    spaces: 2
+
+  brackets:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+
+  braces:
+    min-spaces-inside: 0
+    max-spaces-inside: 1
+
+# Ignore these paths completely
+ignore: |
+  .venv/
+  node_modules/
+  dist/
+  build/
+  *.egg-info/
+  katana_public_api_client/generated/
+  docs/original openapi files/

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

@@ -17,6 +17,7 @@
 
 from katana_mcp.logging import observe_tool
 from katana_mcp.services import get_services
+from katana_mcp.tools.schemas import ConfirmationSchema
 from katana_mcp.unpack import Unpack, unpack_pydantic_params
 from katana_public_api_client.client_types import UNSET
 from katana_public_api_client.models import (
@@ -138,7 +139,47 @@ async def _create_manufacturing_order_impl(
             message=f"Preview: Manufacturing order for variant {request.variant_id}, quantity {request.planned_quantity}",
         )
 
-    # Confirm mode - create the manufacturing order via API
+    # Confirm mode - use elicitation to get user confirmation before creating
+    elicit_result = await context.elicit(
+        f"Create manufacturing order for variant {request.variant_id} with quantity {request.planned_quantity}?",
+        ConfirmationSchema,
+    )
+
+    # Check if user accepted
+    if elicit_result.action != "accept":
+        logger.info(
+            f"User did not accept creation of manufacturing order for variant {request.variant_id}"
+        )
+        return ManufacturingOrderResponse(
+            variant_id=request.variant_id,
+            planned_quantity=request.planned_quantity,
+            location_id=request.location_id,
+            order_created_date=request.order_created_date,
+            production_deadline_date=request.production_deadline_date,
+            additional_info=request.additional_info,
+            is_preview=True,
+            message="Manufacturing order creation cancelled by user",
+            next_actions=["Review the order details and try again with confirm=true"],
+        )
+
+    # Type narrowing: at this point we know action == "accept", so data exists
+    if not elicit_result.data.confirm:
+        logger.info(
+            f"User declined to confirm creation of manufacturing order for variant {request.variant_id}"
+        )
+        return ManufacturingOrderResponse(
+            variant_id=request.variant_id,
+            planned_quantity=request.planned_quantity,
+            location_id=request.location_id,
+            order_created_date=request.order_created_date,
+            production_deadline_date=request.production_deadline_date,
+            additional_info=request.additional_info,
+            is_preview=True,
+            message="Manufacturing order creation declined by user",
+            next_actions=["Review the order details and try again with confirm=true"],
+        )
+
+    # User confirmed - create the manufacturing order via API
     try:
         services = get_services(context)