Metadata-Version: 2.4
Name: xfqtrace
Version: 0.2.0
Summary: 真机 Android NDK 指令级 trace 工具 — CLI + MCP Server
Author-email: xfq <i@xfq.fun>
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-username/xfqtrace
Project-URL: Repository, https://github.com/your-username/xfqtrace
Project-URL: Documentation, https://github.com/your-username/xfqtrace#readme
Keywords: android,reverse-engineering,trace,frida,qbdi,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12
Requires-Dist: mcp>=1.0

# xfQTrace — 真机 Android NDK 指令级 trace

基于 [xfQTrace](https://github.com/xfq/frida-qbdi-trace)（QBDI + Frida）的真机 trace 工具封装，提供统一的 **CLI** + **MCP Server**。

## 快速开始

```bash
pip install xfqtrace

# 检查环境
xfqtrace doctor

# 查看资产
xfqtrace info

# 生成 hook 配置
xfqtrace gen-config -p com.example.app --so libnative.so --offset 0x1234

# dry-run 查看计划
xfqtrace run -p com.example.app

# 执行 trace
xfqtrace run -p com.example.app --execute

# 启动 MCP Server
xfqtrace mcp
```

## 架构

```
┌─────────────────────────────────────────────┐
│  xfqtrace CLI                                │
│  xfqtrace doctor | info | gen-config | run   │
│  xfqtrace pull-only | list-logs | preview    │
│  xfqtrace logcat | mcp                       │
├─────────────────────────────────────────────┤
│  xfqtrace.core     核心业务逻辑              │
│  xfqtrace.device   adb + frida 设备管理      │
│  xfqtrace.mcp_server  MCP Server (双格式)     │
├─────────────────────────────────────────────┤
│  xfqtrace/_vendor/  内置资产                 │
│    ├── libxfqtrace.so     (QBDI 引擎)        │
│    ├── 半自动化trace.js   (Frida 模板)       │
│    ├── scripts/           (bypass 脚本)      │
│    └── <package>/         (案例配置)          │
└─────────────────────────────────────────────┘
```

**设计原则：** 不依赖 `import frida`，全程 subprocess 调系统 `frida` CLI，无版本匹配问题。

## 命令

| 命令 | 说明 |
|---|---|
| `doctor` | 检查 adb/frida/frida-server/资产 |
| `info` | 查看工具资产和案例列表 |
| `gen-config` | 生成 Frida hook 脚本 |
| `run` | 执行 trace（默认 dry-run） |
| `pull-only` | 仅拉取设备 trace 日志 |
| `list-logs` | 列出本地日志 |
| `preview-log` | 预览日志内容 |
| `logcat` | 输出 logcat 监控命令 |
| `mcp` | 启动 MCP Server |

## MCP Server

支持两种传输格式自动探测：

- **Content-Length** — 兼容 Claude Desktop、Cursor 等标准 MCP 客户端
- **JSON Lines** — Python MCP SDK 原生格式

配置 Claude Desktop：

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

## 致谢

- [xfQTrace](https://github.com/xfq/frida-qbdi-trace) — 基于 QBDI 的 Android native trace 引擎
- [Frida](https://frida.re) — 动态插桩框架
