docs(mcp): make tool docs match the 32 registered tools - #232
Open
dougborg wants to merge 2 commits into
Open
Conversation
The MCP server instructions and docs/mcp-server/tools.md advertised tools that
were never registered (list_products, create_products, create_customers,
create_suppliers, get_inventory, set_inventory, run_order_plan, run_forecast,
get_configuration, list_boms, create_bom) and used a `stocktrim_` tool-name
prefix the real tools don't have. Clients reading these would call non-existent
tools.
- Rewrite server.py "Tool Categories" + workflow/data-flow examples to the real
tool names; add an explicit "not exposed via MCP" note (BOM, order-plan query,
forecast trigger, inventory read, customer/bulk create).
- Replace the phantom Planning/Configuration/BOM sections in tools.md with a
"Not Yet Available as MCP Tools" section pointing at the client library; fix
the Inventory section (set_product_inventory; no read tool) and the header
count (32 = 21 foundation + 9 workflow + 2 session preferences).
- Delete three dead duplicate tool modules (tools/{products,customers,inventory}.py)
that were never imported — the foundation/ versions are the live ones.
- Add a drift-guard test asserting the registered tool set exactly matches a
documented contract, so docs and reality can't silently diverge again.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR aims to eliminate “docs vs reality” drift in the StockTrim MCP server by updating tool documentation to match the actually registered tool set, removing dead/duplicate tool modules, and adding a regression test that asserts the registered tool names match an explicit contract.
Changes:
- Updated MCP server instruction text (
server.py) and MCP tool documentation (docs/mcp-server/tools.md) to reflect the intended real tool names and remove references to phantom tools. - Deleted three duplicate/unreferenced tool modules (
tools/{products,customers,inventory}.py) in favor of thetools/foundation/implementations. - Added a drift-guard test (
EXPECTED_TOOL_NAMES) to fail CI if tool registration diverges from the expected contract.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
stocktrim_mcp_server/tests/test_tool_schemas.py |
Adds EXPECTED_TOOL_NAMES + an exact-match test to prevent future tool-set drift. |
stocktrim_mcp_server/src/stocktrim_mcp_server/tools/products.py |
Deletes dead duplicate module (replaced by tools/foundation/products.py). |
stocktrim_mcp_server/src/stocktrim_mcp_server/tools/inventory.py |
Deletes dead duplicate module (replaced by tools/foundation/inventory.py). |
stocktrim_mcp_server/src/stocktrim_mcp_server/tools/customers.py |
Deletes dead duplicate module (replaced by tools/foundation/customers.py). |
stocktrim_mcp_server/src/stocktrim_mcp_server/server.py |
Updates the “Tool Categories” + workflow/examples to use the intended tool names. |
docs/mcp-server/tools.md |
Updates tool counts/sections and removes phantom planning/config/BOM tool sections in favor of a “not yet available” note. |
Address PR #232 review (Copilot): the first pass left the Foundation Tools section of tools.md untouched and invented tool I/O shapes. - tools.md Foundation section: drop the `stocktrim_` prefix and the phantom entries that survived the first pass (stocktrim_list_products, stocktrim_create_products, stocktrim_create_customers, stocktrim_create_suppliers, stocktrim_list_locations, stocktrim_create_location); use the real registered names (get_product, search_products, create_product, list_customers, create_supplier, list_locations, create_location, ...). - Correct set_product_inventory params (product_id/stock_on_hand/stock_on_order/ location_code/location_name — there is no `inventory_items` array or `quantity`). - get_product returns ProductInfo (code/description/uom/is_active/cost/selling price) with NO stock or supplier fields; fix server.py workflow/data-flow examples that claimed get_product exposes stock_on_hand or a product.id, and point stock lookups at the stocktrim://inventory/... resource instead. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Owner
Author
|
Thanks @Copilot — all five addressed in ecd8114 (the first pass had only fixed part of the doc and invented some tool I/O shapes):
|
Comment on lines
+123
to
+129
| """The registered tool set must exactly match the documented contract. | ||
|
|
||
| Guards both directions: a documented-but-missing tool (phantom) and an | ||
| implemented-but-undocumented tool both fail here. When intentionally adding | ||
| or removing a tool, update EXPECTED_TOOL_NAMES together with server.py's | ||
| "## Tool Categories" section and docs/mcp-server/tools.md. | ||
| """ |
Comment on lines
235
to
+237
| **Parameters:** | ||
|
|
||
| - `products` (array): List of product objects | ||
| - product fields (code, name, category, cost, price, etc.) |
Comment on lines
495
to
497
| **Parameters:** | ||
|
|
||
| - `location` (object): Location data |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The MCP server's instructions and
docs/mcp-server/tools.mdadvertised 11 tools that were never registered and used astocktrim_name prefix the real tools don't have. An AI client reading these docs would try to call non-existent tools.Phantom tools removed from docs:
list_products,create_products,delete_products,create_customers,create_suppliers,get_inventory,set_inventory,run_order_plan,run_forecast,get_configuration,list_boms,create_bom.Initial changes:
server.pyinstructions — rewrote the "Tool Categories" section + the workflow / data-flow examples to the real tool names, and added an explicit "not exposed via MCP" note (bill-of-materials, order-plan queries, forecast triggering, inventory read, customer/bulk create).docs/mcp-server/tools.md— replaced the phantom Planning / Configuration / BOM sections with a "Not Yet Available as MCP Tools" section pointing at the client library; fixed the Inventory section (set_product_inventory; no read tool) and the header count (32 = 21 foundation + 9 workflow + 2 session preferences).tools/{products,customers,inventory}.py— never imported; thefoundation/versions are the live ones.test_tool_schemas.py) asserting the registered tool set exactly matches a documented contract (EXPECTED_TOOL_NAMES), so docs and reality can't silently diverge again — fails on both phantom (documented-but-missing) and undocumented-but-registered tools.Follow-up corrections (review feedback):
server.pyworkflow steps — correctedget_productdescription to reflect its actualProductInforesponse (code/description/uom/is_active/cost/selling price, no stock or supplier fields); inventory levels are now directed to thestocktrim://reports/inventory-statusandstocktrim://inventory/{location_code}/{product_code}resources.server.pydata-flow example — fixed toset_product_inventory({product_id: "WIDGET-001", stock_on_hand: 100, location_code: "AKL"}); removed the non-existentquantityandproduct.idfields.tools.mdFoundation section — all tool names now use real, unprefixed names with nostocktrim_prefix and no phantom entries.tools.mdInventory section —set_product_inventorynow documents the real flat parameters (product_id,stock_on_hand,stock_on_order,location_code,location_name); removed the incorrectinventory_itemsarray and the inaccurate note aboutget_productexposing stock fields.This is the "docs-honest first" step; a follow-up will add real BOM/assemblies MCP tools (tracked separately).
Type of Change
Testing
Code Quality
uv run poe lintand resolved any issuesuv run poe format-checkand code is properly formattedRelated Issues
Additional Notes
New
test_registered_tools_match_documented_contractdrift-guard test fails on both phantom (documented-but-missing) and undocumented-but-registered tools, preventing future docs/reality divergence.