Merge pull request #35 from inventree/tool-link

Tool link

Author: SchrodingersGat

inventree_mcp/mcp_server.py

@@ -25,7 +25,23 @@
 
 mcp = MCPServer(
     name="InvenTree MCP",
-    instructions="MCP server for querying InvenTree inventory management data.",
+    instructions=(
+        "MCP server for querying InvenTree inventory management data - "
+        "parts, stock, purchase/sales/return orders, build orders, "
+        "companies (suppliers/customers/manufacturers) and their catalog "
+        "parts, BOMs, attachments, and more. Every tool here only reads "
+        "data (no create/update/delete tools exist yet). "
+        "Tools follow a list_X/get_X pattern per resource (e.g. "
+        "list_parts/get_part). To find out more about a resource beyond "
+        "its tools' named arguments - available search fields, sort "
+        "fields, extra filters, and optional fields you can inline to save "
+        "a round trip - call describe_filters(resource) first. "
+        "When your response mentions a specific record that has a "
+        "standalone web UI page (e.g. a part, build order, purchase order, "
+        "stock item, or company - see make_web_link's docstring for the "
+        "full list), call make_web_link with its type and ID to give the "
+        "user a clickable link to it."
+    ),
 )
 
 # Import tool modules for their side effect of registering @mcp.tool() functions.

inventree_mcp/output_schemas.py

@@ -129,6 +129,13 @@
     "get_stock_test_result": serializer_schema(StockItemTestResultSerializer),
     "list_project_codes": paginated_schema(ProjectCodeSerializer),
     "get_project_code": serializer_schema(ProjectCodeSerializer),
+    "make_web_link": {
+        "type": "object",
+        "properties": {
+            "web_url": {"type": ["string", "null"], "format": "uri"},
+            "error": {"type": "string"},
+        },
+    },
 }
 
 

inventree_mcp/test_mcp.py

@@ -11,6 +11,7 @@
 
 import datetime
 import json
+import sys
 import unittest
 from typing import Any, ClassVar
 from unittest.mock import patch
@@ -59,6 +60,7 @@
 from .proxy import call_view
 from .schema_introspection import paginated_schema, serializer_schema
 from .settings import get_plugin_setting
+from .tools import discovery
 from .tools._common import DEFAULT_LIMIT, MAX_LIMIT, build_query_params, clamp_limit
 from .tools.attachments import get_attachment, list_attachments
 from .tools.bom import (
@@ -84,7 +86,7 @@
     list_companies,
     list_contacts,
 )
-from .tools.discovery import RESOURCE_LOADERS, describe_filters
+from .tools.discovery import RESOURCE_LOADERS, describe_filters, make_web_link
 from .tools.locations import get_location, list_locations
 from .tools.parameters import (
     get_parameter,
@@ -1081,6 +1083,22 @@ async def test_unauthorized_user_can_still_read_project_codes(self):
         detail = await get_project_code(self.project_code.pk)
         self.assertEqual(detail["pk"], self.project_code.pk)
 
+    async def test_make_web_link_builds_a_real_url_end_to_end(self):
+        """Exercise the actual registered async tool (not just the sync helper
+        MakeWebLinkTest covers) - confirms the sync_to_async wrapping in
+        discovery.make_web_link() doesn't swallow or mis-route either the
+        return value or a raised ToolError.
+        """
+        result = await make_web_link("purchase_order", self.purchase_order.pk)
+        self.assertTrue(
+            result["web_url"].endswith(
+                f"/web/purchasing/purchase-order/{self.purchase_order.pk}"
+            )
+        )
+
+        with self.assertRaises(ToolError):
+            await make_web_link("purchase_order_line", self.po_line.pk)
+
     async def test_tools_list_reflects_oauth2_scope_narrowing(self):
         """Regression test for a real design bug caught during development, not a
         hypothetical: a literal HTTP OPTIONS-based capability check (the obvious
@@ -1162,6 +1180,7 @@ async def test_ungated_tools_are_always_visible_to_a_zero_role_user(self):
             names,
             {
                 "describe_filters",
+                "make_web_link",
                 "list_attachments",
                 "get_attachment",
                 "list_parameters",
@@ -1241,7 +1260,7 @@ async def test_unauthenticated_bound_identity_sees_only_tools_needing_no_auth(se
             tool.name for tool in await mcp.list_tools()
         )
 
-        self.assertEqual(names, {"describe_filters"})
+        self.assertEqual(names, {"describe_filters", "make_web_link"})
 
     async def test_unavailable_resource_hides_its_tools_without_crashing(self):
         """A resource whose loader can't resolve its view class (e.g. a
@@ -1273,7 +1292,14 @@ async def test_every_gated_tool_has_a_visibility_entry(self):
         """
         all_names = {tool.name for tool in await mcp.list_tools()}
         unmapped = (
-            all_names - set(tool_visibility._TOOL_RESOURCES) - {"describe_filters"}
+            all_names
+            - set(tool_visibility._TOOL_RESOURCES)
+            # Both pure metadata/utility tools with no underlying gated view:
+            # describe_filters only reads static filterset/serializer
+            # definitions, make_web_link only builds a URL string - neither
+            # touches the database in a way any RolePermission/RuleSet check
+            # applies to.
+            - {"describe_filters", "make_web_link"}
         )
 
         self.assertEqual(unmapped, set())
@@ -1376,6 +1402,65 @@ def test_caches_a_total_failure_without_re_importing(self):
         mock_import.assert_called_once()
 
 
+class MakeWebLinkTest(unittest.TestCase):
+    """discovery._build_web_link() must build the right InvenTree web-UI URL, and know when not to.
+
+    Exercises the sync helper directly rather than the registered async
+    make_web_link() tool - same reasoning as ViewResolutionTest testing
+    resolve_view() directly: this needs no MCP/DB fixtures, just the plain
+    function ToolError.
+    """
+
+    def test_raises_for_a_resource_with_no_standalone_page(self):
+        with self.assertRaises(ToolError):
+            discovery._build_web_link("purchase_order_line", 1)
+
+    def test_returns_an_error_message_without_a_configured_base_url(self):
+        with patch("InvenTree.helpers_model.get_base_url", return_value=""):
+            result = discovery._build_web_link("part", 5)
+            self.assertIsNone(result["web_url"])
+            self.assertIn("error", result)
+
+    def test_returns_an_error_message_on_a_core_version_mismatch(self):
+        # Setting a module to None in sys.modules is what actually forces
+        # ImportError out of a `from X import Y` statement - patching an
+        # attribute on the already-imported module (as
+        # test_returns_an_error_message_without_a_configured_base_url does
+        # above) can't simulate that, since the `from` import itself would
+        # still succeed.
+        with patch.dict(sys.modules, {"InvenTree.helpers": None}):
+            result = discovery._build_web_link("part", 5)
+            self.assertIsNone(result["web_url"])
+            self.assertIn("error", result)
+
+    def test_builds_the_expected_url_per_resource(self):
+        with patch("InvenTree.helpers_model.get_base_url", return_value="http://x/"):
+            cases = {
+                "part": (5, "http://x/web/part/5"),
+                "category": (2, "http://x/web/part/category/2"),
+                "stock": (7, "http://x/web/stock/item/7"),
+                "location": (3, "http://x/web/stock/location/3"),
+                "purchase_order": (9, "http://x/web/purchasing/purchase-order/9"),
+                "supplier_part": (4, "http://x/web/purchasing/supplier-part/4"),
+                "manufacturer_part": (
+                    6,
+                    "http://x/web/purchasing/manufacturer-part/6",
+                ),
+                # The generic 'company/{pk}' route, not core's own Company.
+                # get_absolute_url() - see _WEB_LINK_PATHS's comment for why.
+                "company": (8, "http://x/web/company/8"),
+                "sales_order": (1, "http://x/web/sales/sales-order/1"),
+                "return_order": (10, "http://x/web/sales/return-order/10"),
+                "build_order": (11, "http://x/web/manufacturing/build-order/11"),
+            }
+            for resource, (pk, expected) in cases.items():
+                self.assertEqual(
+                    discovery._build_web_link(resource, pk)["web_url"],
+                    expected,
+                    resource,
+                )
+
+
 class CallViewImportSafetyTest(InvenTreeTestCase):
     """call_view(None, ...) must raise a clean ToolError, not an AttributeError.
 

inventree_mcp/tools/discovery.py

@@ -2,13 +2,17 @@
 
 from __future__ import annotations
 
+import structlog
+from asgiref.sync import sync_to_async
 from mcp.server.mcpserver.exceptions import ToolError
 
 from ..expand_introspection import describe_output_options
 from ..filter_introspection import describe_filterset
 from ..mcp_server import mcp
 from ..view_resolution import resolve_view, resolve_view_any
 
+logger = structlog.get_logger("inventree")
+
 
 def _part_list() -> type | None:
     return resolve_view("part.api", "PartList")
@@ -239,3 +243,116 @@ def describe_filters(resource: str) -> dict:
         **describe_filterset(view_cls),
         "optional_fields": describe_output_options(view_cls),
     }
+
+
+# Relative "web" (React frontend) subpaths, one per resource that has a real
+# standalone detail page - matches each model's own get_absolute_url() in
+# InvenTree core (order/models.py, part/models.py, stock/models.py,
+# company/models.py), *not* imported from there directly: doing so would
+# need a real (DB-fetched) model instance just to read a pk-only f-string,
+# and Company.get_absolute_url() unconditionally returns
+# '/purchasing/manufacturer/{pk}' regardless of whether the company is
+# actually a supplier/manufacturer/customer (looks like a core bug -
+# verified against src/frontend/src/router.tsx, which also registers a
+# generic 'company/:id' route that resolves correctly for any role - used
+# here instead of reproducing that bug). manufacturer_part has no
+# get_absolute_url() in core at all; its route
+# ('purchasing/manufacturer-part/:id') is hardcoded here straight from
+# router.tsx. Resources with no standalone page (line items, allocations,
+# attachments, and other records only ever shown embedded in a parent's
+# page) are deliberately absent - make_web_link() rejects them below.
+_WEB_LINK_PATHS: dict[str, str] = {
+    "part": "/part/{pk}",
+    "category": "/part/category/{pk}",
+    "stock": "/stock/item/{pk}",
+    "location": "/stock/location/{pk}",
+    "purchase_order": "/purchasing/purchase-order/{pk}",
+    "supplier_part": "/purchasing/supplier-part/{pk}",
+    "manufacturer_part": "/purchasing/manufacturer-part/{pk}",
+    "company": "/company/{pk}",
+    "sales_order": "/sales/sales-order/{pk}",
+    "return_order": "/sales/return-order/{pk}",
+    "build_order": "/manufacturing/build-order/{pk}",
+}
+
+
+def _build_web_link(model_type: str, model_id: int) -> dict:
+    path_template = _WEB_LINK_PATHS.get(model_type)
+
+    if path_template is None:
+        raise ToolError(
+            f"{model_type!r} has no standalone web page. Choose one of: "
+            f"{', '.join(_WEB_LINK_PATHS)}"
+        )
+
+    try:
+        from InvenTree.helpers import pui_url
+        from InvenTree.helpers_model import construct_absolute_url, get_base_url
+    except ImportError as exc:
+        # Defensive, same reasoning as view_resolution.py: a version
+        # mismatch between this plugin and the running InvenTree core
+        # shouldn't crash the tool, just leave it unable to build a link -
+        # but unlike the "no base URL configured" case below, this is a real
+        # failure, so log it and tell the caller why, not just null.
+        logger.warning(
+            "inventree_mcp: could not import URL-building helpers (%s) - "
+            "make_web_link will report web_url as unavailable. This usually "
+            "means the running InvenTree core version doesn't match what "
+            "this plugin expects.",
+            exc,
+        )
+        return {
+            "web_url": None,
+            "error": ("Could not build a web link with the provided information."),
+        }
+
+    if not get_base_url():
+        return {
+            "web_url": None,
+            "error": ("Base URL is not configured for this InvenTree instance."),
+        }
+
+    return {
+        "web_url": construct_absolute_url(pui_url(path_template.format(pk=model_id)))
+    }
+
+
+@mcp.tool()
+async def make_web_link(model_type: str, model_id: int) -> dict:
+    """Build a clickable InvenTree web UI link for a specific record.
+
+    Does not touch any InvenTree data - this only builds a URL string, the
+    same way describe_filters only describes static metadata. It doesn't
+    verify model_id actually exists; a valid ID from the matching
+    list_*/get_* tool always produces a valid link.
+
+    Not every resource has a standalone page in the web UI - only the ones
+    listed below do. A PurchaseOrderLineItem, for example, is only ever
+    shown embedded in its parent order's page - call this with the parent
+    purchase_order's ID instead of trying it with a line item.
+
+    Args:
+        model_type: one of "part", "category", "stock", "location",
+            "purchase_order", "supplier_part", "manufacturer_part",
+            "company", "sales_order", "return_order", "build_order" -
+            matches get_part / get_category / get_stock_item / get_location
+            / get_purchase_order / get_supplier_part / get_manufacturer_part
+            / get_company / get_sales_order / get_return_order /
+            get_build_order.
+        model_id: the record's database ID (its `pk` field, from the
+            matching list_*/get_* tool).
+
+    Returns:
+        {"web_url": <url>} - a full, absolute URL - if this InvenTree
+        instance has a configured base URL to build one from (SITE_URL /
+        Django Sites / the INVENTREE_BASE_URL global setting).
+        {"web_url": null, "error": <message>} otherwise, explaining why no
+        link could be built - either the server just isn't configured with
+        a base URL (nothing wrong with the call itself), or the running
+        InvenTree core version doesn't match what this plugin expects (a
+        real failure, also logged server-side).
+
+    Raises:
+        ToolError: model_type isn't one of the resources listed above.
+    """
+    return await sync_to_async(_build_web_link)(model_type, model_id)