docs(mcp): make tool docs match the 32 registered tools#232
Open
dougborg wants to merge 1 commit 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. |
Comment on lines
227
to
230
| **Approach B - Manual**: | ||
| 1. list_products → Get all products | ||
| 2. get_inventory → Check stock levels | ||
| 1. search_products(...) → Find candidate products | ||
| 2. get_product(code) → Inspect a product's stock_on_hand and supplier | ||
| 3. For low-stock items: create_purchase_order with appropriate quantities |
Comment on lines
269
to
+272
| 1. get_customer("CUST-001") → Verify customer exists | ||
| 2. get_product("WIDGET-001") → Verify product exists and get details | ||
| 3. get_inventory → Check if sufficient stock available | ||
| 4. If in stock: create_sales_order({...}) | ||
| 5. After order ships: set_inventory to deduct stock | ||
| 2. get_product("WIDGET-001") → Verify product exists and check stock_on_hand | ||
| 3. If in stock: create_sales_order({...}) | ||
| 4. After order ships: set_product_inventory to deduct stock |
Comment on lines
311
to
314
| product = get_product("WIDGET-001") | ||
| if product: | ||
| set_inventory({product_id: product.id, quantity: 100}) | ||
| set_product_inventory({product_id: product.id, quantity: 100}) | ||
| else: |
Comment on lines
+3
to
+5
| The StockTrim MCP Server provides **32 tools** for interacting with the StockTrim API, | ||
| organized into **Foundation Tools** (21 direct API operations), **Workflow Tools** (9 | ||
| high-level business operations), and **Session Preference Tools** (2). |
Comment on lines
+322
to
326
| Set inventory levels for products. (There is no inventory-read tool; read a product's | ||
| `stock_on_hand` via `get_product` instead.) | ||
|
|
||
| **Parameters:** | ||
|
|
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.
Summary
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.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.This is the "docs-honest first" step; a follow-up will add real BOM/assemblies MCP tools (tracked separately).
Test plan
uv run poe check(lint + ty + full client & MCP suites) passestest_registered_tools_match_documented_contractpasses and would fail if a documented tool isn't registered (or vice-versa)🤖 Generated with Claude Code