idh

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

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

安装

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

推荐使用 pipx 独立安装：

pipx install ios-decrypt-hub

也可以直接通过 pip 安装：

python3 -m pip install ios-decrypt-hub

升级到最新版：

pipx upgrade ios-decrypt-hub

发现设备

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 广播时，可以手动指定地址：

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

命令行调用 MCP

一次性调用只读工具：

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

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

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

MCP 聚合网关

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

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

示例流程：

用户：帮我分析 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，调用体验最好：

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

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

本地 Simulator 联调：

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 转发。

开发

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。