Metadata-Version: 2.4
Name: esheria
Version: 0.2.0
Summary: Installable CLI and MCP tools for the Esheria Regulatory Pack API.
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic<3.0,>=2.8
Requires-Dist: PyYAML<7.0,>=6.0
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=8.2; extra == "dev"

# Esheria CLI And MCP

Installable command-line and MCP tools for the Esheria Regulatory Pack API.

The package exposes two commands:

```bash
esheria --help
esheria-mcp --help
```

## CLI Quickstart

1. Create an API token in the Esheria dashboard.
2. Install the command. `pipx` is recommended because it keeps command-line
   tools isolated from project dependencies:

```bash
pipx install esheria
```

If you do not use `pipx`, use normal `pip`:

```bash
python3 -m pip install esheria
```

3. Configure your shell. Put these in your terminal for a one-off test, or in
   `~/.zshrc`, `~/.bashrc`, or your shell profile to keep them:

```bash
export ESHERIA_API_BASE_URL="https://api.esheria.ai"
export ESHERIA_API_KEY="<client-api-key>"
```

`ESHERIA_API_TOKEN` is also accepted as an alias when `ESHERIA_API_KEY` is
unset.

Do not commit API keys. The CLI and MCP server read credentials from
environment variables or command-line flags and redact API key values from
diagnostic output.

4. Confirm the API is reachable:

```bash
esheria health --format json
esheria ready --format json
```

5. Discover packs, choose a `domain_pack_id`, then pass that pack ID to
   pack-specific commands:

```bash
esheria packs list --format json
esheria packs inspect KE-DATA-PROTECTION --format json
esheria packs versions KE-DATA-PROTECTION --format json
esheria packs diff KE-DATA-PROTECTION --format json
esheria packs change-events KE-DATA-PROTECTION --format json
esheria obligations list KE-DATA-PROTECTION --query breach --limit 3 --format json
esheria penalties list KE-DATA-PROTECTION --limit 5 --format json
esheria legal-review audit KE-DATA-PROTECTION --limit 5 --format json
```

`KE-DATA-PROTECTION` is only an example pack ID. The CLI and MCP server are
catalog-first: users should list packs and then call tools with the pack ID
they want. `ESHERIA_DEFAULT_PACK_ID` is optional legacy configuration and is not
required for normal CLI or MCP use.

## MCP Server

MCP hosts run the server for you. The JSON/TOML snippet tells the host which
command to start and which environment variables to pass into that process.

For local testing only, you can run the stdio server yourself:

```bash
esheria-mcp serve --stdio
```

The MCP server is read-only and exposes Regulatory Pack API tools for health,
readiness, pack discovery, obligations, applicability, claim verification,
version history, diffs, change events, filing calendars, evidence registers,
penalty facts, legal review audit metadata, relationship graph queries, exports,
and citation context lookup.

## Codex MCP

Edit `~/.codex/config.toml` and add:

```toml
[mcp_servers.esheria]
command = "uvx"
args = ["--from", "esheria", "esheria-mcp", "serve", "--stdio"]
env = { ESHERIA_API_BASE_URL = "https://api.esheria.ai", ESHERIA_API_KEY = "<client-api-key>" }
```

Restart Codex, then call `esheria_health`, `esheria_ready`, and
`esheria_list_packs`.

## Claude Code

Run this once from a terminal. It writes the MCP server entry into Claude
Code's MCP configuration:

```bash
claude mcp add --scope user --transport stdio \
  --env ESHERIA_API_BASE_URL=https://api.esheria.ai \
  --env ESHERIA_API_KEY=<client-api-key> \
  esheria -- uvx --from esheria esheria-mcp serve --stdio
```

Then run:

```bash
claude mcp list
```

Start or restart Claude Code and ask it to use the Esheria MCP tools.

## Claude Desktop

Open the Claude Desktop MCP config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add or merge this object:

```json
{
  "mcpServers": {
    "esheria": {
      "command": "uvx",
      "args": ["--from", "esheria", "esheria-mcp", "serve", "--stdio"],
      "env": {
        "ESHERIA_API_BASE_URL": "https://api.esheria.ai",
        "ESHERIA_API_KEY": "<client-api-key>"
      }
    }
  }
}
```

Restart Claude Desktop after saving the file.
