djcrud_client¶

djcrud-client is the standalone client package (pip install djcrud-client) for talking to djcrud DRF JSON APIs over HTTP. It powers remote stdio MCP agents and can be used directly as a library (no Django, no FastMCP required).

It is automatically included when you do pip install --pre "djcrud[mcp]" on the host, but agents / external tools only need the lightweight client wheel.

Install¶

pip install djcrud-client
# during development / prereleases:
pip install --pre djcrud-client

CLI Usage¶

The entry point djcrud-client can run as a stdio MCP server or invoke a single tool.

Basic:

export DJCRUD_BASE_URL=http://localhost:8000
export DJCRUD_TOKEN=...
djcrud-client -mcp                 # stdio MCP server for agents
djcrud-client --call article_list --json '{}'
djcrud-client --call article_publish --json '{"pk": 1}'

Full options (see djcrud-client --help):

-mcp: run FastMCP stdio server
--call TOOL + --json '...': one-shot call, print JSON result
--registry KEY: select profile (default resolved from host)
--user / --password: fallback to login exchange

Environment variables¶

Variable	Purpose	Fallbacks
`DJCRUD_BASE_URL`	Target API root	`DJMVC_BASE_URL`, `TILDETTE_BASE_URL`
`DJCRUD_TOKEN`	Bearer token	`DJMVC_TOKEN`, `TILDETTE_TOKEN`
`DJCRUD_USERNAME` / `DJCRUD_PASSWORD`	Login credentials (only if no token)	(same with legacy prefixes)

Library Usage (build your own client)¶

Import surface (no Django dependency):

from djcrud_client import (
    CrudApi, McpProfile,
    create_mcp_server,
    build_tools_for_profile, build_tools_from_schema,
    get_base_url, get_token, login,
)

High-level: create a ready-to-run MCP server¶

from djcrud_client.server import create_mcp_server

mcp = create_mcp_server(
    base_url="http://localhost:8000",
    token=os.environ["DJCRUD_TOKEN"],
    # registry=... or profile=...
)
mcp.run(transport="stdio")

Low-level: build tools yourself + direct API calls¶

from djcrud_client import McpProfile
from djcrud_client.api import CrudApi
from djcrud_client.schema import build_tools_from_schema

profile = McpProfile.from_dict(...)  # or load_profile(...)
schema = ...  # from /api/schema/ or fetch_schema
tools = build_tools_from_schema(schema, prefixes={"article": "/api/article/"})

api = CrudApi(base_url=..., token=...)
resp = api.request("GET", "/api/article/")
print(resp.json())

# or use login()
token = login(base_url=base, username=..., password=...)

See also the source of djcrud_client.server and djcrud_client.tools for render_path, split_arguments, etc.

Public API¶

Stdio MCP bridge for djcrud JSON APIs (no Django required).

class djcrud_client.CrudApi(*, base_url, token, timeout=30.0, extra_headers=None)[source]¶

Bases: object

Parameters:

base_url (str)
token (str)
timeout (float)
extra_headers (dict[str, str] | Callable[[], dict[str, str]] | None)

request(method, path, *, params=None, json_body=None, timeout=None)[source]¶

Parameters:

method (str)
path (str)
params (dict[str, Any] | None)
json_body (dict[str, Any] | None)
timeout (float | None)

Return type:

Response

fetch_schema()[source]¶

Return type:: dict[str, Any]

fetch_json(path)[source]¶

Parameters:: path (str)
Return type:: Any

class djcrud_client.McpProfile[source]¶

Bases: object

Wire-format MCP profile fetched from GET /api/mcp/profiles/{key}/.

key: str¶

server_name: str¶

instructions: str¶

info_tool_name: str¶

api_prefixes: tuple[str, ...]¶

meta: dict[str, Any]¶

classmethod from_dict(payload)[source]¶

Parameters:: payload (dict[str, Any])
Return type:: McpProfile

to_dict()[source]¶

Return type:: dict[str, Any]

djcrud_client.all_tools_for_profile(schema, profile)[source]¶

Parameters:

schema (dict[str, Any])
profile (McpProfile)

Return type:

list[dict[str, Any]]

djcrud_client.build_tools_for_profile(schema, profile)[source]¶

Parameters:

schema (dict[str, Any])
profile (McpProfile)

Return type:

list[dict[str, Any]]

djcrud_client.build_tools_from_schema(schema, *, prefixes)[source]¶

Parameters:

schema (dict[str, Any])
prefixes (dict[str, str])

Return type:

list[dict[str, Any]]

djcrud_client.create_mcp_server(*, base_url=None, token=None, profile=None, registry=None, extra_headers=None)[source]¶

Parameters:

base_url (str | None)
token (str | None)
profile (McpProfile | str | None)
registry (str | None)
extra_headers (dict[str, str] | None)

Return type:

FastMCP

djcrud_client.fetch_schema(*, base_url)[source]¶

Parameters:: base_url (str)
Return type:: dict[str, Any]

djcrud_client.get_base_url()[source]¶

Return type:: str

djcrud_client.get_registry_key(*, base_url=None)[source]¶

Host default profile key from GET /api/mcp/profiles/ (not an env var).

Parameters:: base_url (str | None)
Return type:: str

djcrud_client.get_token()[source]¶

Return type:: str

djcrud_client.login(*, base_url, username, password, timeout=30.0)[source]¶

Parameters:

base_url (str)
username (str)
password (str)
timeout (float)

Return type:

str

djcrud_client.profile_meta(profile)[source]¶

Parameters:: profile (McpProfile)
Return type:: dict[str, Any]

djcrud_client.run_stdio(*, registry=None)[source]¶

Parameters:: registry (str | None)
Return type:: None

Core modules:

class djcrud_client.profile.McpProfile[source]¶

Bases: object

Wire-format MCP profile fetched from GET /api/mcp/profiles/{key}/.

djcrud_client.schema.prefix_map_from_profile(profile)[source]¶

Build {model_name: api_prefix} from host-published api_prefixes.

Parameters:: profile (McpProfile)
Return type:: dict[str, str]

djcrud_client.config.get_registry_key(*, base_url=None)[source]¶

Host default profile key from GET /api/mcp/profiles/ (not an env var).

Parameters:: base_url (str | None)
Return type:: str