Metadata-Version: 2.4
Name: ios-decrypt-hub
Version: 0.2.1
Summary: Discover IOSDecryptHub instances and bridge HTTP MCP to stdio
Author: IOSDecryptHub
Keywords: ios,mcp,udp,discovery
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"

# idh

`idh` 是 IOSDecryptHub 的 PC 端发现与 MCP 网关。它监听设备每 2 秒发送一次的 UDP
广播信标（端口 8089），并把设备上的 Streamable HTTP MCP 转换为本地 stdio MCP。

> HTTP/MCP 服务没有身份认证，只能在可信局域网中使用，不要暴露到公网。

## 安装

要求 Python 3.10 或更高版本，运行时只使用 Python 标准库。

推荐使用 pipx 独立安装：

```bash
pipx install ios-decrypt-hub
```

也可以直接通过 pip 安装：

```bash
python3 -m pip install ios-decrypt-hub
```

升级到最新版：

```bash
pipx upgrade ios-decrypt-hub
```

## 发现设备

```bash
idh devices
idh devices --json
idh watch
idh open com.example.app
```

`idh --devices` 是 `idh devices` 的兼容快捷写法。`devices --json` 返回的
`target_id` 是当前在线 App 进程的唯一标识，AI Agent 和自动化脚本应优先使用它；
Bundle ID、App 名称、序号和 MCP URL 仅作为便利选择器。

无法使用 UDP 广播时，可以手动指定地址：

```bash
idh devices --endpoint http://192.168.1.20:8088 --no-discovery
```

## 命令行调用 MCP

一次性调用只读工具：

```bash
idh call <target_id> get_stats
idh call <target_id> query_events \
  --arguments '{"category":"digest","limit":3}' --json
```

修改远端状态的工具必须显式确认：

```bash
idh call <target_id> set_pause \
  --arguments '{"paused":true}' --allow-mutation
```

## MCP 聚合网关

聚合网关适合动态发现和管理多个 App，只需在 MCP 客户端配置一次：

```json
{
  "mcpServers": {
    "idh": {
      "command": "idh",
      "args": ["mcp"]
    }
  }
}
```

网关提供固定工具集，避免设备上下线后 MCP 客户端缓存动态 `tools/list`：

- `idh_list_devices`
- `idh_list_tools`
- `idh_get_tool_schema`
- `idh_call_tool`
- `idh_get_panel_url`

### AI Agent 调用协议

`idh` 不解析自然语言，也不替 AI 决定“应该怎样分析”。自然语言理解、目标判断和分析规划
属于 AI Agent；`idh` 只提供在线事实、设备端真实工具描述、参数 schema 和确定性路由。

当用户说“帮我分析 xxxx App”时，Agent 应按以下协议工作：

1. 调用 `idh_list_devices` 获取当前在线 App，不使用历史 target 或缓存序号。
2. 由 Agent 将用户说的 `xxxx` 与返回的 `app`、`bundle` 字段对照。
3. 只有一个明确候选时，保存并使用该候选本轮返回的 `target_id`。
4. 多个候选都合理时，向用户展示 App、Bundle ID 和设备并要求选择；不得自行猜测。
5. 没有候选时，提示用户启动目标 App 并确认 IOSDecryptHub 已注入。
6. 调用 `idh_list_tools` 阅读设备端真实工具描述，不臆造不存在的分析能力。
7. 调用 `idh_get_tool_schema` 获取准备调用工具的完整 schema。
8. 调用 `idh_call_tool`，传入 `target`、`tool_name` 和 `tool_arguments`。
9. 查询、读取、反汇编等只读操作可根据用户目标自主执行；具有副作用的工具只有在用户
   明确要求后才传 `allow_mutation=true`。

示例流程：

```text
用户：帮我分析 Example App 最近的加密行为
Agent → idh_list_devices({})
Agent：根据 app/bundle 字段确定唯一候选，取得 target_id
Agent → idh_list_tools({"target":"<target_id>","query":"crypto"})
Agent → idh_get_tool_schema({"target":"<target_id>","tool_name":"query_events"})
Agent → idh_call_tool({
  "target":"<target_id>",
  "tool_name":"query_events",
  "tool_arguments":{"category":"all","limit":100}
})
```

上述工具链提供事实和执行能力，具体选择 `query_events` 还是其他工具应由 Agent 根据用户目标
和设备端返回的 description/schema 判断，而不是由 `idh` 内置关键词或自然语言规则决定。

希望 Agent 自主选择在线目标时，应配置聚合网关 `idh mcp`。透明代理的 target 在进程启动时
已经固定，更适合用户或上层系统预先确定目标的场景。

## 单 App 透明代理

固定分析一个 App 时，透明代理会把远端工具及完整 schema 原样暴露给 AI Agent，调用体验最好：

```json
{
  "mcpServers": {
    "idh-demo": {
      "command": "idh",
      "args": ["mcp", "--target", "com.example.app"]
    }
  }
}
```

多台设备运行相同 Bundle ID 时，应改用 `idh devices --json` 返回的 `target_id`，
或者显式指定唯一 MCP URL。透明代理启动时会等待目标出现，而不是在发现任意设备后立即失败。

本地 Simulator 联调：

```bash
idh mcp --target 1 --endpoint http://127.0.0.1:8088 --no-discovery
```

所有日志写入 stderr，stdout 严格保留给逐行 JSON-RPC stdio 消息。

## 发现生命周期

- 信标每 2 秒发送一次。
- 一次性发现默认等待 3 秒，覆盖完整信标周期和定时器调度容差。
- 6 秒未收到信标时，实例标记为 `stale`；路由前会用 `/api/stats` 复核，HTTP
  可达时仍视为在线。
- 10 秒未收到信标时，实例从注册表移除。
- 同一设备上的同一 Bundle ID 启动新进程时，新实例会立即替换旧实例。
- UDP 广播仅适用于同一二层局域网；跨 VLAN 时使用 `--endpoint` 或配置 UDP 转发。

## 开发

```bash
uv sync --extra dev
uv run python -m pytest tests/ -q
uv run ruff check src/ tests/
uv run python -m build
```

详细实施和验收步骤见
[MCP_GATEWAY_AGENT_OPTIMIZATION_PLAN.md](docs/MCP_GATEWAY_AGENT_OPTIMIZATION_PLAN.md)。
