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
=======

.. code-block:: bash

   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:

.. code-block:: bash

   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
---------------------

.. list-table::
   :header-rows: 1

   * - 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):

.. code-block:: python

   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
--------------------------------------------

.. code-block:: python

   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
--------------------------------------------------

.. code-block:: python

   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 :mod:`djcrud_client.server` and :mod:`djcrud_client.tools`
for ``render_path``, ``split_arguments``, etc.

Public API
==========

.. automodule:: djcrud_client
   :members:
   :undoc-members:
   :show-inheritance:

Core modules:

.. automodule:: djcrud_client.server
   :members:

.. automodule:: djcrud_client.api
   :members:

.. automodule:: djcrud_client.profile
   :members:

.. automodule:: djcrud_client.schema
   :members:

.. automodule:: djcrud_client.config
   :members:

.. automodule:: djcrud_client.tools
   :members: