Local Docker MCP¶

Bharat Judgements exposes 30 tools over stdio. Run them locally through Docker, Claude Code/Desktop, Codex or Grok Build. No hosted service, API key or court account is required. Live searches use OCR; CAPTCHA exhaustion returns an error.

Build and verify before publication¶

docker build -t hhftechnology/bharat-judgements:0.6.0 .
python scripts/mcp_smoke.py --image hhftechnology/bharat-judgements:0.6.0

After publication users can pull that version instead of building it. The image runs as UID/GID 10001 and needs writable cache and optional PDF output mounts. Keep Docker running. MCP requires -i and must not use -t.

For Python-only development:

pip install -e '.[mcp,dev]'
bharat-judgements mcp

Connect an assistant¶

Use this configuration for clients supporting local MCP commands:

{
  "mcpServers": {
    "bharat-judgements": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--init",
        "--cap-drop=ALL", "--security-opt=no-new-privileges",
        "--mount", "type=volume,src=bharat-judgements-cache,dst=/home/app/.cache",
        "docker.io/hhftechnology/bharat-judgements:0.6.0"
      ]
    }
  }
}

Generated packages live in plugins/claude, plugins/codex, and plugins/grok. They include the same canonical skill and Docker command. For local development, use Claude's --plugin-dir ./plugins/claude, register the repository marketplace with codex plugin marketplace add ., or install ./plugins/grok in Grok Build. Use each client's plugin validation and installation commands before release.

For Docker MCP Toolkit, use the release catalog generated by scripts/prepare_submissions.py as described in the release guide. The official Docker catalog entry becomes available only after review and acceptance.

Docker Compose setup¶

The repository includes compose.yaml. From the repository directory, with Docker Desktop running:

docker compose config --quiet
docker compose build mcp
docker compose run --rm --no-deps -T mcp

To verify discovery and structured errors after building:

python scripts/mcp_smoke.py --compose compose.yaml

Add --live to also retrieve a recent Supreme Court PDF and read its MCP resource. This verification command needs the Python mcp extra installed locally; assistant connections use the dependencies bundled in the container.

The last command in the first block opens the stdio MCP process and waits for a client. Normally your assistant launches that command itself. Build the image once before connecting; the Compose service uses the locally built version. After the image is published, docker compose pull --policy always mcp can download it instead.

Use this client configuration, replacing the example with the absolute path to your checkout's Compose file:

{
  "mcpServers": {
    "bharat-judgements": {
      "command": "docker",
      "args": [
        "compose", "--file", "/absolute/path/to/bharat-judgements/compose.yaml",
        "run", "--rm", "--no-deps", "-T", "mcp"
      ]
    }
  }
}

On Windows a path such as C:/Users/YOU/projects/bharat-judgements/compose.yaml works in JSON; forward slashes avoid backslash escaping. The absolute Compose path also resolves its build context and mounts from the correct directory. The generated plugins use their existing direct docker run setup; replace that MCP command with the configuration above when you prefer Compose.

Compose keeps cache files in its cache volume and exports in its output volume across client/container restarts. The app runs as UID/GID 10001, drops Linux capabilities, and uses one CPU and a 2 GiB memory limit. Normal MCP PDF resources can be read by the assistant without exporting a host file. A named output volume is persistent Docker storage, not a folder in your checkout.

For PDFs saved directly to your computer, create compose.host-output.yaml beside compose.yaml with:

services:
  mcp:
    volumes:
      - ./output:/output

Create the output directory. On Linux it must be writable by UID 10001; for a new export directory you can set its ownership explicitly:

mkdir -p output
sudo chown 10001:10001 output

On Windows, create it with New-Item -ItemType Directory -Force output. Use both Compose files in the assistant's command, with absolute paths:

docker compose --file /absolute/path/compose.yaml --file /absolute/path/compose.host-output.yaml run --rm --no-deps -T mcp

Ask the assistant to pass a relative filename, for example matter/order-2024-05-10.pdf, to download_pdf. The PDF is then saved below output/. Existing files are not overwritten. The override replaces the default named output mount; previously exported files stay in the original volume.

The Compose file reads request-delay, timeout, retry and CAPTCHA settings from their BHARAT_JUDGEMENTS_ environment variables (or Compose's .env file). For the documented Calcutta-only certificate exception, set BHARAT_JUDGEMENTS_CALCUTTA_VERIFY_SSL=false explicitly before connecting. Verification for other portals stays enabled.

Try the copy-ready research prompts, starting with court discovery and then a case identifier or a small judgment search.

Tools and PDF retrieval¶

Tool schemas use SDK parameter names. Supply court codes from courts and obtain district/establishment codes from discovery tools. Default result limit is 50; the MCP maximum is 100. Portal page sizes can impose a smaller page limit.

Search results with downloadable documents include an opaque download_id. Call download_pdf(download_id=...); read the resulting bharat-judgements://pdf/... resource as application/pdf. Identifiers and resources expire after ten minutes. At most 32 sessions and 100 downloaded resources are retained; repeat a search if its session was evicted. PDFs larger than 32 MiB are rejected for MCP resource delivery. SCI archive downloads can first require a large annual tar bundle; the SDK remains available for bulk work.

find_judgments returns unified models; live results from this facade require judgments_search to obtain session-bound PDF IDs. No portal-specific session state is embedded in unified models.

To export a PDF, mount a host folder at /output and pass a relative .pdf filename to download_pdf. Existing exports are not overwritten. Export paths must remain within BHARAT_JUDGEMENTS_MCP_OUTPUT_DIR.

Reliability and privacy¶

TLS is verified by default. An explicit BHARAT_JUDGEMENTS_VERIFY_SSL=false exception disables verification; configure it only for a known portal certificate problem. Transport attempts, CAPTCHA retries and session refreshes are bounded.

Archive text queries match titles/parties, not full document bodies. Citation filters require court="sci"; forced live search accepts text only. Unsupported combinations fail visibly. Historical archives may lag current decisions.

Queries reach the selected official court portal or public S3 archive. There is no application telemetry. Court response text and PDFs are untrusted content; assistants must not treat their contents as instructions.

An explicit Calcutta-only certificate exception can be configured by forwarding BHARAT_JUDGEMENTS_CALCUTTA_VERIFY_SSL=false to the container with docker run -e. Other portals retain verified TLS. Use this only after assessing the portal certificate issue.