Merge pull request #46 from inventree/well-known

add well-known URL

Author: SchrodingersGat

AGENTS.md

@@ -35,6 +35,10 @@ duplicate the check per-tool or bypass `call_view()`.
 - `expand_introspection.py` - derives optional output-expansion flags (e.g. `part_detail`) from a
   view's real `output_options`.
 - `core.py` - the `InvenTreePlugin` subclass, `REQUIRE_AUTH` and `MCP_READ_ONLY` settings.
+- `server_card.py` - serves an MCP Server Card (SEP-2127) at `plugin/inventree-mcp/server-card/`
+  for discovery, advertised under `/.well-known/` via `core.py`'s `get_well_known_urls()`.
+- `_well_known_compat.py` - `WellKnownMixin` import, falling back to a blank mixin on InvenTree
+  versions predating `inventree/InvenTree#12698` (not yet in a "stable" release as of writing).
 
 ## Testing
 

inventree_mcp/_well_known_compat.py

@@ -0,0 +1,22 @@
+"""Compat shim for InvenTree versions that don't yet provide WellKnownMixin.
+
+WellKnownMixin (letting a plugin advertise entries under /.well-known/) was
+added in inventree/InvenTree#12698, merged to InvenTree's master branch but
+not yet present in a "stable" release. InvenTreeMCP must still import and
+load cleanly on older InvenTree instances, so this falls back to a blank
+mixin that simply advertises nothing when the real one isn't available.
+"""
+
+try:
+    from plugin.mixins import WellKnownMixin
+except ImportError:  # pragma: no cover - only hit on InvenTree < #12698
+
+    class WellKnownMixin:
+        """Blank fallback used when the running InvenTree doesn't provide WellKnownMixin."""
+
+        def get_well_known_urls(self, request=None):
+            """No well-known entries to advertise without native support."""
+            return []
+
+
+__all__ = ["WellKnownMixin"]

inventree_mcp/core.py

@@ -2,13 +2,15 @@
 
 from typing import ClassVar
 
+from django.urls import reverse_lazy
 from plugin import InvenTreePlugin
 from plugin.mixins import SettingsMixin, UrlsMixin
 
 from . import PLUGIN_VERSION
+from ._well_known_compat import WellKnownMixin
 
 
-class InvenTreeMCP(SettingsMixin, UrlsMixin, InvenTreePlugin):
+class InvenTreeMCP(WellKnownMixin, SettingsMixin, UrlsMixin, InvenTreePlugin):
     """InvenTreeMCP - custom InvenTree plugin."""
 
     # Plugin metadata
@@ -53,6 +55,13 @@ class InvenTreeMCP(SettingsMixin, UrlsMixin, InvenTreePlugin):
     # Ref: https://docs.inventree.org/en/latest/plugins/mixins/urls/
     def setup_urls(self):
         """Configure custom URL endpoints for this plugin."""
-        from .mcp_transport import urlpatterns
+        from .mcp_transport import urlpatterns as mcp_urlpatterns
+        from .server_card import urlpatterns as server_card_urlpatterns
 
-        return urlpatterns
+        return mcp_urlpatterns + server_card_urlpatterns
+
+    # Well-known URLs (from WellKnownMixin, if the running InvenTree provides it)
+    # Ref: https://github.com/inventree/inventree-mcp/issues/33
+    def get_well_known_urls(self, request=None):
+        """Advertise this plugin's MCP Server Card under /.well-known/."""
+        return [("mcp-server-card", reverse_lazy(f"plugin:{self.slug}:server-card"))]

inventree_mcp/server_card.py

@@ -0,0 +1,68 @@
+"""Serve an MCP Server Card for discoverability.
+
+Implements SEP-2127 (https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127),
+which lets an MCP client discover this server's remote endpoint and supported
+protocol versions ahead of connecting, without guessing or hardcoding a URL.
+
+The card deliberately omits tools/resources/prompts - those are dynamic
+(vary by caller's role/OAuth2 scope, see tool_visibility.py) and already
+discoverable at runtime via the real MCP `tools/list` call.
+
+This view is registered as a plain plugin URL regardless of InvenTree
+version (see core.py's setup_urls()), so it's always directly reachable.
+It's only *advertised* under /.well-known/ when the running InvenTree
+provides WellKnownMixin - see _well_known_compat.py.
+"""
+
+from __future__ import annotations
+
+from django.http import HttpRequest, JsonResponse
+from django.urls import path, reverse
+from InvenTree.permissions import auth_exempt
+from mcp_types.version import SUPPORTED_PROTOCOL_VERSIONS
+
+from . import PLUGIN_VERSION
+
+# Must be exactly this URL per SEP-2127.
+SERVER_CARD_SCHEMA = (
+    "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json"
+)
+
+
+def build_server_card(request: HttpRequest) -> dict:
+    """Build this plugin's MCP Server Card document."""
+    mcp_url = request.build_absolute_uri(reverse("plugin:inventree-mcp:mcp-endpoint"))
+
+    return {
+        "$schema": SERVER_CARD_SCHEMA,
+        "name": "io.github.inventree/inventree-mcp",
+        "version": PLUGIN_VERSION,
+        "title": "InvenTree MCP",
+        "description": "MCP server for InvenTree",
+        "websiteUrl": "https://github.com/inventree/inventree-mcp",
+        "repository": {
+            "url": "https://github.com/inventree/inventree-mcp",
+            "source": "github",
+        },
+        "remotes": [
+            {
+                "type": "streamable-http",
+                "url": mcp_url,
+                "supportedProtocolVersions": list(SUPPORTED_PROTOCOL_VERSIONS),
+            }
+        ],
+    }
+
+
+@auth_exempt
+def view_server_card(request: HttpRequest) -> JsonResponse:
+    """Return this plugin's MCP Server Card as JSON.
+
+    Deliberately unauthenticated, unlike the real MCP endpoint - this is
+    discovery metadata only (no InvenTree data), matching the passkey-endpoints
+    well-known view InvenTree ships built-in (core_wellknown.py).
+    """
+    return JsonResponse(build_server_card(request))
+
+
+urlpatterns = [path("server-card/", view_server_card, name="server-card")]

inventree_mcp/test_mcp.py

@@ -10,6 +10,7 @@
 from __future__ import annotations
 
 import datetime
+import importlib
 import json
 import sys
 import unittest
@@ -27,11 +28,13 @@
 from django.contrib.auth.models import AnonymousUser
 from django.contrib.contenttypes.models import ContentType
 from django.test import Client, override_settings
+from django.urls import reverse
 from django.utils import timezone
 from InvenTree.api_version import INVENTREE_API_VERSION
 from InvenTree.unit_test import InvenTreeTestCase
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.types import CallToolResult
+from mcp_types.version import SUPPORTED_PROTOCOL_VERSIONS
 from oauth2_provider.models import AccessToken, Application
 from order.models import (
     PurchaseOrder,
@@ -55,11 +58,12 @@
 )
 from users.models import ApiToken
 
-from . import context, tool_visibility, view_resolution
+from . import PLUGIN_VERSION, context, tool_visibility, view_resolution
 from .filter_introspection import _default_ordering_fields
 from .mcp_server import mcp
 from .proxy import call_view
 from .schema_introspection import paginated_schema, serializer_schema
+from .server_card import SERVER_CARD_SCHEMA, build_server_card
 from .settings import get_plugin_setting
 from .tools import discovery
 from .tools._common import DEFAULT_LIMIT, MAX_LIMIT, build_query_params, clamp_limit
@@ -2368,3 +2372,120 @@ async def test_every_list_tool_defaults_limit_to_100(self):
         }
 
         self.assertEqual(wrong_defaults, {})
+
+
+@override_settings(PLUGIN_TESTING_SETUP=True)
+class ServerCardTest(InvenTreeTestCase):
+    """Regression tests for the MCP Server Card well-known endpoint (server_card.py).
+
+    Implements SEP-2127 (https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)
+
+    Tests that the card is reachable and correctly shaped, and - separately, since
+    the two are independent failure modes - that it's actually wired into
+    WellKnownMixin (core.py's get_well_known_urls())
+    """
+
+    URL = "/plugin/inventree-mcp/server-card/"
+
+    @classmethod
+    def setUpTestData(cls):
+        super().setUpTestData()
+
+        registry.reload_plugins(full_reload=True, collect=True)
+        registry.set_plugin_state("inventree-mcp", True)
+
+    def test_server_card_is_reachable_without_authentication(self):
+        """Discovery metadata only, no InvenTree data - unlike the real MCP
+        endpoint (see MCPTransportTest.test_unauthenticated_request_rejected_by_default),
+        this must not require a credential.
+        """
+        response = Client().get(self.URL)
+
+        self.assertEqual(response.status_code, 200)
+        self.assertEqual(response["Content-Type"], "application/json")
+
+    def test_server_card_matches_the_sep_2127_shape(self):
+        response = Client().get(self.URL)
+        card = response.json()
+
+        self.assertEqual(card["$schema"], SERVER_CARD_SCHEMA)
+        # Reverse-DNS namespace + "/" + server name, per the schema's pattern.
+        self.assertRegex(card["name"], r"^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$")
+        self.assertEqual(card["version"], PLUGIN_VERSION)
+
+        [remote] = card["remotes"]
+        self.assertEqual(remote["type"], "streamable-http")
+        self.assertTrue(remote["url"].endswith("/plugin/inventree-mcp/mcp/"))
+        self.assertEqual(
+            remote["supportedProtocolVersions"], list(SUPPORTED_PROTOCOL_VERSIONS)
+        )
+
+    def test_build_server_card_resolves_a_real_absolute_mcp_url(self):
+        """Direct unit test of build_server_card() - the request-scoped absolute
+        URL building is the one part the HTTP-level tests above don't isolate.
+        """
+        response = Client().get(self.URL)
+        card = build_server_card(response.wsgi_request)
+
+        self.assertTrue(card["remotes"][0]["url"].startswith("http"))
+        self.assertIn("/plugin/inventree-mcp/mcp/", card["remotes"][0]["url"])
+
+    @override_settings(
+        SITE_URL="http://testserver", CSRF_TRUSTED_ORIGINS=["http://testserver"]
+    )
+    def test_server_card_is_discoverable_via_the_well_known_index(self):
+        """End-to-end regression test for InvenTreeMCP.get_well_known_urls() -
+        proves the card is reachable via InvenTree's aggregated /.well-known/
+        index (plugin/urls.py's wellknownindexview), the same mechanism the
+        built-in InvenTreeWellKnown plugin uses for passkey-endpoints.
+
+        The SITE_URL/CSRF_TRUSTED_ORIGINS override matches
+        InvenTreeWellKnownTest.test_well_known_urls in InvenTree core -
+        wellknownindexview's request.build_absolute_uri() rejects an
+        untrusted host otherwise.
+        """
+
+        import django.urls.exceptions
+
+        try:
+            response = Client().get(reverse("well-known:index"))
+        except django.urls.exceptions.NoReverseMatch:
+            # Exit early, this version of the InvenTree server does not have the well-known index.
+            return
+
+        self.assertEqual(response.status_code, 200)
+        data = response.json()
+        self.assertIn("mcp-server-card", data["well_known_urls"])
+        self.assertTrue(data["well_known_urls"]["mcp-server-card"].endswith(self.URL))
+
+
+class WellKnownCompatTest(unittest.TestCase):
+    """Regression test for _well_known_compat.py's WellKnownMixin fallback.
+
+    WellKnownMixin was added in inventree/InvenTree#12698 (merged to master,
+    not yet in a "stable" release as of writing) - InvenTreeMCP must still
+    import and load cleanly on InvenTree versions that don't provide it.
+    Simulates that by deleting the real mixin from plugin.mixins and
+    reloading the compat shim, rather than actually downgrading InvenTree.
+    """
+
+    def test_falls_back_to_a_blank_mixin_when_plugin_mixins_lacks_it(self):
+        import plugin.mixins as plugin_mixins
+
+        from . import _well_known_compat
+
+        try:
+            real_mixin = plugin_mixins.WellKnownMixin
+        except AttributeError:
+            # Exit early - the WellKnownMixin does not exist in this version of plugin.mixins
+            return
+
+        del plugin_mixins.WellKnownMixin
+        try:
+            reloaded = importlib.reload(_well_known_compat)
+
+            self.assertIsNot(reloaded.WellKnownMixin, real_mixin)
+            self.assertEqual(reloaded.WellKnownMixin().get_well_known_urls(), [])
+        finally:
+            plugin_mixins.WellKnownMixin = real_mixin
+            importlib.reload(_well_known_compat)