Releases: dougborg/stocktrim-openapi-client
mcp-v0.15.1
v0.15.1 (2025-11-22)
Bug Fixes
- docs: update documentation to accurately reflect project capabilities
This commit comprehensively updates the documentation to showcase the project's production-ready quality and extensive feature set.
Main README.md Updates
- Add code quality badges (CI, Codecov, Security, pre-commit) - Update MCP Server features from "5 tools" to "43+ tools, 5 workflow prompts, and resource endpoints" - Expand MCP Server Tools section with complete breakdown: - 27 Foundation Tools (CRUD operations) - 16 Workflow Tools (high-level business operations) - 5 MCP Prompts (guided workflows) - MCP Resources (read-only discovery) - Add new "Code Quality & Testing" section highlighting: - 50+ test files with comprehensive coverage - Linting, type checking, and security scanning - CI/CD pipeline with matrix testing - Quality tooling commands - Enhance Architecture section with MCP Server Architecture details: - Service layer architecture - Parameter flattening and user confirmation patterns - Structured logging and observability - Reference to Architecture Decision Records
Documentation Files Updates
- Update tools.md header from "20+ tools" to "43+ tools" - Add missing
manage_forecast_groupworkflow tool documentation - Update prompts.md to document all 5 workflow prompts: - purchasing_workflow (existing) - forecast_accuracy_review (new) - supplier_performance_review (new) - stockout_prevention (new) - product_lifecycle_review (new)
Impact
The documentation now accurately represents the project as: - Production-ready with enterprise-grade quality infrastructure - Feature-rich with 43+ tools vs. previously understated "5 tools" - Well-tested with comprehensive CI/CD and security scanning - Architecturally sophisticated with clean patterns and safety measures
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- fix(mcp): configure logging at module level to prevent JSON parsing errors
Problem When Claude Desktop connected to the MCP server, it reported: "Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)"
Root cause: logger.info("prompts_registered") at line 369 executed during module import (before main() ran), but logging wasn't configured yet. Log output went to stdout, polluting the MCP JSON-RPC protocol which requires clean JSON on stdout.
Solution 1. Move configure_logging() from main() to module level (line 27) - Ensures logging is configured before any module-level code executes - Runs at import time, before tool registration
-
Re-enable
logger.info("prompts_registered")at line 370 - Now safe because logging is already configured - Output goes to stderr (verified in logging_config.py:39) -
Remove duplicate
configure_logging()call frommain() -
Add documentation explaining initialization order
Testing Verified server starts without JSON errors: bash timeout 3 uv run stocktrim-mcp-server 2>&1 | head -30
- fix: correct tool counts and markdown formatting
Address Copilot review feedback:
-
Fix tool count discrepancies: - Actual count: 21 foundation + 9 workflow = 30 total tools - Updated README.md (3 locations) - Updated docs/mcp-server/tools.md
-
Fix escaped backtick formatting in api-feedback.md: - /api/RunForecast (line 996) - /api/RunForecastCalculations (line 1012) - Removed backslash escapes for proper markdown rendering
Verified counts with: grep -r "mcp.tool()" stocktrim_mcp_server/src/stocktrim_mcp_server/tools/foundation/ | wc -l # 21 grep -r "mcp.tool()" stocktrim_mcp_server/src/stocktrim_mcp_server/tools/workflows/ | wc -l # 9
-
docs(mcp): fix manage_forecast_group parameter documentation (#120)
-
Initial plan
-
docs(mcp): fix manage_forecast_group parameters to match implementation
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: Doug Borg dougborg@apple.com
Co-authored-by: Claude noreply@anthropic.com
Co-authored-by: Copilot 198982749+Copilot@users.noreply.github.com
Detailed Changes: mcp-v0.15.0...mcp-v0.15.1
client-v0.12.0
v0.12.0 (2025-11-22)
Bug Fixes
- docs: update documentation to accurately reflect project capabilities
This commit comprehensively updates the documentation to showcase the project's production-ready quality and extensive feature set.
Main README.md Updates
- Add code quality badges (CI, Codecov, Security, pre-commit) - Update MCP Server features from "5 tools" to "43+ tools, 5 workflow prompts, and resource endpoints" - Expand MCP Server Tools section with complete breakdown: - 27 Foundation Tools (CRUD operations) - 16 Workflow Tools (high-level business operations) - 5 MCP Prompts (guided workflows) - MCP Resources (read-only discovery) - Add new "Code Quality & Testing" section highlighting: - 50+ test files with comprehensive coverage - Linting, type checking, and security scanning - CI/CD pipeline with matrix testing - Quality tooling commands - Enhance Architecture section with MCP Server Architecture details: - Service layer architecture - Parameter flattening and user confirmation patterns - Structured logging and observability - Reference to Architecture Decision Records
Documentation Files Updates
- Update tools.md header from "20+ tools" to "43+ tools" - Add missing
manage_forecast_groupworkflow tool documentation - Update prompts.md to document all 5 workflow prompts: - purchasing_workflow (existing) - forecast_accuracy_review (new) - supplier_performance_review (new) - stockout_prevention (new) - product_lifecycle_review (new)
Impact
The documentation now accurately represents the project as: - Production-ready with enterprise-grade quality infrastructure - Feature-rich with 43+ tools vs. previously understated "5 tools" - Well-tested with comprehensive CI/CD and security scanning - Architecturally sophisticated with clean patterns and safety measures
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- fix(mcp): configure logging at module level to prevent JSON parsing errors
Problem When Claude Desktop connected to the MCP server, it reported: "Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)"
Root cause: logger.info("prompts_registered") at line 369 executed during module import (before main() ran), but logging wasn't configured yet. Log output went to stdout, polluting the MCP JSON-RPC protocol which requires clean JSON on stdout.
Solution 1. Move configure_logging() from main() to module level (line 27) - Ensures logging is configured before any module-level code executes - Runs at import time, before tool registration
-
Re-enable
logger.info("prompts_registered")at line 370 - Now safe because logging is already configured - Output goes to stderr (verified in logging_config.py:39) -
Remove duplicate
configure_logging()call frommain() -
Add documentation explaining initialization order
Testing Verified server starts without JSON errors: bash timeout 3 uv run stocktrim-mcp-server 2>&1 | head -30
- fix: correct tool counts and markdown formatting
Address Copilot review feedback:
-
Fix tool count discrepancies: - Actual count: 21 foundation + 9 workflow = 30 total tools - Updated README.md (3 locations) - Updated docs/mcp-server/tools.md
-
Fix escaped backtick formatting in api-feedback.md: - /api/RunForecast (line 996) - /api/RunForecastCalculations (line 1012) - Removed backslash escapes for proper markdown rendering
Verified counts with: grep -r "mcp.tool()" stocktrim_mcp_server/src/stocktrim_mcp_server/tools/foundation/ | wc -l # 21 grep -r "mcp.tool()" stocktrim_mcp_server/src/stocktrim_mcp_server/tools/workflows/ | wc -l # 9
-
docs(mcp): fix manage_forecast_group parameter documentation (#120)
-
Initial plan
-
docs(mcp): fix manage_forecast_group parameters to match implementation
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: Doug Borg dougborg@apple.com
Co-authored-by: Claude noreply@anthropic.com
Co-authored-by: Copilot 198982749+Copilot@users.noreply.github.com
Chores
-
release: Mcp v0.12.0 (
3e9b436) -
release: Mcp v0.13.0 (
4d5c1a1) -
release: Mcp v0.14.0 (
f529c40) -
release: Mcp v0.15.0 (
78dcfcc) -
release: Mcp v0.15.1 (
3407b24)
Documentation
- Clarify product search is exact match only, remove deprecated methods (
ec96bbc)
This change documents and clarifies that the StockTrim Products API only supports exact code matching, not prefix or partial search. It also removes deprecated methods that had misleading names.
Changes
Documentation - Add API feedback section documenting Products endpoint 404 behavior - Document that code parameter only supports exact matching - Explain why 404 for query filtering is non-standard REST
API Client (stocktrim_public_api_client) - Update get_all() docs to clarify exact match only - Add find_by_exact_code() method with clear naming - Remove deprecated search() method - Update tests to check for find_by_exact_code() instead of search()
MCP Server (stocktrim_mcp_server) - Update find_by_exact_code() docs with API limitation note - Remove deprecated search() method - Rename tests: test_search_* → test_find_by_exact_code_*
Testing - All 73 public API client tests pass - All 276 MCP server tests pass - Test function names now match the actual method names
Breaking Changes Since we're pre-1.0, deprecated methods were removed rather than kept for backward compatibility: - ProductService.search() → use find_by_exact_code() instead - Products.search() → use find_by_exact_code() instead
Note: For keyword search functionality across product names, codes, and
categories, use the Order Plan API (implemented in PR #99).
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- docs: update documentation to accurately reflect project capabilities
This commit comprehensively updates the documentation to showcase the project's production-ready quality and extensive feature set.
Main README.md Updates
- Add code quality badges (CI, Codecov, Security, pre-commit) - Update MCP Server features from "5 tools" to "43+ tools, 5 workflow prompts, and resource endpoints" - Expand MCP Server Tools section with complete breakdown: - 27 Foundation Tools (CRUD operations) - 16 Workflow Tools (high-level business operations) - 5 MCP Prompts (guided workflows) - MCP Resources (read-only discovery) - Add new "Code Quality & Testing" section highlighting: - 50+ test files with comprehensive coverage - Linting, type checking, and security scanning - CI/CD pipeline with matrix testing - Quality tooling commands - Enhance Architecture section with MCP Server Architecture details: - Service layer architecture - Parameter flattening and user confirmation patterns - Structured logging and observability - Reference to Architecture Decision Records
Documentation Files Updates
- Update tools.md header from "20+ tools" to "43+ tools" - Add missing
manage_forecast_groupworkflow tool documentation - Update prompts.md to document all 5 workflow prompts: - purchasing_workflow (existing) - forecast_accuracy_review (new) - supplier_performance_review (new) - stockout_prevention (new) - product_lifecycle_review (new)
Impact
The documentation now accurately represents the project as: - Production-ready with enterprise-grade quality infrastructure - Feature-rich with 43+ tools vs. previously understated "5 tools" - Well-tested with comprehensive CI/CD and security scanning - Architecturally sophisticated with clean patterns and safety measures
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- Apply suggestions from code review
Co-authored-by: Copilot 175728472+Copilot@users.noreply.github.com
- Update docs/mcp-server/prompts.md
Co-authored-by: Doug Borg dougborg@apple.com
Co-authored-by: Claude noreply@anthropic.com
Features
- feat: add Cursor rules for better AI assistance
- Add comprehensive .cursorrules file with project architecture - Document transport-layer resilience pattern - Include domain helpers documentation - Specify generated code rules (DO NOT EDIT) - Add development workflow and testing patterns
-
chore: update uv.lock after dependency sync
-
Apply suggestions from code review
Co-authored-by: Copilot 175728472+Copilot@users.noreply.github.com
- fix: ...
mcp-v0.15.0
v0.15.0 (2025-11-12)
Features
- feat(mcp): consolidate stockout_prevention and product_lifecycle_review prompts
Consolidates prompt implementations from PR #112 and PR #110 into a single feature branch. This adds two new workflow prompts to the existing three, bringing the total to five comprehensive inventory management workflows.
Added Prompts:
-
stockout_prevention(from PR #112) - Proactive stockout prevention workflow - 5-step process: Risk Analysis, Gap Identification, Forecast Review, Preventive Action, and Recommendations - Parameters: location_code (required), days_ahead (default: 14) - Tools: review_urgent_order_requirements, generate_purchase_orders_from_urgent_items, forecasts_get_for_products -
product_lifecycle_review(from PR #110) - Product portfolio optimization workflow - Covers: Portfolio Overview, Performance Analysis, Configuration Review, Optimization Recommendations, and Configuration Changes - Parameters: category (default: "all"), include_inactive (default: False) - Analysis areas: slow movers, overstock risks, forecast accuracy, supplier consolidation, missing configurations
Complete Prompt Inventory (5 total): - purchasing_workflow - forecast_accuracy_review - supplier_performance_review - stockout_prevention (new) - product_lifecycle_review (new)
Implementation Details: - All imports consolidated (added mcp.types imports for product_lifecycle_review) - Added logger initialization for stockout_prevention error handling - All prompts properly registered in register_workflow_prompts() - Combined test suite with 42 tests covering all prompts - All tests passing (318 total in suite) - Linting and formatting clean
Supersedes: - PR #112: Stockout Prevention prompt - PR #110: Product Lifecycle Review prompt
Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- fix: update product_lifecycle_review tests to access .content.text
Fixed test assertions to access message content via .content.text instead of .content directly. Message() factory function returns objects with TextContent in the content field, requiring the .text property access.
Updated 6 test methods: - test_product_lifecycle_review_default_params - test_product_lifecycle_review_with_category - test_product_lifecycle_review_with_inactive - test_product_lifecycle_review_all_params - test_product_lifecycle_review_resources_mentioned - test_product_lifecycle_review_analysis_areas
All 42 workflow prompt tests now passing.
🤖 Generated with Claude Code
Co-authored-by: Doug Borg dougborg@apple.com
Co-authored-by: Claude noreply@anthropic.com
Detailed Changes: mcp-v0.14.0...mcp-v0.15.0
mcp-v0.14.0
v0.14.0 (2025-11-12)
Features
- feat(mcp): implement forecast accuracy review prompt (issue #106)
Co-authored-by: Doug Borg dougborg@dougborg.org
Detailed Changes: mcp-v0.13.0...mcp-v0.14.0
mcp-v0.13.0
v0.13.0 (2025-11-12)
Features
- feat(mcp): implement supplier_performance_review prompt
Implement comprehensive supplier performance review prompt with:
- Optional supplier_code parameter (defaults to None for all suppliers)
- period_days parameter (defaults to 90 days)
- Dynamic current date injection
- Comprehensive system instructions for supply chain analysis
- Guided multi-step workflow (overview, analysis, trends, recommendations)
- Full test coverage (10 tests passing)
- Token size validation (under 5KB)
Detailed Changes: mcp-v0.12.0...mcp-v0.13.0
mcp-v0.12.0
v0.12.0 (2025-11-12)
Build System
Bumps mdformat from 0.7.22 to 1.0.0.
updated-dependencies:
- dependency-name: mdformat dependency-version: 1.0.0
dependency-type: direct:production
update-type: version-update:semver-major
...
Signed-off-by: dependabot[bot] support@github.com
Co-authored-by: Doug Borg dougborg@dougborg.org
- deps: Bump openapi-python-client from 0.27.0 to 0.27.1 (
4749d3f)
Bumps openapi-python-client from 0.27.0 to 0.27.1.
updated-dependencies:
- dependency-name: openapi-python-client dependency-version: 0.27.1
dependency-type: direct:production
update-type: version-update:semver-patch
...
Signed-off-by: dependabot[bot] support@github.com
- deps: Bump pre-commit from 4.3.0 to 4.4.0 (
57c1849)
Bumps pre-commit from 4.3.0 to 4.4.0.
updated-dependencies:
- dependency-name: pre-commit dependency-version: 4.4.0
dependency-type: direct:production
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] support@github.com
- deps: Bump pydantic from 2.12.3 to 2.12.4 (
3c4f712)
Bumps pydantic from 2.12.3 to 2.12.4.
updated-dependencies:
- dependency-name: pydantic dependency-version: 2.12.4
dependency-type: direct:production
update-type: version-update:semver-patch
...
Signed-off-by: dependabot[bot] support@github.com
- deps: Bump python-semantic-release from 10.4.1 to 10.5.0 (
89a11ed)
Bumps python-semantic-release from 10.4.1 to 10.5.0.
updated-dependencies:
- dependency-name: python-semantic-release dependency-version: 10.5.0
dependency-type: direct:production
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] support@github.com
Chores
- release: Client v0.11.0 (
67d0e7d)
Documentation
- Clarify product search is exact match only, remove deprecated methods (
ec96bbc)
This change documents and clarifies that the StockTrim Products API only supports exact code matching, not prefix or partial search. It also removes deprecated methods that had misleading names.
Changes
Documentation - Add API feedback section documenting Products endpoint 404 behavior - Document that code parameter only supports exact matching - Explain why 404 for query filtering is non-standard REST
API Client (stocktrim_public_api_client) - Update get_all() docs to clarify exact match only - Add find_by_exact_code() method with clear naming - Remove deprecated search() method - Update tests to check for find_by_exact_code() instead of search()
MCP Server (stocktrim_mcp_server) - Update find_by_exact_code() docs with API limitation note - Remove deprecated search() method - Rename tests: test_search_* → test_find_by_exact_code_*
Testing - All 73 public API client tests pass - All 276 MCP server tests pass - Test function names now match the actual method names
Breaking Changes Since we're pre-1.0, deprecated methods were removed rather than kept for backward compatibility: - ProductService.search() → use find_by_exact_code() instead - Products.search() → use find_by_exact_code() instead
Note: For keyword search functionality across product names, codes, and
categories, use the Order Plan API (implemented in PR #99).
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
Features
- feat: replace product search with keyword search using Order Plan API
Replace nearly-useless prefix-based product search with comprehensive keyword search that works across product names, codes, and categories.
Changes: - tools/foundation/products.py: - Rename SearchProductsRequest.prefix → search_query - Replace Products API call with Order Plan API searchString - Update docstring with keyword search examples - tests: Update mocks to use Order Plan API and SkuOptimizedResultsDto
Benefits: - Search by product name: "blue widget" - Search by category: "electronics" - Search by partial code: "WIDG" matches "WIDGET-001" - Much more useful than prefix-only search
Before: search_products(prefix="WIDG") - must know exact prefix
After: search_products(search_query="widget") - natural search
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- fix: use OrderPlanFilterCriteria instead of DTO for 415 error
The Order Plan API endpoint expects OrderPlanFilterCriteria, not OrderPlanFilterCriteriaDto. Using the DTO version caused 415 "Unsupported Media Type" errors.
Changes: - Import OrderPlanFilterCriteria instead of OrderPlanFilterCriteriaDto - Update test to be more robust when checking call arguments
Fixes the 415 errors seen in production logs.
- feat: add unpack decorator for flattened MCP parameters
Add @unpack_pydantic_params decorator to enable flattened parameter calls instead of nested request objects, matching the pattern from katana-mcp.
Changes: - Add unpack.py module with Unpack marker and decorator - Apply decorator to search_products tool - Update tests to use flattened parameters
Benefits: - Better DX: search_products(search_query="widget") instead of search_products(request={"search_query": "widget"}) - Maintains Pydantic validation while exposing flat params to MCP - Compatible with FastMCP's parameter introspection
Pattern from: https://github.com/dougborg/katana-openapi-client
- feat(mcp): implement parameter flattening for all tools
Apply @unpack_pydantic_params decorator to all MCP tools to expose flattened parameters instead of nested objects. This improves compatibility with Claude Code and other MCP clients that have issues serializing nested parameter objects.
Changes: - Add unpack.py module with @unpack_pydantic_params decorator (from Katana) - Apply decorator to all 27 tools across 11 tool files - Update all foundation tool tests to use flattened parameters - Add ADR 0001 documenting parameter flattening decision - Update README with parameter flattening pattern documentation
Technical Details: The decorator transforms function signatures at import time: - Scans for Annotated[Model, Unpack()] parameters - Extracts Pydantic model fields as individual KEYWORD_ONLY params - Updates signature and annotations for FastMCP introspection - At runtime, reconstructs validated model instances from flat params
This provides: - Flat parameters for MCP protocol compatibility - Pydantic validation for type safety - Clean tool code working with typed model objects - Automatic parameter documentation from Field descriptions
All 276 tests passing.
Related: Katana MCP implementation (ef59809, 862ce79, a025ca9)
- fix: address PR review feedback
Address review comments from PR #99:
-
Revert nullable supplier code - The SupplierInfo.code field should remain required (str) as it's fundamental for identifying suppliers and the underlying SupplierResponseDto has it as non-nullable.
-
Improve 404 handling documentation - Add detailed comment explaining why StockTrim API returns 404 for "no results" instead of the more conventional 200 with empty list, and why we treat it as expected behavior rather than an error.
-
Fix empty product code handling - Instead of using empty string fallback which violates ProductInfo schema, filter out order plan items that have missing/empty product codes to prevent creating invalid product records.
client-v0.11.0
v0.11.0 (2025-11-11)
Build System
Bumps mdformat from 0.7.22 to 1.0.0.
updated-dependencies:
- dependency-name: mdformat dependency-version: 1.0.0
dependency-type: direct:production
update-type: version-update:semver-major
...
Signed-off-by: dependabot[bot] support@github.com
Co-authored-by: Doug Borg dougborg@dougborg.org
- deps: Bump openapi-python-client from 0.27.0 to 0.27.1 (
4749d3f)
Bumps openapi-python-client from 0.27.0 to 0.27.1.
updated-dependencies:
- dependency-name: openapi-python-client dependency-version: 0.27.1
dependency-type: direct:production
update-type: version-update:semver-patch
...
Signed-off-by: dependabot[bot] support@github.com
- deps: Bump pre-commit from 4.3.0 to 4.4.0 (
57c1849)
Bumps pre-commit from 4.3.0 to 4.4.0.
updated-dependencies:
- dependency-name: pre-commit dependency-version: 4.4.0
dependency-type: direct:production
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] support@github.com
- deps: Bump pydantic from 2.12.3 to 2.12.4 (
3c4f712)
Bumps pydantic from 2.12.3 to 2.12.4.
updated-dependencies:
- dependency-name: pydantic dependency-version: 2.12.4
dependency-type: direct:production
update-type: version-update:semver-patch
...
Signed-off-by: dependabot[bot] support@github.com
- deps: Bump python-semantic-release from 10.4.1 to 10.5.0 (
89a11ed)
Bumps python-semantic-release from 10.4.1 to 10.5.0.
updated-dependencies:
- dependency-name: python-semantic-release dependency-version: 10.5.0
dependency-type: direct:production
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] support@github.com
Chores
- release: Mcp v0.11.0 (
e129cbb)
Documentation
- docs: add ADRs and update documentation
- Add ADR 002: Tool Interface Pattern (Pydantic + FastMCP)
- Add ADR 003: Automated Tool Documentation strategy
- Update overview.md and README.md with current features
- Organize tool documentation investigation into docs/
- Add session summary for 2025-11-07
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
Features
- feat: replace product search with keyword search using Order Plan API
Replace nearly-useless prefix-based product search with comprehensive keyword search that works across product names, codes, and categories.
Changes: - tools/foundation/products.py: - Rename SearchProductsRequest.prefix → search_query - Replace Products API call with Order Plan API searchString - Update docstring with keyword search examples - tests: Update mocks to use Order Plan API and SkuOptimizedResultsDto
Benefits: - Search by product name: "blue widget" - Search by category: "electronics" - Search by partial code: "WIDG" matches "WIDGET-001" - Much more useful than prefix-only search
Before: search_products(prefix="WIDG") - must know exact prefix
After: search_products(search_query="widget") - natural search
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- fix: use OrderPlanFilterCriteria instead of DTO for 415 error
The Order Plan API endpoint expects OrderPlanFilterCriteria, not OrderPlanFilterCriteriaDto. Using the DTO version caused 415 "Unsupported Media Type" errors.
Changes: - Import OrderPlanFilterCriteria instead of OrderPlanFilterCriteriaDto - Update test to be more robust when checking call arguments
Fixes the 415 errors seen in production logs.
- feat: add unpack decorator for flattened MCP parameters
Add @unpack_pydantic_params decorator to enable flattened parameter calls instead of nested request objects, matching the pattern from katana-mcp.
Changes: - Add unpack.py module with Unpack marker and decorator - Apply decorator to search_products tool - Update tests to use flattened parameters
Benefits: - Better DX: search_products(search_query="widget") instead of search_products(request={"search_query": "widget"}) - Maintains Pydantic validation while exposing flat params to MCP - Compatible with FastMCP's parameter introspection
Pattern from: https://github.com/dougborg/katana-openapi-client
- feat(mcp): implement parameter flattening for all tools
Apply @unpack_pydantic_params decorator to all MCP tools to expose flattened parameters instead of nested objects. This improves compatibility with Claude Code and other MCP clients that have issues serializing nested parameter objects.
Changes: - Add unpack.py module with @unpack_pydantic_params decorator (from Katana) - Apply decorator to all 27 tools across 11 tool files - Update all foundation tool tests to use flattened parameters - Add ADR 0001 documenting parameter flattening decision - Update README with parameter flattening pattern documentation
Technical Details: The decorator transforms function signatures at import time: - Scans for Annotated[Model, Unpack()] parameters - Extracts Pydantic model fields as individual KEYWORD_ONLY params - Updates signature and annotations for FastMCP introspection - At runtime, reconstructs validated model instances from flat params
This provides: - Flat parameters for MCP protocol compatibility - Pydantic validation for type safety - Clean tool code working with typed model objects - Automatic parameter documentation from Field descriptions
All 276 tests passing.
Related: Katana MCP implementation (ef59809, 862ce79, a025ca9)
- fix: address PR review feedback
Address review comments from PR #99:
-
Revert nullable supplier code - The SupplierInfo.code field should remain required (str) as it's fundamental for identifying suppliers and the underlying SupplierResponseDto has it as non-nullable.
-
Improve 404 handling documentation - Add detailed comment explaining why StockTrim API returns 404 for "no results" instead of the more conventional 200 with empty list, and why we treat it as expected behavior rather than an error.
-
Fix empty product code handling - Instead of using empty string fallback which violates ProductInfo schema, filter out order plan items that have missing/empty product codes to prevent creating invalid product records.
- docs: add ADR 001 documenting user confirmation pattern
Add Architecture Decision Record documenting the choice to use FastMCP Elicitation for user confirmation on destructive operations.
Documents: - Context and problem statement - 4 options considered (pre-flight, parameter, prompt, elicitation) - Decision rationale (MCP-native, industry best practice) - Implementation pattern with code examples - Tool categorization by risk level - Testing requirements - Consequences and validation criteria
Decision: Use FastMCP Elicitation (MCP native protocol)
Rationale: Standard protocol, strong safety guarantees, rich context,
excellent developer experience
Part of Issue #80 implementation.
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- test: update purchase order and sales order deletion tests for elicitation
- Replace old deletion tests with elicitation pattern tests - Add ...
mcp-v0.11.0
v0.11.0 (2025-11-10)
Chores
- release: Client v0.10.0 (
e11ae0e)
Documentation
- docs: add ADRs and update documentation
- Add ADR 002: Tool Interface Pattern (Pydantic + FastMCP)
- Add ADR 003: Automated Tool Documentation strategy
- Update overview.md and README.md with current features
- Organize tool documentation investigation into docs/
- Add session summary for 2025-11-07
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
Features
- docs: add ADR 001 documenting user confirmation pattern
Add Architecture Decision Record documenting the choice to use FastMCP Elicitation for user confirmation on destructive operations.
Documents: - Context and problem statement - 4 options considered (pre-flight, parameter, prompt, elicitation) - Decision rationale (MCP-native, industry best practice) - Implementation pattern with code examples - Tool categorization by risk level - Testing requirements - Consequences and validation criteria
Decision: Use FastMCP Elicitation (MCP native protocol)
Rationale: Standard protocol, strong safety guarantees, rich context,
excellent developer experience
- test: update purchase order and sales order deletion tests for elicitation
- Replace old deletion tests with elicitation pattern tests - Add imports for AcceptedElicitation, DeclinedElicitation, CancelledElicitation - Test all elicitation response paths (not found, accepted, declined, cancelled) - Align with product and supplier test patterns - All 276 tests passing
- test: implement autospec for service mocks to enforce interface compliance
Use create_autospec() for all service mocks in conftest.py to prevent tests from passing while mocking non-existent methods. This ensures that test mocks always match the actual service interfaces.
Benefits: - Tests will fail immediately if they mock non-existent methods - Prevents bugs where tests pass but production code fails - Provides better refactoring safety - Catches method name typos and signature mismatches
This change was implemented after discovering that tests were mocking services.suppliers.list_suppliers() instead of list_all(), which allowed the bug to slip through to the resource implementation.
All 276 tests pass with autospec enforcement.
Addresses: #82
- fix: add nullable enum support to client regeneration + fix resource bug
-
Add nullable enum field support to regeneration script - Add
add_nullable_to_enum_fields()function - Mark OrderPlanFilterCriteria.currentStatus as nullable - Fixes "None is not a valid CurrentStatusEnum" errors - Addresses: #83 -
Fix supplier directory resource method name - Change
list_suppliers()tolist_all()- This bug was caught by autospec implementation - Related: #82
The regeneration script now handles enum fields that can be null in API responses, using the allOf + nullable pattern for OpenAPI 3.0.
- fix: regenerate client with nullable currentStatus enum field
Regenerated Python client from StockTrim OpenAPI spec with the nullable enum field fix applied. The currentStatus field in OrderPlanFilterCriteria can now handle null values from the API.
Changes: - OrderPlanFilterCriteria.currentStatus is now CurrentStatusEnum | None | Unset - from_dict() properly handles None values without throwing validation errors
This fixes the "None is not a valid CurrentStatusEnum" error when querying order plan data.
Fixes: #83
- fix: remove limit parameter from ProductService.list_all() calls
The ProductService.list_all() method doesn't accept a limit parameter, but foundation.py was calling it with limit=50. This was caught when testing resources with MCP Inspector at runtime.
Root cause: test_foundation.py was using mock_foundation_context which overrode the autospec'd services from conftest.py with plain AsyncMock, so tests couldn't catch the interface mismatch.
Changes: - foundation.py: Remove limit=50 from list_all() call, use slicing instead - test_foundation.py: Remove mock_foundation_context fixture that was overriding autospec'd services with plain AsyncMock - test_foundation.py: Update all tests to use mock_context directly - test_foundation.py: Fix catalog limit test to verify slicing behavior
This ensures autospec catches interface mismatches in resource tests.
- fix: use bulk endpoint for listing all suppliers
The Suppliers.get_all() method was incorrectly using /api/Suppliers endpoint without a code parameter, which returns 404. The StockTrim API has separate endpoints for different supplier operations: - /api/Suppliers?code=X - returns single supplier (requires code) - /api/SuppliersBulk - returns all suppliers (no parameters)
This is different from other endpoints like Customers and Products which return arrays from their main endpoint.
Changes: - Import get_api_suppliers_bulk from generated API - Use bulk endpoint when code is UNSET (listing all) - Use single endpoint when code is provided (get specific supplier) - Update docstring to clarify the conditional behavior
This fixes the 404 error in the supplier directory MCP resource.
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- docs: add ADR 001 documenting user confirmation pattern
Add Architecture Decision Record documenting the choice to use FastMCP Elicitation for user confirmation on destructive operations.
Documents: - Context and problem statement - 4 options considered (pre-flight, parameter, prompt, elicitation) - Decision rationale (MCP-native, industry best practice) - Implementation pattern with code examples - Tool categorization by risk level - Testing requirements - Consequences and validation criteria
Decision: Use FastMCP Elicitation (MCP native protocol)
Rationale: Standard protocol, strong safety guarantees, rich context,
excellent developer experience
Part of Issue #80 implementation.
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- test: update purchase order and sales order deletion tests for elicitation
- Replace old deletion tests with elicitation pattern tests - Add imports for AcceptedElicitation, DeclinedElicitation, CancelledElicitation - Test all elicitation response paths (not found, accepted, declined, cancelled) - Align with product and supplier test patterns - All 276 tests passing
- test: implement autospec for service mocks to enforce interface compliance
Use create_autospec() for all service mocks in conftest.py to prevent tests from passing while mocking non-existent methods. This ensures that test mocks always match the actual service interfaces.
Benefits: - Tests will fail immediately if they mock non-existent methods - Prevents bugs where tests pass but production code fails - Provides better refactoring safety - Catches method name typos and signature mismatches
This change was implemented after discovering that tests were mocking services.suppliers.list_suppliers() instead of list_all(), which allowed the bug to slip through to the resource implementation.
All 276 tests pass with autospec enforcement.
Addresses: #82
- fix: add nullable enum support to client regeneration + fix resource bug
-
Add nullable enum field support to regeneration script - Add
add_nullable_to_enum_fields()function - Mark OrderPlanFilterCriteria.currentStatus as nullable - Fixes "None is not a valid CurrentStatusEnum" errors - Addresses: #83 -
Fix supplier directory resource method name - Change
list_suppliers()tolist_all()- This bug was caught by autospec implementation - Related: #82
The regeneration script now handles enum fields that can be null in API responses, using the allOf + nullable pattern for OpenAPI 3.0.
- fix: regenerate client with nullable currentStatus enum field
Regenerated Python client from StockTrim OpenAPI spec with the nullable enum field fix applied. The currentStatus field in OrderPlanFilterCriteria can now handle null values from the API.
Changes: - OrderPlanFilterCriteria.currentStatus is now CurrentStatusEnum | None | Unset - from_dict() properly handles None values without throwing validation errors
This fixes the "None is not a valid CurrentStatusEnum" error when querying order plan data.
Fixes: #83
- fix: remove limit parameter from ProductService.list_all() calls
The ProductService.list_all() method doesn't accept a limit parameter, but foundation.py was calling it with limit=50. This was caught when testing resources with MCP Inspector at runtime.
Root cause: test_foundation.py was using mock_foundation_context which overrode the autospec'd services from conftest.py with plain AsyncMock, so tests couldn't catch the interface mismatch.
Changes: - foundation.py: Remove limit=50 from list_all() call, use slicing instead - test_foundation.py: Remove mock_foundation_context fixture that was overriding autospec'd services with plain AsyncMock - test_foundation.py: Update all tests to use mock_context directly - test_foundation.py: Fix catalog limit test to verify slicing behavior
This ensures autospec catches interface mismatches in resource t...
client-v0.10.0
v0.10.0 (2025-11-09)
Chores
Documentation
- test(mcp): add comprehensive tests for structured logging
Add test coverage for logging configuration and observability decorators.
Tests added: - test_logging_config.py (10 tests): * Configuration with different formats (console, JSON) * Configuration with different log levels * Logger instance creation * Environment variable handling * Invalid configuration handling
- test_observability.py (15 tests): * @observe_tool decorator functionality * @observe_service decorator functionality * Success and failure scenarios * Timing measurements * Parameter filtering * Function metadata preservation * Exception propagation
All 25 tests pass successfully.
This provides coverage for the structured logging implementation added in commit 925a19f.
- fix(test): replace time.sleep with asyncio.sleep in async tests
Address code review feedback: use asyncio.sleep() instead of time.sleep() in async test functions to properly test timing without blocking the event loop.
Changes: - Replace time.sleep() with asyncio.sleep() in timing tests - Remove AsyncMock() calls that don't yield control - Import asyncio instead of time module
Fixes PR review comments from Copilot.
- test: add comprehensive tests for forecast management tools
Add 13 new unit tests covering the two new forecast management workflow tools: - forecasts_update_and_monitor (5 tests) - forecasts_get_for_products (8 tests)
Tests cover: - Trigger-only and wait-for-completion modes - Progress monitoring and timeout handling - Error scenarios and validation - Filtering, sorting, and priority indicators - Empty results and summary statistics
Also fix DTO field name issues in forecast_management.py: - Remove references to non-existent supplier_name field - Use correct field names (order_quantity, safety_stock_level) - Add pytest timeout marker for long-running test
All 235 tests now passing.
- fix: remove unused product_name assignment
Address Copilot review comment - remove unnecessary product_name assignment that was immediately overwritten. Now correctly uses product_code as the display name since the DTO doesn't have a product_description field.
- docs(mcp): enhance documentation and externalize markdown templates (#5)
This commit addresses issue #5 by significantly improving MCP server documentation for AI agent success. Changes include:
Documentation Improvements
-
Comprehensive Server Instructions (server.py) - Expanded FastMCP instructions from 6 lines to 200+ lines - Added tool categorization (Foundation vs Workflow) - Included 5 complete workflow examples: * Inventory Reordering (automated & manual approaches) * Forecast Management (update, monitor, analyze) * Supplier Onboarding (workflow vs step-by-step) * Product Configuration (lifecycle management) * Customer Order Fulfillment (complete flow) - Added best practices for tool selection - Documented error handling patterns - Included observability and performance notes
-
Complete Workflow Examples (docs/mcp-server/examples.md) - Real-world scenarios with full request/response flows - When-to-use guidance for each workflow - Trade-off analysis for different approaches - Advanced patterns and troubleshooting - Error handling best practices - Performance optimization tips
Code Quality Improvements
- Externalized Markdown Templates - Created templates/ directory for response templates - Extracted 6 markdown templates from forecast_management.py - Added template loader utility with format support - Cleaner code with better maintainability - Templates can now be edited without touching Python code
Technical Details
- Templates use Python .format() for variable substitution - Template loader provides FileNotFoundError for missing templates - All existing tests pass without modification - Server imports successfully with new structure
- docs(mcp): enhance workflow tool docstrings and complete tools.md (#5)
This commit completes issue #5 by enhancing workflow tool documentation with comprehensive docstrings and updating tools.md to include workflow tools.
Enhanced Workflow Tool Docstrings
Updated all 6 workflow tool docstrings with:
-
review_urgent_order_requirements - How it works section - Common use cases (weekly reorders, urgent restocking, etc.) - Typical workflow with step-by-step guidance - Enhanced example with detailed response structure - See Also section linking to examples.md
-
generate_purchase_orders_from_urgent_items - How it works section - Common use cases and best practices - Important notes about draft status and review requirements - Enhanced example showing multiple POs - See Also section with related tools
-
create_supplier_with_products - How it works with transactional approach explanation - Common use cases for supplier onboarding scenarios - Best practices for verification and error handling - Advantages over manual approach comparison - Enhanced example with 3 product mappings
-
configure_product - How it works section - Common use cases (discontinuation, seasonal activation, etc.) - Best practices for lifecycle management - Field mappings explanation (discontinue -> discontinued) - Multiple examples (discontinuing and activating products)
Updated tools.md
Added comprehensive workflow tools section including: - Tool categories explanation (Foundation vs Workflow) - When to use which type of tool - Detailed documentation for all 7 workflow tools: * Forecast management tools (3) * Urgent order management tools (2) * Supplier management tools (1) * Product management tools (1) - Links to examples.md for complete workflows - Parameter documentation with ranges and defaults
Documentation Structure
Each enhanced docstring now includes: - Brief description - "How It Works" section - "Common Use Cases" section - "Best Practices" section (where applicable) - Enhanced examples with realistic data - "See Also" section with links to: * Complete workflows in examples.md * Related tools * Foundation tools for comparison
This makes the tools self-documenting and provides clear guidance for AI agents on when and how to use each tool.
- refactor: extract magic numbers to named constants
Address Copilot review comments by defining: - MAX_RESPONSE_SIZE_BYTES = 400_000 - ESTIMATED_CHARS_PER_FORECAST_ITEM = 500
This improves maintainability and makes token budget thresholds easy to adjust.
- fix: address Copilot review comments
- Extract priority threshold constants (HIGH=7, MEDIUM=14 days) - Remove unnecessary comments from test file - Fix markdown formatting for environment variables
Co-authored-by: Doug Borg dougborg@dougborg.org
Co-authored-by: Claude noreply@anthropic.com
Features
- docs: add ADR 001 documenting user confirmation pattern
Add Architecture Decision Record documenting the choice to use FastMCP Elicitation for user confirmation on destructive operations.
Documents: - Context and problem statement - 4 options considered (pre-flight, parameter, prompt, elicitation) - Decision rationale (MCP-native, industry best practice) - Implementation pattern with code examples - Tool categorization by risk level - Testing requirements - Consequences and validation criteria
Decision: Use FastMCP Elicitation (MCP native protocol)
Rationale: Standard protocol, strong safety guarantees, rich context,
excellent developer experience
- test: update purchase order and sales order deletion tests for elicitation
- Replace old deletion tests with elicitation pattern tests - Add imports for AcceptedElicitation, DeclinedElicitation, CancelledElicitation - Test all elicitation response paths (not found, accepted, declined, cancelled) - Align with product and supplier test patterns - All 276 tests passing
- test: implement autospec for service mocks to enforce interface compliance
Use create_autospec() for all service mocks in conftest.py to prevent tests from passing while mocking non-existent methods. This ensures that test mocks always match the actual service interfaces.
Benefits: - Tests will fail immediately if they mock non-existent methods - Prevents bugs where tests pass but production code fails - Provides better refactoring safety - Catches method name typos and signature mismatches
This change was implemented after discovering that tests were mocking services.suppliers.list_suppliers() instead of list_all(), which allowed the bug to slip through to the resource implementation.
All 276 tests pass with autospec enforcement.
Addresses: #82
- fix: add nullable enum support to client regeneration + fix resource bug
-
Add nullable enum field support to regeneration script - Add
add_nullable_to_enum_fields()function - Mark OrderPlanFilterCriteria.currentStatus as nullable - Fixes "None is not a valid CurrentStatusEnum" errors - Addresses: #83 -
Fix supplier directory resource method name - Change
list_suppliers()tolist_all()- This bug was caught by autospec implementation - Related: #82
Th...
mcp-v0.9.0
v0.9.0 (2025-11-07)
Features
Changes
1. Enhanced Supplier Service - Extended SupplierService.create() to support all SupplierRequestDto fields: - Contact info: email_address, primary_contact_name - Lead time: default_lead_time - Address: street_address, address_line_1, address_line_2, state, country, post_code - External ID: external_id
2. Enhanced Supplier Onboarding Tool - Updated create_supplier_with_products to match suppliers_add_and_configure spec - Added all contact and address fields to request model - Changed return type from JSON to markdown report - Enhanced output with: - Structured supplier details (contact, lead time, address) - Success/failure tracking for product mappings - Actionable next steps based on mapping results
3. New Product Lifecycle Management Tool - Implemented products_configure_lifecycle workflow tool - Supports 4 lifecycle actions: - activate: Enable product and forecasting - deactivate: Temporarily disable forecasting - discontinue: Mark as discontinued - unstock: Remove from inventory management - Features: - Impact analysis (current inventory, previous status) - Optional forecast recalculation - Before/after comparison in markdown report - Error handling with graceful forecast failure
4. Comprehensive Test Coverage - Added 8 new unit tests for products_configure_lifecycle - Updated 7 supplier onboarding tests for markdown output - All 243 tests passing
Closes
Completes #18 (Phase 2: High-Value Workflow Tools)
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
Testing
- test(mcp): add comprehensive tests for structured logging
Add test coverage for logging configuration and observability decorators.
Tests added: - test_logging_config.py (10 tests): * Configuration with different formats (console, JSON) * Configuration with different log levels * Logger instance creation * Environment variable handling * Invalid configuration handling
- test_observability.py (15 tests): * @observe_tool decorator functionality * @observe_service decorator functionality * Success and failure scenarios * Timing measurements * Parameter filtering * Function metadata preservation * Exception propagation
All 25 tests pass successfully.
This provides coverage for the structured logging implementation added in commit 925a19f.
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
- test(mcp): add comprehensive tests for structured logging
Add test coverage for logging configuration and observability decorators.
Tests added: - test_logging_config.py (10 tests): * Configuration with different formats (console, JSON) * Configuration with different log levels * Logger instance creation * Environment variable handling * Invalid configuration handling
- test_observability.py (15 tests): * @observe_tool decorator functionality * @observe_service decorator functionality * Success and failure scenarios * Timing measurements * Parameter filtering * Function metadata preservation * Exception propagation
All 25 tests pass successfully.
This provides coverage for the structured logging implementation added in commit 925a19f.
🤖 Generated with Claude Code
Co-authored-by: Doug Borg dougborg@apple.com
Co-authored-by: Claude noreply@anthropic.com
Detailed Changes: mcp-v0.8.0...mcp-v0.9.0