esheria 0.2.0

Installable CLI and MCP tools for the Esheria Regulatory Pack API.

Esheria CLI And MCP

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

The package exposes two commands:

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:

pipx install esheria

If you do not use pipx, use normal pip:

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:

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:

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:

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:

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:

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

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:

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:

{
  "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.