django-mcpz 1.0.0__tar.gz

django_mcpz-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Johnson
+
+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.

django_mcpz-1.0.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: django-mcpz
+Version: 1.0.0
+Summary: Easy peasy MCP servers in Django.
+Keywords: Django,MCP,Model Context Protocol
+Author: Adam Johnson
+Author-email: Adam Johnson <me@adamj.eu>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Typing :: Typed
+Requires-Dist: asgiref>=3.6
+Requires-Dist: django>=5.2
+Requires-Dist: django-msgspec>=1
+Requires-Dist: msgspec>=0.20
+Requires-Python: >=3.10
+Project-URL: Changelog, https://django-mcpz.readthedocs.io/en/latest/changelog.html
+Project-URL: Documentation, https://django-mcpz.readthedocs.io/
+Project-URL: Funding, https://adamj.eu/books/
+Project-URL: Repository, https://github.com/adamchainz/django-mcpz
+Description-Content-Type: text/x-rst
+
+===========
+django-mcpz
+===========
+
+.. image:: https://img.shields.io/readthedocs/django-mcpz?style=for-the-badge
+   :target: https://django-mcpz.readthedocs.io/en/latest/
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/django-mcpz/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/django-mcpz/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/django-mcpz/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/django-mcpz.svg?style=for-the-badge
+   :target: https://pypi.org/project/django-mcpz/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+*Easy peasy MCP servers in Django.*
+
+django-mcpz lets you build a Model Context Protocol (MCP) server in your Django project.
+Create an MCP server object with metadata, give it a URL, and attach Python functions to it as tools.
+The MCP server acts like a regular synchronous Django view, handling the intricacies of the MCP protocol.
+django-mcpz leans on `msgspec <https://msgspec.dev/>`__ for defining schemas and fast JSON serialization and deserialization.
+
+A quick example:
+
+.. code-block:: python
+
+    from typing import Literal
+
+    import msgspec
+
+    from django_mcpz.server import MCPServer
+    from django_mcpz.bearer_tokens.auth import token_auth
+    from example.models import Order
+
+    server = MCPServer(
+        name="shop",
+        version="1.0.0",
+        instructions="Query the shop’s order database.",
+        auth=token_auth,
+    )
+
+
+    class CountOrdersParams(msgspec.Struct):
+        status: Literal["pending", "shipped", "cancelled"] | None = None
+
+
+    class CountOrdersResult(msgspec.Struct):
+        count: int
+
+
+    @server.tool(
+        description="Count Order rows, optionally filtered by status.",
+        read_only=True,
+    )
+    def count_orders(request, params: CountOrdersParams) -> CountOrdersResult:
+        qs = Order.objects.all()
+        if params.status is not None:
+            qs = qs.filter(status=params.status)
+        return CountOrdersResult(count=qs.count())
+
+Documentation
+-------------
+
+Please see https://django-mcpz.readthedocs.io/.

django_mcpz-1.0.0/README.rst

@@ -0,0 +1,74 @@
+===========
+django-mcpz
+===========
+
+.. image:: https://img.shields.io/readthedocs/django-mcpz?style=for-the-badge
+   :target: https://django-mcpz.readthedocs.io/en/latest/
+
+.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/django-mcpz/main.yml.svg?branch=main&style=for-the-badge
+   :target: https://github.com/adamchainz/django-mcpz/actions?workflow=CI
+
+.. image:: https://img.shields.io/badge/Coverage-100%25-success?style=for-the-badge
+   :target: https://github.com/adamchainz/django-mcpz/actions?workflow=CI
+
+.. image:: https://img.shields.io/pypi/v/django-mcpz.svg?style=for-the-badge
+   :target: https://pypi.org/project/django-mcpz/
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
+   :target: https://github.com/psf/black
+
+.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
+   :target: https://github.com/pre-commit/pre-commit
+   :alt: pre-commit
+
+----
+
+*Easy peasy MCP servers in Django.*
+
+django-mcpz lets you build a Model Context Protocol (MCP) server in your Django project.
+Create an MCP server object with metadata, give it a URL, and attach Python functions to it as tools.
+The MCP server acts like a regular synchronous Django view, handling the intricacies of the MCP protocol.
+django-mcpz leans on `msgspec <https://msgspec.dev/>`__ for defining schemas and fast JSON serialization and deserialization.
+
+A quick example:
+
+.. code-block:: python
+
+    from typing import Literal
+
+    import msgspec
+
+    from django_mcpz.server import MCPServer
+    from django_mcpz.bearer_tokens.auth import token_auth
+    from example.models import Order
+
+    server = MCPServer(
+        name="shop",
+        version="1.0.0",
+        instructions="Query the shop’s order database.",
+        auth=token_auth,
+    )
+
+
+    class CountOrdersParams(msgspec.Struct):
+        status: Literal["pending", "shipped", "cancelled"] | None = None
+
+
+    class CountOrdersResult(msgspec.Struct):
+        count: int
+
+
+    @server.tool(
+        description="Count Order rows, optionally filtered by status.",
+        read_only=True,
+    )
+    def count_orders(request, params: CountOrdersParams) -> CountOrdersResult:
+        qs = Order.objects.all()
+        if params.status is not None:
+            qs = qs.filter(status=params.status)
+        return CountOrdersResult(count=qs.count())
+
+Documentation
+-------------
+
+Please see https://django-mcpz.readthedocs.io/.

django_mcpz-1.0.0/pyproject.toml

@@ -0,0 +1,152 @@
+[build-system]
+build-backend = "uv_build"
+requires = ["uv-build>=0.12.1,<0.13"]
+
+[project]
+name = "django-mcpz"
+version = "1.0.0"
+description = "Easy peasy MCP servers in Django."
+readme = "README.rst"
+keywords = [
+    "Django",
+    "MCP",
+    "Model Context Protocol",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Typing :: Typed",
+]
+dependencies = [
+    "asgiref>=3.6",
+    "django>=5.2",
+    "django-msgspec>=1",
+    "msgspec>=0.20",
+]
+
+[[project.authors]]
+name = "Adam Johnson"
+email = "me@adamj.eu"
+
+[project.urls]
+Changelog = "https://django-mcpz.readthedocs.io/en/latest/changelog.html"
+Documentation = "https://django-mcpz.readthedocs.io/"
+Funding = "https://adamj.eu/books/"
+Repository = "https://github.com/adamchainz/django-mcpz"
+
+[dependency-groups]
+test = [
+    "coverage[toml]",
+    "mcp>=2,<3",
+    "pytest>=9",
+    "pytest-django",
+    "pytest-randomly",
+]
+docs = [
+    "furo>=2024.8.6",
+    "sphinx>=7.4.7",
+    "sphinx-copybutton>=0.5.2",
+]
+django52 = ["django>=5.2a1,<6; python_version>='3.10'"]
+django60 = ["django>=6a1,<6.1; python_version>='3.12'"]
+django61 = ["django>=6.1a1,<6.2; python_version>='3.12'"]
+example = ["pillow>=10.1"]
+
+[tool.uv]
+conflicts = [[
+    { group = "django52" },
+    { group = "django60" },
+    { group = "django61" },
+]]
+
+[tool.ruff.lint]
+select = [
+    "B",
+    "C4",
+    "E",
+    "F",
+    "I",
+    "SIM",
+    "TID",
+    "UP",
+    "W",
+]
+ignore = [
+    "B9",
+    "E501",
+    "SIM105",
+    "SIM108",
+]
+extend-safe-fixes = ["UP006"]
+
+[tool.ruff.lint.isort]
+required-imports = ["from __future__ import annotations"]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.15"
+
+[tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
+warn_unreachable = true
+enable_error_code = [
+    "ignore-without-code",
+    "redundant-expr",
+    "truthy-bool",
+]
+strict = true
+plugins = ["mypy_django_plugin.main"]
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+allow_untyped_defs = true
+disallow_untyped_calls = false
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[tool.pytest]
+django_find_project = false
+DJANGO_SETTINGS_MODULE = "tests.settings"
+strict = true
+
+[tool.coverage.run]
+branch = true
+data_file = ".coverage/cov"
+parallel = true
+source = [
+    "django_mcpz",
+    "tests",
+]
+
+[tool.coverage.paths]
+source = [
+    "src",
+    ".tox/**/site-packages",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+skip_empty = true
+
+[tool.rstcheck]
+ignore_directives = ["setting"]
+ignore_roles = ["setting"]
+report_level = "ERROR"

django_mcpz-1.0.0/pyproject.toml.orig

@@ -0,0 +1,161 @@
+[build-system]
+build-backend = "uv_build"
+requires = [
+  "uv-build>=0.12.1,<0.13",
+]
+
+[project]
+name = "django-mcpz"
+version = "1.0.0"
+description = "Easy peasy MCP servers in Django."
+readme = "README.rst"
+keywords = [
+  "Django",
+  "MCP",
+  "Model Context Protocol",
+]
+license = "MIT"
+license-files = [ "LICENSE" ]
+authors = [
+  { name = "Adam Johnson", email = "me@adamj.eu" },
+]
+requires-python = ">=3.10"
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Django :: 5.2",
+  "Framework :: Django :: 6.0",
+  "Framework :: Django :: 6.1",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: 3.15",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Typing :: Typed",
+]
+dependencies = [
+  "asgiref>=3.6",
+  "django>=5.2",
+  "django-msgspec>=1",
+  "msgspec>=0.20",
+]
+urls.Changelog = "https://django-mcpz.readthedocs.io/en/latest/changelog.html"
+urls.Documentation = "https://django-mcpz.readthedocs.io/"
+urls.Funding = "https://adamj.eu/books/"
+urls.Repository = "https://github.com/adamchainz/django-mcpz"
+
+[dependency-groups]
+test = [
+  "coverage[toml]",
+  "mcp>=2,<3",
+  "pytest>=9",
+  "pytest-django",
+  "pytest-randomly",
+]
+docs = [
+  "furo>=2024.8.6",
+  "sphinx>=7.4.7",
+  "sphinx-copybutton>=0.5.2",
+]
+django52 = [ "django>=5.2a1,<6; python_version>='3.10'" ]
+django60 = [ "django>=6a1,<6.1; python_version>='3.12'" ]
+django61 = [ "django>=6.1a1,<6.2; python_version>='3.12'" ]
+example = [ "pillow>=10.1" ]
+
+[tool.uv]
+conflicts = [
+  [
+    { group = "django52" },
+    { group = "django60" },
+    { group = "django61" },
+  ],
+]
+
+[tool.ruff]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
+]
+lint.isort.required-imports = [ "from __future__ import annotations" ]
+
+[tool.pyproject-fmt]
+max_supported_python = "3.15"
+
+[tool.mypy]
+mypy_path = "src/"
+namespace_packages = false
+warn_unreachable = true
+enable_error_code = [
+  "ignore-without-code",
+  "redundant-expr",
+  "truthy-bool",
+]
+strict = true
+plugins = [ "mypy_django_plugin.main" ]
+overrides = [
+  { module = "tests.*", allow_untyped_defs = true, disallow_untyped_calls = false },
+]
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[tool.pytest]
+django_find_project = false
+DJANGO_SETTINGS_MODULE = "tests.settings"
+strict = true
+
+[tool.coverage]
+run.branch = true
+run.data_file = ".coverage/cov"
+run.parallel = true
+run.source = [
+  "django_mcpz",
+  "tests",
+]
+paths.source = [
+  "src",
+  ".tox/**/site-packages",
+]
+report.show_missing = true
+report.skip_covered = true
+report.skip_empty = true
+
+[tool.rstcheck]
+ignore_directives = [ "setting" ]
+ignore_roles = [ "setting" ]
+report_level = "ERROR"

django_mcpz-1.0.0/src/django_mcpz/bearer_tokens/admin.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from django.contrib import admin, messages
+from django.db.models import QuerySet
+from django.http import HttpRequest
+from django.utils import timezone
+
+from django_mcpz import tokens
+from django_mcpz.bearer_tokens.models import Token
+
+if TYPE_CHECKING:
+    ModelAdmin = admin.ModelAdmin[Token]
+else:
+    ModelAdmin = admin.ModelAdmin
+
+
+@admin.register(Token)
+class TokenAdmin(ModelAdmin):
+    list_display = [
+        "name",
+        "user",
+        "created_at",
+        "last_used_at",
+        "expires_at",
+        "revoked_at",
+    ]
+    list_filter = [("revoked_at", admin.EmptyFieldListFilter)]
+    search_fields = ["name"]
+    raw_id_fields = ["user"]
+    fields = [
+        "name",
+        "user",
+        "created_at",
+        "last_used_at",
+        "expires_at",
+        "revoked_at",
+    ]
+    # Revocation is one-way: it happens through the action, not the form.
+    readonly_fields = ["created_at", "last_used_at", "revoked_at"]
+    actions = ["revoke"]
+
+    def save_model(
+        self, request: HttpRequest, obj: Token, form: Any, change: bool
+    ) -> None:
+        if not change:
+            value = tokens.generate()
+            obj.digest = tokens.sha256_hex(value)
+            messages.success(
+                request,
+                f"Token created. Its value, shown only this once, is: {value}",
+            )
+        super().save_model(request, obj, form, change)
+
+    @admin.action(description="Revoke selected tokens")
+    def revoke(self, request: HttpRequest, queryset: QuerySet[Token]) -> None:
+        count = queryset.filter(revoked_at__isnull=True).update(
+            revoked_at=timezone.now()
+        )
+        messages.success(request, f"Revoked {count} token(s).")

django_mcpz-1.0.0/src/django_mcpz/bearer_tokens/apps.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class BearerTokensConfig(AppConfig):
+    name = "django_mcpz.bearer_tokens"
+    label = "django_mcpz_bearer_tokens"
+    verbose_name = "MCP bearer tokens"
+    default_auto_field = "django.db.models.BigAutoField"

django_mcpz-1.0.0/src/django_mcpz/bearer_tokens/auth.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from http import HTTPStatus
+
+from django.db.models import Q
+from django.http import HttpRequest, HttpResponse
+from django.utils import timezone
+
+from django_mcpz import tokens
+from django_mcpz.bearer_tokens.models import Token
+
+
+def token_auth(request: HttpRequest) -> HttpResponse | None:
+    """
+    Authenticate with a bearer token from the django_mcpz.bearer_tokens app.
+
+    Requires the Authorization header to carry an unrevoked, unexpired token,
+    for an active user, as a bearer credential. On success, attaches the Token as
+    request.mcp_token and sets request.user to the token's user.
+    """
+    header = request.headers.get("Authorization", "")
+    # The auth scheme is case-insensitive (RFC 9110 §11.1).
+    scheme, _, credential = header.partition(" ")
+    credential = credential.strip()
+    if scheme.lower() != "bearer" or not credential:
+        return _rejection()
+    try:
+        token = Token.objects.select_related("user").get(
+            Q(expires_at__isnull=True) | Q(expires_at__gt=timezone.now()),
+            digest=tokens.sha256_hex(credential),
+            revoked_at__isnull=True,
+        )
+    except Token.DoesNotExist:
+        return _rejection()
+    # Like Django's ModelBackend, treat a user model without is_active as
+    # always active.
+    if not getattr(token.user, "is_active", True):
+        return _rejection()
+    token.record_use()
+    request.mcp_token = token  # type: ignore[attr-defined]
+    request.user = token.user
+    return None
+
+
+def _rejection() -> HttpResponse:
+    return HttpResponse(
+        status=HTTPStatus.UNAUTHORIZED, headers={"WWW-Authenticate": "Bearer"}
+    )

django_mcpz-1.0.0/src/django_mcpz/bearer_tokens/cleanup.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from django.db.models import Q
+from django.utils import timezone
+
+from django_mcpz.bearer_tokens.models import Token
+
+
+def clear_expired() -> int:
+    """
+    Delete expired and revoked bearer tokens.
+
+    Returns the number deleted.
+    """
+    return Token.objects.filter(
+        Q(expires_at__lt=timezone.now()) | Q(revoked_at__isnull=False)
+    ).delete()[0]