Metadata-Version: 2.3
Name: dhis2w-mcp-bridge
Version: 0.16.0
Summary: Single-tool MCP bridge that exposes the dhis2 CLI for small local models.
Author: Morten Hansen
Author-email: Morten Hansen <morten@winterop.com>
Requires-Dist: dhis2w-cli>=0.16.0,<0.17
Requires-Dist: fastmcp>=3.4
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# dhis2w-mcp-bridge

A FastMCP server that exposes the entire `dhis2` CLI as **one** MCP tool, `dhis2_cli`.

Where `dhis2w-mcp` registers ~337 typed tools (≈50-65k tokens of schema loaded into the
model's context up front), this server registers a single tool that shells out to the local
`dhis2` binary. A small, context-limited **local model** discovers the command surface
progressively with `--help` and runs commands with `--json` — and nothing leaves the host.

## Why this exists

For sensitive data that must stay on-box, you run a local model (LM Studio, Ollama,
llama.cpp). Such models can't spare ~53k tokens for tool schemas, and many degrade when
choosing among hundreds of tools. One tool + on-demand `--help` fits an 8k-context model and
keeps the full DHIS2 surface reachable. Same code as the CLI — the bridge just runs it.

Use `dhis2w-mcp` (the full typed server) for hosts that do progressive tool disclosure
themselves (e.g. Claude Code handles all 337 tools fine). Use this bridge for small local
models.

## The tool

```
dhis2_cli(args: list[str], profile: str | None = None) -> CliResult
CliResult = { exit_code: int, stdout: str, stderr: str }
```

The model is expected to discover, then act:

```
dhis2_cli(["--help"])                                  # list command groups
dhis2_cli(["metadata", "--help"])                      # drill into a group
dhis2_cli(["metadata", "list", "dataElements",
           "--filter", "name:ilike:malaria"])          # run a command
```

Contract: `--json` is injected automatically, so on success (`exit_code == 0`) `stdout` is
JSON. `--help`/`--version` exit 0 with human text. Any non-zero exit is a failure and the
message is on `stderr` (never JSON). `profile` is injected as `-p <profile>`.

## Install & run

The bridge depends on `dhis2w-cli`, so installing it provides the `dhis2` binary.

```bash
# From a workspace checkout (development)
uv run dhis2w-mcp-bridge

# From PyPI
uv tool install dhis2w-mcp-bridge
dhis2w-mcp-bridge
```

## Configure a client (LM Studio shown; any MCP host works)

`~/.lmstudio/mcp.json`:

```json
{
  "mcpServers": {
    "dhis2": {
      "command": "uv",
      "args": ["run", "--directory", "/ABS/PATH/TO/dhis2w-utils", "dhis2w-mcp-bridge"],
      "env": {
        "DHIS2_PROFILE": "local_basic",
        "DHIS2_MCP_READONLY": "1"
      }
    }
  }
}
```

The server speaks MCP over stdio and reads its DHIS2 connection from a profile
(`.dhis2/profiles.toml` / `~/.config/dhis2/profiles.toml`) or env vars (`DHIS2_URL` +
`DHIS2_PAT` / `DHIS2_USERNAME`+`DHIS2_PASSWORD`), exactly like the CLI.

## Environment variables

| Variable | Default | Effect |
| --- | --- | --- |
| `DHIS2_MCP_READONLY` | unset | When truthy (`1`/`true`/`yes`/`on`), only read commands and `--help` are allowed; writes are refused (exit 126). |
| `DHIS2_CLI_BIN` | auto | Path to the `dhis2` executable. Auto-discovered next to the running interpreter, then on `PATH`. |
| `DHIS2_MCP_CLI_TIMEOUT` | `120` | Per-command timeout in seconds (exit 124 on timeout). |
| `DHIS2_PROFILE` | profile default | Selects the DHIS2 profile, passed through to the CLI. |

Exit-code conventions added by the bridge: `124` timeout, `126` refused by read-only mode,
`127` CLI not found. Otherwise the result carries the CLI's own exit code (`0` success / JSON,
`1` domain error, `2` usage error).

## Read-only mode

`DHIS2_MCP_READONLY=1` is the safe default for handing a local model a query-only surface. It
is **fail-closed**: only commands on an allowlist of read-only command paths (and `--help`)
are permitted; everything else is refused before any subprocess runs. The allowlist is
generated by introspecting the Typer command tree and verified against the live tree by the
test suite, so it cannot silently drift, and ambiguous verbs default to denied.

This is convenience, not the security boundary — the authoritative control is the DHIS2
authorities of the profile's credentials. For a hard guarantee, point the profile at a
read-scoped PAT or user.

## How it works

`build_server()` creates a `FastMCP` instance and registers the single `dhis2_cli` tool
(`cli_bridge.register`). The tool runs `dhis2 --json [-p <profile>] <args>` via
`asyncio.create_subprocess_exec` (exec form — no shell, no injection), bounded by a timeout,
and returns a typed `CliResult`. There is no version resolution or plugin discovery: the CLI
subprocess auto-detects the DHIS2 version itself on connect.
