Esheria Regulatory Intelligence

Esheria CLI 和 MCP

适用于 Esheria Regulatory Pack API 的可安装命令行工具和 MCP 工具。

面向明确发布的法规包，提供全球范围内、有引用支持的法规情报。 了解当前就绪情况，选择预期的司法管辖区和法规包，并在 CLI、Python 和 MCP 工作流中保留引用、版本、限制和跟踪 ID。Esheria 提供法规情报，不提供法律建议。

该软件包提供两个命令：

esheria --help
esheria-mcp --help
esheria mcp serve --help

版本 1.2.2 是正式发布的稳定公开版本。esheria Python 软件包中分发的 CLI、Python 客户端和 MCP 软件根据 Apache License 2.0 授权。托管 API/MCP 访问、法规数据、 服务输出和 Esheria 商标不受 Apache-2.0 授权；它们仍受 Esheria 服务条款、 隐私政策以及任何适用的客户协议约束。确切的授权范围请参阅 LICENSE 和 NOTICE。

CLI 快速入门

1. 在 Esheria 控制面板中创建数据 API 令牌。
2. 安装该命令。建议使用 pipx，因为它会将命令行 工具与项目依赖项隔离：

pipx install esheria

如果不使用 pipx，请使用常规的 pip：

python3 -m pip install esheria

3. 配置 Shell。将以下内容输入终端进行一次性测试，或者将其添加到 ~/.zshrc、~/.bashrc 或 Shell 配置文件中以便长期使用：

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

PowerShell：

$env:ESHERIA_API_BASE_URL = "https://api.esheria.ai"
$env:ESHERIA_API_KEY = "<client-api-key>"

如果未设置 ESHERIA_API_KEY，也可以使用 ESHERIA_API_TOKEN 作为别名。

请勿提交 API 密钥。CLI 和 MCP 服务会从环境变量或命令行标志中读取凭据，并在 诊断输出中隐藏 API 密钥值。建议使用环境变量：--api-key 可能会通过 Shell 历史记录或操作系统进程列表泄露。

4. 确认 API 可访问：

esheria --version
esheria health --format json
esheria ready --format json

5. 发现法规包，选择一个 domain_pack_id，然后将该法规包 ID 传递给 特定法规包的命令：

esheria packs list --format json
export ESHERIA_PACK_ID="UK-DATA-PROTECTION-PRIVACY"
esheria packs inspect "$ESHERIA_PACK_ID" --format json
esheria packs versions "$ESHERIA_PACK_ID" --format json
esheria packs diff "$ESHERIA_PACK_ID" --format json
esheria packs change-events "$ESHERIA_PACK_ID" --format json
esheria obligations list "$ESHERIA_PACK_ID" --limit 3 --format json
esheria penalties list "$ESHERIA_PACK_ID" --limit 5 --format json
esheria legal-review audit "$ESHERIA_PACK_ID" --limit 5 --format json

输出标志可以放在全局位置，也可以放在叶子命令上：

esheria --format json packs list
esheria packs list --format json

使用 esheria --help 和 <group> --help 查看完整的命令树。 除了上述读取工作流外，CLI 还包含源监控操作、图谱覆盖率/重建操作、 工作区范围内的客户生命周期命令，以及工作区/令牌/计费管理命令。

工作区、令牌和计费命令需要管理令牌。通过控制面板创建的常规令牌和 OAuth 连接器令牌仅具有 regulatory:read 权限。 会更改状态的法规工作流需要明确创建的操作员数据令牌，并且该令牌必须具有一个或多个 monitoring:write、graph:write 或 customer:write 权限；仅有 regulatory:read 会被拒绝。例如：

esheria tokens create \
  --name "Monitoring operator" \
  --scope regulatory:read \
  --scope monitoring:write \
  --pack UK-DATA-USE-AND-ACCESS

建议继续在控制面板中自助管理工作区、令牌、计费和订阅。操作员令牌应设置较短的有效期，并且只授予所需的权限范围和法规包授权。

CLI 和 MCP 服务以法规包目录为起点：用户先列出法规包，再使用明确指定的法规包 ID 调用工具。ESHERIA_DEFAULT_PACK_ID 是可选的客户端偏好设置，不是服务端司法管辖区默认值。

CLI 会报告 API 的就绪状态标签、限制、引用和跟踪 ID；请在下游工作流中保留这些信息。已发布的法规包可能仅包含完整法律语料库中经过审查的部分内容，并非所有法规包都支持通过评估器门控的声明验证。Esheria 的输出是法规情报，不是法律建议，也不能替代合格法律顾问的意见。

托管 MCP

生产环境中的 MCP 使用托管的 Esheria 端点：

https://mcp.esheria.ai/mcp

常规客户入驻时请使用此端点。这样用户的机器上就无需安装本地 Python、uvx，也无需配置虚拟环境或发现软件包。

Claude Directory 宿主使用 OAuth。其他 Agent 宿主则发送在控制面板中创建的 Esheria 数据令牌，作为 bearer token 或 X-API-Key。托管 MCP 服务会在初始化前检查凭据，并使用该凭据调用 Regulatory Pack API，因此计费、数据包权限、跟踪 ID 和仅公开已发布内容的行为都由中心统一管理。无效凭据和仅用于管理的凭据无法枚举工具。

Codex MCP

将令牌设置在 Codex 可以读取的位置：

export ESHERIA_API_KEY="<client-api-key>"

编辑 ~/.codex/config.toml 并添加：

[mcp_servers.esheria]
url = "https://mcp.esheria.ai/mcp"
bearer_token_env_var = "ESHERIA_API_KEY"

重启 Codex，然后调用 esheria_health、esheria_ready 和 esheria_list_packs。

本地 MCP 回退方案

用于本地开发，或不支持远程 MCP URL 的 Agent 宿主时，可以自行运行 stdio 服务端：

esheria-mcp serve --stdio

仅供操作员使用的 HTTP 传输命令：

ESHERIA_API_BASE_URL="https://api.esheria.ai" \
  esheria-mcp serve --http --host 127.0.0.1 --port 8081 --path /mcp

生产环境已部署在 https://mcp.esheria.ai/mcp；终端用户不应运行此命令。

托管 OAuth 配置提供只读的 20 个工具目录，涵盖健康检查、就绪状态、数据包发现、义务、适用性、声明验证、版本、差异、变更事件、申报日历、证据、处罚、审计元数据、关系查询、导出和引用上下文。常规 API 数据令牌可使用 29 个安全的只读或类只读工具。操作员数据令牌还可使用由 monitoring:write、graph:write 和/或 customer:write 授权的变更工具，最多可使用完整的 37 个工具目录。每项变更操作都必须提供 confirm=true；OAuth Directory 会话仍为只读。

托管服务使用官方 MCP SDK 和当前的 Streamable HTTP。成功的工具调用会在文本内容和 structuredContent 中返回有大小限制的 JSON，并附带 trace_id 和 mcp 截断元数据。需要完整的大型导出时，请使用 API 或 CLI。

仅在宿主不支持远程 MCP URL 时使用 stdio：

[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>" }

Claude Code

如果已安装的版本支持远程 MCP 设置，请使用 Claude Code 的远程 MCP 配置：

• URL：https://mcp.esheria.ai/mcp
• Authorization：Bearer <client-api-key>

如果你的 Claude Code 版本仅支持本地 stdio MCP 服务端，请在终端中运行一次此回退命令：

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

然后运行：

claude mcp list

启动或重启 Claude Code，并让它使用 Esheria MCP 工具。

Claude Desktop

如果已安装的版本支持远程 MCP 设置，请使用 Claude Desktop 的远程 MCP 配置：

• URL：https://mcp.esheria.ai/mcp
• Authorization：Bearer <client-api-key>

如果你的 Claude Desktop 版本仅支持本地 stdio MCP 服务端，请使用以下回退方案。

打开 Claude Desktop MCP 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.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>"
      }
    }
  }
}

保存文件后重启 Claude Desktop。