Add resources for Django project, app, and model exploration (#24)

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,14 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- MCP resources for exploring the project environment, Django apps, and models without shell execution.
+
+### Changed
+
+- Updated server instructions to guide LLMs to use resources for project orientation before shell operations.
+
 ### Removed
 
 - Removed redundant input field from `django_shell` tool response to reduce output verbosity.

README.md

@@ -158,20 +158,14 @@ Don't see your client? [Submit a PR](CONTRIBUTING.md) with setup instructions.
 }
 ```
 
-## Usage
+## Features
 
 mcp-django-shell provides an MCP server with a stateful Django shell for AI assistants. It sets up Django, maintains session state between calls, and lets the AI write and execute Python code directly against your project.
 
-The MCP server comes with just two tools:
-
-- `django_shell` - Execute Python code in a persistent Django shell session
-- `django_reset` - Reset the session, clearing all variables and imports
-
-Imports and variables persist between calls, so the AI can work iteratively - exploring your models, testing queries, debugging issues.
-
 It wouldn't be an MCP server README without a gratuitous list of features punctuated by emojis, so:
 
-- 🐚 **One tool** - `django_shell` executes Python code in your Django environment
+- 🐚 **Stateful shell** - `django_shell` executes Python code in your Django environment
+- 🔍 **Project exploration** - MCP resources for discovering apps, models, and configuration
 - 🔄 **Persistent state** - Imports and variables stick around between calls
 - 🧹 **Reset when needed** - `django_reset` clears the session when things get weird
 - 🚀 **Zero configuration** - No schemas, no settings, just Django
@@ -182,6 +176,25 @@ It wouldn't be an MCP server README without a gratuitous list of features punctu
 
 Inspired by Armin Ronacher's [Your MCP Doesn't Need 30 Tools: It Needs Code](https://lucumr.pocoo.org/2025/8/18/code-mcps/).
 
+### Resources
+
+Read-only resources are provided for project exploration without executing code (note that resource support varies across MCP clients):
+
+- `django://project` - Python environment and Django configuration details
+- `django://apps` - All installed Django applications with their models
+- `django://models` - Detailed model information with import paths and field types
+
+The idea is to give just enough information about the project to hopefully guide the LLM assistant and prevent needless shell exploration, allowing it to get straight to work.
+
+### Tools
+
+Two tools handle shell operations and session management:
+
+- `django_shell` - Execute Python code in a persistent Django shell session
+- `django_reset` - Reset the session, clearing all variables and imports
+
+Imports and variables persist between calls within the shell tool, so the AI can work iteratively - exploring your models, testing queries, debugging issues.
+
 ## Development
 
 For detailed instructions on setting up a development environment and contributing to this project, see [CONTRIBUTING.md](CONTRIBUTING.md).

src/mcp_django_shell/resources.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import inspect
+import os
+import sys
+from pathlib import Path
+from typing import Any
+from typing import Literal
+
+import django
+from django.apps import AppConfig
+from django.apps import apps
+from django.conf import settings
+from django.contrib.auth import get_user_model
+from django.db import models
+from pydantic import BaseModel
+from pydantic import field_serializer
+
+
+def get_source_file_path(obj: Any) -> Path:
+    target = obj if inspect.isclass(obj) else obj.__class__
+    try:
+        return Path(inspect.getfile(target))
+    except (TypeError, OSError):
+        return Path("unknown")
+
+
+class ProjectResource(BaseModel):
+    python: PythonResource
+    django: DjangoResource
+
+    @classmethod
+    def from_env(cls) -> ProjectResource:
+        py = PythonResource.from_sys()
+        dj = DjangoResource.from_django()
+        return ProjectResource(python=py, django=dj)
+
+
+class PythonResource(BaseModel):
+    base_prefix: Path
+    executable: Path
+    path: list[Path]
+    platform: str
+    prefix: Path
+    version_info: tuple[
+        int, int, int, Literal["alpha", "beta", "candidate", "final"], int
+    ]
+
+    @classmethod
+    def from_sys(cls) -> PythonResource:
+        return cls(
+            base_prefix=Path(sys.base_prefix),
+            executable=Path(sys.executable),
+            path=[Path(p) for p in sys.path],
+            platform=sys.platform,
+            prefix=Path(sys.prefix),
+            version_info=sys.version_info,
+        )
+
+
+class DjangoResource(BaseModel):
+    apps: list[str]
+    auth_user_model: str | None
+    base_dir: Path
+    databases: dict[str, dict[str, str]]
+    debug: bool
+    settings_module: str
+    version: tuple[int, int, int, Literal["alpha", "beta", "rc", "final"], int]
+
+    @classmethod
+    def from_django(cls) -> DjangoResource:
+        app_names = [app_config.name for app_config in apps.get_app_configs()]
+
+        databases = {
+            db_alias: {
+                "engine": db_config.get("ENGINE", ""),
+                "name": str(db_config.get("NAME", "")),
+            }
+            for db_alias, db_config in settings.DATABASES.items()
+        }
+
+        if "django.contrib.auth" in app_names:
+            user_model = get_user_model()
+            auth_user_model = f"{user_model.__module__}.{user_model.__name__}"
+        else:
+            auth_user_model = None
+
+        return cls(
+            apps=app_names,
+            auth_user_model=auth_user_model,
+            base_dir=Path(getattr(settings, "BASE_DIR", Path.cwd())),
+            databases=databases,
+            debug=settings.DEBUG,
+            settings_module=os.environ.get("DJANGO_SETTINGS_MODULE", ""),
+            version=django.VERSION,
+        )
+
+
+class AppResource(BaseModel):
+    name: str
+    label: str
+    path: Path
+    models: list[ModelResource]
+
+    @classmethod
+    def from_app(cls, app: AppConfig) -> AppResource:
+        appconfig = get_source_file_path(app)
+        app_path = appconfig.parent if appconfig != Path("unknown") else Path("unknown")
+
+        app_models = (
+            [
+                ModelResource.from_model(model)
+                for model in app.models.values()
+                if not model._meta.auto_created
+            ]
+            if app.models
+            else []
+        )
+
+        return cls(name=app.name, label=app.label, path=app_path, models=app_models)
+
+    @field_serializer("models")
+    def serialize_models(self, models: list[ModelResource]) -> list[str]:
+        return [model.model_dump()["model_class"] for model in models]
+
+
+class ModelResource(BaseModel):
+    model_class: type[models.Model]
+    import_path: str
+    source_path: Path
+    fields: dict[str, str]
+
+    @classmethod
+    def from_model(cls, model: type[models.Model]):
+        field_types = {
+            field.name: field.__class__.__name__ for field in model._meta.fields
+        }
+
+        return cls(
+            model_class=model,
+            import_path=f"{model.__module__}.{model.__name__}",
+            source_path=get_source_file_path(model),
+            fields=field_types,
+        )
+
+    @field_serializer("model_class")
+    def serialize_model_class(self, klass: type[models.Model]) -> str:
+        return klass.__name__

src/mcp_django_shell/server.py

@@ -3,17 +3,47 @@
 import logging
 from typing import Annotated
 
+from django.apps import apps
 from fastmcp import Context
 from fastmcp import FastMCP
 from mcp.types import ToolAnnotations
 
 from .output import DjangoShellOutput
 from .output import ErrorOutput
+from .resources import AppResource
+from .resources import ModelResource
+from .resources import ProjectResource
 from .shell import DjangoShell
 
 mcp = FastMCP(
     name="Django Shell",
-    instructions="Provides a stateful Django shell environment for executing Python code, managing sessions, and exporting command history.",
+    instructions="""Provides Django resource endpoints for project exploration and a stateful shell environment for executing Python code.
+
+RESOURCES:
+Use resources for orientation, then use the shell for all actual work. Resources provide
+precise coordinates (import paths, file locations) to avoid exploration overhead.
+
+- django://project - Python/Django environment metadata (versions, settings, database config)
+- django://apps - All Django apps with their file paths
+- django://models - All models with import paths and source locations
+
+TOOLS:
+The shell maintains state between calls - imports and variables persist. Use django_reset to
+clear state when variables get messy or you need a fresh start.
+
+- django_shell - Execute Python code in a stateful Django shell
+- django_reset - Reset the shell session
+
+EXAMPLES:
+The pattern: Resource → Import Path → Shell Operation. Resources provide coordinates, shell does
+the work.
+
+- Starting fresh? → Check django://project to understand environment and available apps
+- Need information about a model? → Check django://models → Get import path →
+  `from app.models import ModelName` in django_shell
+- Need app structure? → Check django://apps for app labels and paths → Use paths in django_shell
+- Need to query data? → Get model from django://models → Import in django_shell → Run queries
+""",
 )
 shell = DjangoShell()
 logger = logging.getLogger(__name__)
@@ -100,3 +130,46 @@ async def django_reset(ctx: Context) -> str:
     )
 
     return "Django shell session has been reset. All previously set variables and history cleared."
+
+
+@mcp.resource(
+    "django://project",
+    name="Django Project Information",
+    mime_type="application/json",
+    annotations={"readOnlyHint": True, "idempotentHint": True},
+)
+def get_project() -> ProjectResource:
+    """Get comprehensive project information including Python environment and Django configuration.
+
+    Use this to understand the project's runtime environment, installed apps, and database
+    configuration.
+    """
+    return ProjectResource.from_env()
+
+
+@mcp.resource(
+    "django://apps",
+    name="Installed Django Apps",
+    mime_type="application/json",
+    annotations={"readOnlyHint": True, "idempotentHint": True},
+)
+def get_apps() -> list[AppResource]:
+    """Get a list of all installed Django applications with their models.
+
+    Use this to explore the project structure and available models without executing code.
+    """
+    return [AppResource.from_app(app) for app in apps.get_app_configs()]
+
+
+@mcp.resource(
+    "django://models",
+    name="Django Models",
+    mime_type="application/json",
+    annotations={"readOnlyHint": True, "idempotentHint": True},
+)
+def get_models() -> list[ModelResource]:
+    """Get detailed information about all Django models in the project.
+
+    Use this for quick model introspection without shell access.
+    """
+    return [ModelResource.from_model(model) for model in apps.get_models()]