py-1.3.0 shipped — workspace_root is now a first-class argument, silent failure closed

[FROWNINGdev]

py-1.3.0 shipped — closes a silent-failure class that also lives in five other MCP servers I could find.

The bug

Every one of the 9 tools accepted a workspace_root argument that FastMCP silently dropped. Any AI agent inspecting the tools/list schema saw no workspace_root field, so they intuitively passed it anyway (Cursor and Claude Desktop do this on the first call). FastMCP treats unknown kwargs as noise; the tool fell back to $DJANGO_ORM_LENS_ROOT or cwd. When cwd was not a Django project, list_apps returned [] — no error, no hint. The agent assumed the server was broken and moved on.

Same symptom in the wild: microsoft/AL#8273, openai/codex#9989, aws-toolkit-jetbrains#6173, kirodotdev/Kiro#5662, modelcontextprotocol/python-sdk#1097.

The fix — three parts

1. workspace_root: str = "" on all 9 tool signatures. FastMCP now advertises it in inputSchema and the value reaches the handler unchanged. Priority: explicit arg → $DJANGO_ORM_LENS_ROOT → cwd. Ported from the official filesystem-server pattern.
2. Path hardening. expanduser + expandvars + Path.resolve() before any validation collapses .. and follows symlinks. Windows reserved names (CON, PRN, AUX, NUL, COMn, LPTn) rejected on every OS. Django-marker required (manage.py / django in pyproject.toml / any models.py).
3. Structured error envelope, not []. Seven stable codes: WORKSPACE_EMPTY, WORKSPACE_NOT_FOUND, WORKSPACE_NOT_A_DIRECTORY, WORKSPACE_NOT_DJANGO, WORKSPACE_NOT_ALLOWED, WORKSPACE_WINDOWS_RESERVED, WORKSPACE_RESOLVE_FAILED. Every failure returns {"error": "…", "hint": "…"}.

Before / after

> list_apps(workspace_root="/typo")
Before: []
After:  {"error": "WORKSPACE_NOT_FOUND",
         "hint": "Check the workspace_root argument, or omit it to fall back to cwd"}

Tests

23 unit + 22 integration + 18 subtests in two new files. Full Python suite: 236 passed (was 191), zero regressions. TS suite: 104/104 unchanged. E2E round-trip on the freshly-published PyPI wheel: 9/9 tools advertise workspace_root, happy path returns real 4-app result, invalid path returns actionable envelope.

Deliberately not done

MCP roots/list (native workspace discovery) is skipped — the SDK issue linked above tracks a client-side deadlock. Sync fix with explicit-arg-first covers 100% of real cases. Async roots layer will come later, behind a capability check.

Install / upgrade

pip install --upgrade "django-orm-lens[mcp]"
uvx --from django-orm-lens[mcp] django-orm-lens-mcp
docker pull ghcr.io/frowningdev/django-orm-lens:1.3.0

No config change required. The argument is optional and the env-var workflow still works — existing Cursor / Claude Desktop / Aider setups keep working. Just upgrade.

Release notes: https://github.com/FROWNINGdev/django-orm-lens/releases/tag/py-v1.3.0

Feedback welcome — if you hit anything, open an issue and I will look at it same-day.

[FROWNINGdev]

A small nicety I noticed after shipping this — the compound cache key (resolved_path, manage.py mtime) also makes the tool robust to a common agent workflow where they scaffold a new app between two list_apps calls. The mtime bump invalidates the entry immediately, so the second call reflects the new app without waiting for the 30s TTL. If you're doing agent-assisted startapp scaffolding in the same session, this should just work.

For mono-repos with multiple Django projects: the per-call workspace_root argument lets a single MCP server instance switch between projects mid-session. You don't need to spawn 5 separate servers for 5 apps in the same repo — set DJANGO_ORM_LENS_ROOT in env to your default project, and the agent can override with workspace_root="/monorepo/project-b" on any tool that needs to look elsewhere. The LRU cap of 8 in the cache means realistic multi-project agents won't unbounded-grow memory.