Metadata-Version: 2.4
Name: django-xprez-mcp
Version: 0.2.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.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.2
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) and 2 (models). See
[docs/design.md](docs/design.md) for the full design and roadmap.

```python
# settings.py
INSTALLED_APPS = [..., "xprez_mcp"]
XPREZ_MCP = {
    "TOKEN_RESOLVER": "myapp.tokens.resolve",  # (request, token) -> user | None
    "PERMISSION": "myapp.use_mcp",  # required: who may use the server at all
}

# urls.py
from xprez_mcp import mcp

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

```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(models="generic")` exposes them through a few
shared tools (`models_list`, `records_search`, `record_get`, ...) instead of
tools per model.

## 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 .
```
