Merge pull request #14 from inventree/attachment-and-parameter

Support Attachment and Parameter models

Author: SchrodingersGat

README.md

@@ -18,10 +18,18 @@ tools by wrapping an existing (or new) API view, not by reimplementing queries.
 
 Currently read-only: parts, stock items, stock locations, part categories, purchase orders, sales
 orders, build orders (each with list + detail, plus line items, and - for sales/build orders -
-stock allocations), companies, contacts, addresses, manufacturer parts, and supplier parts. No
-write tools are implemented yet - and when they are, the `MCP_READ_ONLY` setting (see
-Configuration below) blocks any write action by default regardless of the calling user's
-permissions, as a second layer on top of per-user roles.
+stock allocations), companies, contacts, addresses, manufacturer parts, supplier parts, BOM items
+and substitutes, attachments, and parameters (with parameter templates). No write tools are
+implemented yet - and when they are, the `MCP_READ_ONLY` setting (see Configuration below) blocks
+any write action by default regardless of the calling user's permissions, as a second layer on top
+of per-user roles.
+
+Attachments and parameters are generic - they can be linked to almost any InvenTree record (a
+part, a stock item, an order, ...) rather than being tied to one resource type - see
+[`inventree_mcp/tools/attachments.py`](inventree_mcp/tools/attachments.py) and
+[`inventree_mcp/tools/parameters.py`](inventree_mcp/tools/parameters.py) for the exact
+`model_type`/`model_id` scoping mechanism (the two use different `model_type` string formats -
+documented in each module).
 
 Each `outputSchema` is generated from the real InvenTree serializer (not hand-maintained), so it
 can't drift from the actual API shape as InvenTree evolves. Every list tool also takes `ordering`

inventree_mcp/mcp_server.py

@@ -29,12 +29,14 @@
 # already-registered tools. See output_schemas.py.
 from . import output_schemas
 from .tools import (  # noqa: F401
+    attachments,
     bom,
     build_orders,
     categories,
     companies,
     discovery,
     locations,
+    parameters,
     parts,
     purchase_orders,
     sales_orders,

inventree_mcp/output_schemas.py

@@ -33,6 +33,11 @@
 from typing import Any
 
 from build.serializers import BuildItemSerializer, BuildLineSerializer, BuildSerializer
+from common.serializers import (
+    AttachmentSerializer,
+    ParameterSerializer,
+    ParameterTemplateSerializer,
+)
 from company.serializers import (
     AddressSerializer,
     CompanySerializer,
@@ -100,6 +105,12 @@
     "get_bom_item": serializer_schema(BomItemSerializer),
     "list_bom_substitutes": paginated_schema(BomItemSubstituteSerializer),
     "get_bom_substitute": serializer_schema(BomItemSubstituteSerializer),
+    "list_attachments": paginated_schema(AttachmentSerializer),
+    "get_attachment": serializer_schema(AttachmentSerializer),
+    "list_parameters": paginated_schema(ParameterSerializer),
+    "get_parameter": serializer_schema(ParameterSerializer),
+    "list_parameter_templates": paginated_schema(ParameterTemplateSerializer),
+    "get_parameter_template": serializer_schema(ParameterTemplateSerializer),
 }
 
 

inventree_mcp/test_mcp.py

@@ -18,8 +18,10 @@
 import jsonschema
 from asgiref.sync import sync_to_async
 from build.models import Build, BuildItem
+from common.models import Attachment, Parameter, ParameterTemplate
 from company.models import Address, Company, Contact, ManufacturerPart, SupplierPart
 from django.contrib.auth import get_user_model
+from django.contrib.contenttypes.models import ContentType
 from django.test import Client, override_settings
 from django.utils import timezone
 from InvenTree.unit_test import InvenTreeTestCase
@@ -47,6 +49,7 @@
 from .schema_introspection import paginated_schema, serializer_schema
 from .settings import get_plugin_setting
 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 (
     get_bom_item,
     get_bom_substitute,
@@ -72,6 +75,12 @@
 )
 from .tools.discovery import describe_filters
 from .tools.locations import get_location, list_locations
+from .tools.parameters import (
+    get_parameter,
+    get_parameter_template,
+    list_parameter_templates,
+    list_parameters,
+)
 from .tools.parts import get_part, list_parts
 from .tools.purchase_orders import (
     get_purchase_order,
@@ -234,6 +243,30 @@ def setUpTestData(cls):
             bom_item=cls.bom_item, part=cls.substitute_part
         )
 
+        # --- Attachment/Parameter fixtures ---
+        # Both model_type fields are real ContentType FKs at the ORM level,
+        # despite each serializing over the wire as a plain string in a
+        # *different* format per resource - see tools/attachments.py's and
+        # tools/parameters.py's module docstrings for why they're not
+        # interchangeable.
+        cls.attachment = Attachment.objects.create(
+            model_type="part",
+            model_id=cls.part.pk,
+            link="https://example.org/datasheet.pdf",
+            comment="Test datasheet",
+        )
+        cls.parameter_template = ParameterTemplate.objects.create(
+            name="Resistance",
+            units="ohm",
+            model_type=ContentType.objects.get_for_model(Part),
+        )
+        cls.parameter = Parameter.objects.create(
+            model_type=ContentType.objects.get_for_model(Part),
+            model_id=cls.part.pk,
+            template=cls.parameter_template,
+            data="100",
+        )
+
         # A second user, deliberately given no roles at all.
         cls.no_access_user = get_user_model().objects.create_user(
             username="noaccess", password="password", email="noaccess@example.org"
@@ -393,6 +426,9 @@ async def test_ordering_argument_reaches_every_list_tool(self):
             "supplier_part": list_supplier_parts,
             "bom_item": list_bom_items,
             "bom_substitute": list_bom_substitutes,
+            "attachment": list_attachments,
+            "parameter": list_parameters,
+            "parameter_template": list_parameter_templates,
         }
 
         for resource, tool_fn in list_tools_by_resource.items():
@@ -711,6 +747,82 @@ async def test_unauthorized_user_cannot_access_bom_data(self):
         with self.assertRaises(ToolError):
             await get_bom_substitute(self.bom_substitute.pk)
 
+    async def test_authorized_user_can_list_and_get_attachments(self):
+        self._as(self.user)
+
+        listed = await list_attachments(model_type="part", model_id=self.part.pk)
+        ids = [a["pk"] for a in listed["results"]]
+        self.assertIn(self.attachment.pk, ids)
+
+        detail = await get_attachment(self.attachment.pk)
+        self.assertEqual(detail["comment"], "Test datasheet")
+
+        # cls.attachment is a link, not an uploaded file, so is_image=False
+        # must include it and is_image=True must exclude it.
+        not_images = await list_attachments(is_image=False)
+        self.assertIn(self.attachment.pk, [a["pk"] for a in not_images["results"]])
+        images_only = await list_attachments(is_image=True)
+        self.assertNotIn(self.attachment.pk, [a["pk"] for a in images_only["results"]])
+
+    async def test_unauthorized_user_can_still_read_attachments(self):
+        """Deliberately the opposite assertion from every other resource's denial test.
+
+        AttachmentList/Detail have no RolePermission/RuleSet gate on reads -
+        only IsAuthenticatedOrReadScope (any authenticated user) - see
+        tools/attachments.py's module docstring. A zero-role user must still
+        succeed here; asserting ToolError (the pattern used everywhere else
+        in this file) would be testing for the wrong thing and would mask a
+        real regression if this view's permissions ever tightened.
+        """
+        self._as(self.no_access_user)
+
+        listed = await list_attachments(model_type="part", model_id=self.part.pk)
+        ids = [a["pk"] for a in listed["results"]]
+        self.assertIn(self.attachment.pk, ids)
+
+        detail = await get_attachment(self.attachment.pk)
+        self.assertEqual(detail["pk"], self.attachment.pk)
+
+    async def test_authorized_user_can_list_and_get_parameters(self):
+        self._as(self.user)
+
+        listed = await list_parameters(model_type="part.part", model_id=self.part.pk)
+        ids = [p["pk"] for p in listed["results"]]
+        self.assertIn(self.parameter.pk, ids)
+
+        detail = await get_parameter(self.parameter.pk)
+        self.assertEqual(detail["data"], "100")
+
+        by_template = await list_parameters(template=self.parameter_template.pk)
+        self.assertIn(self.parameter.pk, [p["pk"] for p in by_template["results"]])
+
+    async def test_authorized_user_can_list_and_get_parameter_templates(self):
+        self._as(self.user)
+
+        listed = await list_parameter_templates(search="Resistance")
+        names = [t["name"] for t in listed["results"]]
+        self.assertIn("Resistance", names)
+
+        detail = await get_parameter_template(self.parameter_template.pk)
+        self.assertEqual(detail["units"], "ohm")
+
+    async def test_unauthorized_user_can_still_read_parameters(self):
+        """Same "opposite of every other resource" case as attachments, above -
+        ParameterList/Detail and ParameterTemplateList/Detail have no
+        RolePermission/RuleSet gate on reads either.
+        """
+        self._as(self.no_access_user)
+
+        listed = await list_parameters(model_type="part.part", model_id=self.part.pk)
+        ids = [p["pk"] for p in listed["results"]]
+        self.assertIn(self.parameter.pk, ids)
+
+        detail = await get_parameter(self.parameter.pk)
+        self.assertEqual(detail["pk"], self.parameter.pk)
+
+        templates = await list_parameter_templates()
+        self.assertTrue(templates["results"])
+
     async def test_authorized_user_can_list_and_get_companies(self):
         self._as(self.user)
 
@@ -956,6 +1068,20 @@ def test_describe_filters_covers_bom_resources(self):
             {"part": {"type": "integer (id)"}, "bom_item": {"type": "integer (id)"}},
         )
 
+    def test_describe_filters_covers_attachment_and_parameter_resources(self):
+        attachment_filters = describe_filters("attachment")["filters"]
+        self.assertIn("model_type", attachment_filters)
+        self.assertIn("model_id", attachment_filters)
+        self.assertIn("is_image", attachment_filters)
+
+        parameter_filters = describe_filters("parameter")["filters"]
+        self.assertIn("model_id", parameter_filters)
+        self.assertIn("template", parameter_filters)
+
+        template_filters = describe_filters("parameter_template")["filters"]
+        self.assertIn("units", template_filters)
+        self.assertIn("has_choices", template_filters)
+
     def test_describe_filters_covers_filterset_fields_shorthand(self):
         """Contact/AddressList use DRF's filterset_fields shorthand, not a full
         filterset_class - regression test for the model-field fallback in

inventree_mcp/tools/attachments.py

@@ -0,0 +1,109 @@
+"""MCP tools for querying InvenTree Attachment data.
+
+Attachments are generic: a single model (`common.models.Attachment`) links a
+file or external URL to almost any other InvenTree record via a
+(`model_type`, `model_id`) pair, rather than each resource having its own
+attachment table. See list_attachments' docstring for the exact
+`model_type` string format this uses, and note it differs from
+`parameters.py`'s.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..mcp_server import mcp
+from ..proxy import call_view
+from ._common import build_query_params
+
+
+@mcp.tool()
+async def list_attachments(
+    model_type: str | None = None,
+    model_id: int | None = None,
+    is_image: bool | None = None,
+    ordering: str | None = None,
+    filters: dict[str, Any] | None = None,
+    limit: int = 25,
+    offset: int = 0,
+) -> dict:
+    """List attachments (uploaded files or external links) linked to InvenTree records.
+
+    Attachments can be linked to almost any InvenTree record - parts, stock
+    items, purchase/sales/return/transfer orders, builds, companies,
+    manufacturer/supplier parts, sales order shipments. Pass both
+    `model_type` and `model_id` together to see everything attached to one
+    specific record, e.g. "what's attached to part 42?".
+
+    Returns a paginated envelope: {count, next, previous, results}. Each
+    entry in `results` has the same shape as get_attachment's return value -
+    use its `pk` field with get_attachment to fetch full detail for one of
+    them. The `attachment`/`thumbnail` fields are URLs to the file, not
+    embedded file content - this tool cannot return raw file bytes.
+
+    Args:
+        model_type: restrict to attachments on this record type - a plain
+            lowercase model name, e.g. "part", "stockitem", "build",
+            "company", "purchaseorder", "salesorder", "returnorder",
+            "transferorder", "manufacturerpart", "supplierpart",
+            "salesordershipment". Note this is a *different* string format
+            from list_parameters' `model_type` (which uses
+            "app_label.modelname") - the two generic-metadata systems don't
+            share a format.
+        model_id: restrict to attachments on this specific record ID (use
+            together with model_type to scope to one record).
+        is_image: True for only attachments with a generated thumbnail
+            (image files), False for the inverse. Omit to include both. See
+            also filters={"is_file": true} / filters={"is_link": true} to
+            distinguish uploaded files from external URL links (a link
+            attachment is never an image).
+        ordering: field to sort results by ('-' prefix for descending, omit
+            it for ascending). Call describe_filters("attachment") and
+            check its ordering_fields list for valid values - an
+            unrecognized field is silently ignored (no error, no sort)
+            rather than rejected.
+        filters: additional filter parameters beyond the named arguments
+            above - call describe_filters("attachment") to see what's
+            available, e.g. filters={"upload_user": <id>}.
+        limit: maximum number of results to return (capped at 100).
+        offset: pagination offset.
+    """
+    from common.api import AttachmentList
+
+    base: dict[str, Any] = {}
+    if model_type is not None:
+        base["model_type"] = model_type
+    if model_id is not None:
+        base["model_id"] = model_id
+    if is_image is not None:
+        base["is_image"] = is_image
+    if ordering is not None:
+        base["ordering"] = ordering
+
+    params = build_query_params(base, filters, limit, offset)
+
+    return await call_view(
+        AttachmentList, "GET", "/api/attachment/", query_params=params
+    )
+
+
+@mcp.tool()
+async def get_attachment(attachment_id: int) -> dict:
+    """Get full detail for a single attachment by its ID.
+
+    Returns the same object shape as one entry in list_attachments's
+    `results` array. Get a valid ID from list_attachments (its `pk` field)
+    if you don't already have one.
+
+    Args:
+        attachment_id: the Attachment's database ID.
+
+    Raises:
+        ToolError: no attachment exists with that ID, or the caller doesn't
+            have permission to view it.
+    """
+    from common.api import AttachmentDetail
+
+    return await call_view(
+        AttachmentDetail, "GET", f"/api/attachment/{attachment_id}/", pk=attachment_id
+    )