Metadata-Version: 2.4
Name: django-xprez-mcp
Version: 0.5.0
Summary: Admin-style MCP servers for Django: register providers, models, admin classes and functions as MCP tools, resources and prompts.
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/s-cape/django_xprez_mcp
Project-URL: Documentation, https://github.com/s-cape/django_xprez_mcp/blob/main/docs/design.md
Project-URL: Issues, https://github.com/s-cape/django_xprez_mcp/issues
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.1
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: djangorestframework; extra == "dev"
Dynamic: license-file

# django-xprez-mcp

Admin-style MCP servers for Django. Register providers, models, admin classes
and plain functions on a server; they become MCP tools, resources and prompts,
filtered by the calling user's permissions.

Early development: phases 1 (core), 2 (models) and 3 (admin). See
[docs/design.md](docs/design.md) for the full design and roadmap.

Guides: [getting started](docs/getting-started.md),
[permissions](docs/permissions.md), [security checklist](docs/security.md).

```python
# settings.py
INSTALLED_APPS = [..., "xprez_mcp", "xprez_mcp.contrib.tokens"]
XPREZ_MCP = {
    "PERMISSION": "myapp.use_mcp",  # required: who may use the server at all
}

# urls.py
from xprez_mcp import mcp

urlpatterns = [path("mcp/", mcp.urls)]
```

Clients send `Authorization: Bearer <key>`. With `xprez_mcp.contrib.tokens`
users create keys under "MCP tokens" in the admin (shown once, stored hashed,
revoked by deleting). Projects with their own token model leave the app out
and set `XPREZ_MCP["TOKEN_RESOLVER"] = "myapp.tokens.resolve"`
(`(request, token) -> user | None`).

```python
# myapp/mcp.py: discovered automatically, like admin.py
from xprez_mcp import Provider, mcp, prompt, resource, tool


@mcp.register
class NotesProvider(Provider):
    namespace = "notes"

    @tool(read_only=True, permission="myapp.view_note")
    def search(self, ctx, query: str, limit: int = 20):
        """Search notes by title."""
        notes = Note.objects.filter(owner=ctx.user, title__icontains=query)
        return {"notes": list(notes.values("id", "title")[:limit])}

    @resource("notes://{id}", mime_type="text/markdown")
    def note(self, ctx, id: int):
        return Note.objects.get(owner=ctx.user, pk=id).text

    @prompt
    def summary(self, ctx, id: int):
        """Summarize one note."""
        return f"Summarize the note notes://{id}."


@mcp.tool
def ping(ctx) -> str:
    return "pong"
```

```python
# myapp/mcp.py: tools generated from a model
from xprez_mcp import ModelProvider, mcp


@mcp.register(Note)
class NoteProvider(ModelProvider):
    fields = ["id", "title", "created"]
    search_fields = ["title"]
    filters = {"created_after": "created__gte"}
    actions = ["list", "get", "update"]  # notes_list, notes_get, notes_update

    def get_queryset(self, ctx):
        return Note.objects.filter(owner=ctx.user)
```

With many models, `MCPServer(exposure="generic")` exposes them through a few
shared tools (`models_list`, `records_search`, `record_get`, ...) instead of
tools per model. A provider can choose for itself with `exposure`.

```python
# the admin, with exactly the permissions each user has there
from django.contrib import admin
from xprez_mcp import AdminProvider, mcp


@mcp.register(Note)
class NoteAdminProvider(AdminProvider):  # uses the registered NoteAdmin
    actions = ["list", "get", "update"]  # writes are opt-in
    admin_actions = ["publish"]          # ModelAdmin actions, opt-in


# the rest of admin.site (models registered above keep their own provider)
mcp.register_admin(admin.site, exposure="generic")
```

Write tools from installed third-party apps are held back until listed in
`XPREZ_MCP["ALLOW_WRITES"]`.

## Development

```bash
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m django test xprez_mcp.tests --settings=xprez_mcp.tests.settings
.venv/bin/black --check .
```
