inventree-mcp 0.3.0__tar.gz

inventree_mcp-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Oliver Walters <admin@inventree.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

inventree_mcp-0.3.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include inventree_mcp/static *

inventree_mcp-0.3.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: inventree-mcp
+Version: 0.3.0
+Summary: MCP server for InvenTree
+Author-email: Oliver Walters <admin@inventree.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/inventree/inventree-mcp
+Keywords: inventree,plugin
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: InvenTree
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<3,>=2.0
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Dynamic: license-file
+
+# InvenTreeMCP
+
+[![PyPI](https://img.shields.io/pypi/v/inventree-mcp)](https://pypi.org/project/inventree-mcp/)
+[![CI](https://github.com/inventree/inventree-mcp/actions/workflows/ci.yaml/badge.svg)](https://github.com/inventree/inventree-mcp/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/inventree/inventree-mcp/graph/badge.svg)](https://codecov.io/gh/inventree/inventree-mcp)
+
+An MCP (Model Context Protocol) server for InvenTree, exposed as an InvenTree plugin. It lets MCP
+clients (Claude, other MCP-aware agents) query InvenTree inventory data over a Streamable HTTP
+endpoint.
+
+## Design
+
+Every tool is a thin wrapper around InvenTree's own REST API view classes (see
+[`inventree_mcp/proxy.py`](inventree_mcp/proxy.py)), dispatched as the authenticated caller - MCP
+requests go through exactly the same permission checks, filtering, and serialization as the regular
+REST API. Tool code never queries the Django ORM directly.
+
+Currently read-only, covering parts, stock items/locations, part categories, purchase/sales/return/
+build orders (with line items and allocations), companies, contacts, addresses, manufacturer/
+supplier parts, BOM items, attachments, parameters, stock tracking history, test results, and
+project codes. Once write tools land, the `MCP_READ_ONLY` setting (see Configuration) will block
+them by default regardless of the calling user's permissions.
+
+Each tool's `outputSchema` and filter/ordering options are derived live from InvenTree's own
+serializers and views (not hand-maintained), so they can't drift as InvenTree evolves. Call
+`describe_filters(resource)` to see what's available for a given resource. The set of tools an MCP
+client sees is also filtered to what the calling user can actually use - though every call is still
+permission-checked in full regardless of what was advertised.
+
+## Setup
+
+### 1. Install the plugin
+
+Install via the InvenTree plugin manager, or via pip:
+
+```bash
+pip install inventree-mcp
+```
+
+Then enable the plugin under **Admin > Plugins**, and configure its settings (see
+Configuration below).
+
+### 2. Create a token for your MCP client
+
+Create an InvenTree API token for your MCP client.
+
+### 3. Configure your MCP client
+
+The endpoint is `<your-inventree-server>/plugin/inventree-mcp/mcp/`, using Streamable HTTP
+transport with an `Authorization: Token <token>` header.
+
+For a client that supports remote Streamable HTTP servers directly, add:
+
+```json
+{
+  "mcpServers": {
+    "inventree": {
+      "url": "https://<your-inventree-server>/plugin/inventree-mcp/mcp/",
+      "headers": {
+        "Authorization": "Token <your-api-token>"
+      }
+    }
+  }
+}
+```
+
+For a client that only supports local (stdio) servers, bridge it with
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
+
+*Note: You will need to have node available on your system path*
+
+```json
+{
+  "mcpServers": {
+    "inventree": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "https://<your-inventree-server>/plugin/inventree-mcp/mcp/",
+        "--header",
+        "Authorization: Token <your-api-token>"
+      ]
+    }
+  }
+}
+```
+
+*Note: On Windows, you may need to substitute `npx` with `C:\\PROGRA~1\\nodejs\\npx.cmd` in the command field.*
+
+In a setup where the server is running a self-signed certificate, you may need to use the following `env` arguments to disable certificate verification:
+
+```json
+"args": [
+  ...
+],
+"env": {
+  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+}
+```
+
+## Configuration
+
+Under **Settings > Plugin Settings**:
+
+- **Require Authentication** (`REQUIRE_AUTH`, default `True`): reject unauthenticated requests.
+  Only disable for local testing.
+- **Read Only** (`MCP_READ_ONLY`, default `True`): block all write actions via MCP, regardless of
+  the calling user's permissions. A plugin-wide kill switch, independent of per-user roles.
+
+## Authentication
+
+Access follows the calling user's normal InvenTree role assignments. Supported auth methods:
+
+- An InvenTree API token: `Authorization: Token <token>`.
+- Basic auth (username/password).
+- An OAuth2 bearer token: `Authorization: Bearer <token>`. A scoped token (e.g. `r:view:part`)
+  narrows access *below* the underlying user's roles - useful for issuing an agent a tightly-scoped
+  token without creating a separate low-privilege user.
+
+Session/cookie auth is not supported (not meaningful for a machine client).

inventree_mcp-0.3.0/README.md

@@ -0,0 +1,121 @@
+# InvenTreeMCP
+
+[![PyPI](https://img.shields.io/pypi/v/inventree-mcp)](https://pypi.org/project/inventree-mcp/)
+[![CI](https://github.com/inventree/inventree-mcp/actions/workflows/ci.yaml/badge.svg)](https://github.com/inventree/inventree-mcp/actions/workflows/ci.yaml)
+[![codecov](https://codecov.io/gh/inventree/inventree-mcp/graph/badge.svg)](https://codecov.io/gh/inventree/inventree-mcp)
+
+An MCP (Model Context Protocol) server for InvenTree, exposed as an InvenTree plugin. It lets MCP
+clients (Claude, other MCP-aware agents) query InvenTree inventory data over a Streamable HTTP
+endpoint.
+
+## Design
+
+Every tool is a thin wrapper around InvenTree's own REST API view classes (see
+[`inventree_mcp/proxy.py`](inventree_mcp/proxy.py)), dispatched as the authenticated caller - MCP
+requests go through exactly the same permission checks, filtering, and serialization as the regular
+REST API. Tool code never queries the Django ORM directly.
+
+Currently read-only, covering parts, stock items/locations, part categories, purchase/sales/return/
+build orders (with line items and allocations), companies, contacts, addresses, manufacturer/
+supplier parts, BOM items, attachments, parameters, stock tracking history, test results, and
+project codes. Once write tools land, the `MCP_READ_ONLY` setting (see Configuration) will block
+them by default regardless of the calling user's permissions.
+
+Each tool's `outputSchema` and filter/ordering options are derived live from InvenTree's own
+serializers and views (not hand-maintained), so they can't drift as InvenTree evolves. Call
+`describe_filters(resource)` to see what's available for a given resource. The set of tools an MCP
+client sees is also filtered to what the calling user can actually use - though every call is still
+permission-checked in full regardless of what was advertised.
+
+## Setup
+
+### 1. Install the plugin
+
+Install via the InvenTree plugin manager, or via pip:
+
+```bash
+pip install inventree-mcp
+```
+
+Then enable the plugin under **Admin > Plugins**, and configure its settings (see
+Configuration below).
+
+### 2. Create a token for your MCP client
+
+Create an InvenTree API token for your MCP client.
+
+### 3. Configure your MCP client
+
+The endpoint is `<your-inventree-server>/plugin/inventree-mcp/mcp/`, using Streamable HTTP
+transport with an `Authorization: Token <token>` header.
+
+For a client that supports remote Streamable HTTP servers directly, add:
+
+```json
+{
+  "mcpServers": {
+    "inventree": {
+      "url": "https://<your-inventree-server>/plugin/inventree-mcp/mcp/",
+      "headers": {
+        "Authorization": "Token <your-api-token>"
+      }
+    }
+  }
+}
+```
+
+For a client that only supports local (stdio) servers, bridge it with
+[`mcp-remote`](https://www.npmjs.com/package/mcp-remote)
+
+*Note: You will need to have node available on your system path*
+
+```json
+{
+  "mcpServers": {
+    "inventree": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "mcp-remote@latest",
+        "https://<your-inventree-server>/plugin/inventree-mcp/mcp/",
+        "--header",
+        "Authorization: Token <your-api-token>"
+      ]
+    }
+  }
+}
+```
+
+*Note: On Windows, you may need to substitute `npx` with `C:\\PROGRA~1\\nodejs\\npx.cmd` in the command field.*
+
+In a setup where the server is running a self-signed certificate, you may need to use the following `env` arguments to disable certificate verification:
+
+```json
+"args": [
+  ...
+],
+"env": {
+  "NODE_TLS_REJECT_UNAUTHORIZED": "0"
+}
+```
+
+## Configuration
+
+Under **Settings > Plugin Settings**:
+
+- **Require Authentication** (`REQUIRE_AUTH`, default `True`): reject unauthenticated requests.
+  Only disable for local testing.
+- **Read Only** (`MCP_READ_ONLY`, default `True`): block all write actions via MCP, regardless of
+  the calling user's permissions. A plugin-wide kill switch, independent of per-user roles.
+
+## Authentication
+
+Access follows the calling user's normal InvenTree role assignments. Supported auth methods:
+
+- An InvenTree API token: `Authorization: Token <token>`.
+- Basic auth (username/password).
+- An OAuth2 bearer token: `Authorization: Bearer <token>`. A scoped token (e.g. `r:view:part`)
+  narrows access *below* the underlying user's roles - useful for issuing an agent a tightly-scoped
+  token without creating a separate low-privilege user.
+
+Session/cookie auth is not supported (not meaningful for a machine client).

inventree_mcp-0.3.0/inventree_mcp/__init__.py

@@ -0,0 +1 @@
+PLUGIN_VERSION = "0.3.0"

inventree_mcp-0.3.0/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-0.3.0/inventree_mcp/context.py

@@ -0,0 +1,98 @@
+"""Propagate the authenticated Django user (and OAuth2 auth, if any) into MCP tool execution.
+
+Tool functions are invoked by the MCP SDK's dispatcher, which does not know
+about Django requests. The transport view sets the current identity via a
+contextvar before handing the request off to the MCP session manager, so
+tools (and the proxy layer) can recover *who* is calling without threading a
+request object through every tool signature.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from django.contrib.auth.models import AbstractUser
+
+
+@dataclass(frozen=True)
+class _Identity:
+    user: AbstractUser
+    # The real oauth2_provider AccessToken, if the MCP request itself was
+    # OAuth2-authenticated - None for token/basic/session auth. Propagated so
+    # proxy.call_view() can make the proxied view see the token's *actual*
+    # granted scopes, not just the user's role permissions. See proxy.py.
+    oauth2_token: Any | None = None
+
+
+_current_identity: ContextVar[_Identity | None] = ContextVar(
+    "inventree_mcp_current_identity", default=None
+)
+
+
+def set_current_user(
+    user: AbstractUser | None, oauth2_token: Any | None = None
+) -> Token:
+    """Bind *user* (and, if OAuth2-authenticated, the real access token) for this context."""
+    identity = _Identity(user, oauth2_token) if user is not None else None
+    return _current_identity.set(identity)
+
+
+def reset_current_user(token: Token) -> None:
+    """Undo a prior set_current_user call."""
+    _current_identity.reset(token)
+
+
+def has_bound_identity() -> bool:
+    """Return whether set_current_user() has been called in this context at all.
+
+    True for *any* real MCP request - including one that resolved to an
+    unauthenticated (AnonymousUser) identity, e.g. REQUIRE_AUTH disabled and
+    no credentials were sent. False only outside a real request (e.g. static
+    introspection - see has_current_user()'s docstring). Distinct from
+    has_current_user(): that answers "is there someone to check permissions
+    for", this answers "did a request happen at all" - callers that need to
+    tell "no request" (safe to skip filtering) apart from "a request with no
+    authenticated user" (should filter down to nothing, not everything) need
+    this one, not has_current_user().
+    """
+    return _current_identity.get() is not None
+
+
+def has_current_user() -> bool:
+    """Return whether an *authenticated* user is currently bound.
+
+    False both outside a real MCP request (see has_bound_identity() to tell
+    that case apart) and for a real request that resolved to an
+    unauthenticated (AnonymousUser) identity - callers that only need "is
+    there someone to check permissions for" (e.g. tool_logging.py's caller
+    label) can treat both the same way; callers that need to react
+    differently to the two (e.g. tool_visibility.py, which must not show
+    every tool just because this request happened to be unauthenticated)
+    should check has_bound_identity() first.
+    """
+    identity = _current_identity.get()
+    return identity is not None and identity.user.is_authenticated
+
+
+def get_current_user() -> AbstractUser:
+    """Return the user bound to the current MCP request.
+
+    Raises:
+        PermissionError: if no user is bound (e.g. a tool is invoked outside
+            of a real MCP request, or authentication was not enforced).
+    """
+    identity = _current_identity.get()
+
+    if identity is None or not identity.user.is_authenticated:
+        raise PermissionError("No authenticated user for this MCP request")
+
+    return identity.user
+
+
+def get_current_oauth2_token() -> Any | None:
+    """Return the real OAuth2 access token for the current MCP request, if any."""
+    identity = _current_identity.get()
+    return identity.oauth2_token if identity else None

inventree_mcp-0.3.0/inventree_mcp/core.py

@@ -0,0 +1,67 @@
+"""MCP server for InvenTree"""
+
+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(WellKnownMixin, SettingsMixin, UrlsMixin, InvenTreePlugin):
+    """InvenTreeMCP - custom InvenTree plugin."""
+
+    # Plugin metadata
+    TITLE = "InvenTree MCP"
+    NAME = "InvenTreeMCP"
+    SLUG = "inventree-mcp"
+    DESCRIPTION = "MCP server for InvenTree"
+    VERSION = PLUGIN_VERSION
+
+    # Additional project information
+    AUTHOR = "Oliver Walters"
+    WEBSITE = "https://github.com/inventree/inventree-mcp"
+    LICENSE = "MIT"
+
+    # Supported InvenTree versions
+    MIN_VERSION = "1.5.0"
+
+    # Plugin settings (from SettingsMixin)
+    # Ref: https://docs.inventree.org/en/latest/plugins/mixins/settings/
+    SETTINGS: ClassVar[dict] = {
+        "REQUIRE_AUTH": {
+            "name": "Require Authentication",
+            "description": "Reject unauthenticated requests to the MCP endpoint. Disable only for local testing.",
+            "validator": bool,
+            "default": True,
+        },
+        "MCP_READ_ONLY": {
+            "name": "Read Only",
+            "description": "Block all write actions via the MCP endpoint, regardless of the calling user's permissions.",
+            "validator": bool,
+            "default": True,
+        },
+        "MCP_LOG_TOOL_CALLS": {
+            "name": "Log Tool Calls",
+            "description": "Log every MCP tool call (tool name, arguments, calling user, and outcome) to the 'inventree' logger for debugging.",
+            "validator": bool,
+            "default": False,
+        },
+    }
+
+    # Custom URL endpoints (from UrlsMixin)
+    # 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 as mcp_urlpatterns
+        from .server_card import urlpatterns as server_card_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-0.3.0/inventree_mcp/expand_introspection.py

@@ -0,0 +1,49 @@
+"""Describe a view's optional output-expansion flags (e.g. `part_detail`).
+
+Many InvenTree list/detail views can inline a related object's full detail
+into the response on request (`?part_detail=true` on the stock API embeds
+the full Part, avoiding a separate get_part call) rather than only exposing
+its ID. These flags are declared once per view as `output_options`, an
+`InvenTree.fields.OutputConfiguration` subclass listing `InvenTreeOutputOption`
+instances (flag name, default, description) - the same metadata InvenTree's
+own OpenAPI schema is generated from (see `InvenTree.schema.
+schema_for_view_output_options`). Reading it here means this can't drift
+from the real API the way a hand-maintained list per resource would.
+
+Not every view declares `output_options` (flat resources with no
+expandable relations, e.g. Company, Attachment, don't need it) -
+describe_output_options() returns an empty dict for those rather than
+raising, same permissive spirit as filter_introspection.py.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def describe_output_options(view_cls: type) -> dict[str, Any]:
+    """Describe the optional output-expansion flags available on *view_cls*.
+
+    Args:
+        view_cls: a list or detail view class as used in the real API
+            urlconf (e.g. stock.api.StockList or stock.api.StockDetail).
+            Both a resource's list and detail view conventionally share the
+            same `output_options` class, so either works.
+
+    Returns:
+        A dict of {flag_name: {default_included, description}} - each key
+        is a boolean query parameter that can be passed directly in a
+        list/get tool's `filters` argument, e.g. filters={"part_detail": true}.
+        Empty if the view declares no `output_options`.
+    """
+    output_config = getattr(view_cls, "output_options", None)
+    if output_config is None:
+        return {}
+
+    return {
+        option.flag: {
+            "default_included": bool(option.default),
+            "description": option.description,
+        }
+        for option in output_config.OPTIONS
+    }