给 GameGuardian MCP Server（ggmcp）套一个手机上的可视化界面 —— 不用命令行、不用 curl，直接在 Android 应用里选进程、搜内存、改数值、冻结、看模块基址与 Hex。
-3DDC84.svg){kind=icon}
-lightgrey.svg){kind=icon}
GGMCP-Control（应用名：GG 控制台）是开源项目 gameguardian-mcp-server 的 Android 图形客户端。
服务端把 GameGuardian（GG 修改器）的核心能力做成了 MCP（Model Context Protocol）服务：进程枚举、内存搜索、读写修改、冻结数值、指针扫描……本应用把这些能力变成手机上点得动的按钮：
- 一键部署：APK 内置交叉编译好的
ggmcp服务端（arm64-v8a/x86_64），装完即可在手机上以 root 写入/data/local/tmp/ggmcp/ggmcp并启动，不需要 adb、不需要电脑。 - 六个标签页：连接 / 进程 / 搜索 / 结果 / 工具 / 日志，覆盖从选进程到改数值的完整流程。
- 纯 Android 框架实现：没有 AndroidX、没有 Kotlin、没有第三方依赖，单 Activity + 原生控件，APK 体积小、启动快。
- 数据不出设备：所有操作通过 HTTP(JSON-RPC) 发给设备本机的
ggmcp（默认http://127.0.0.1:8788/mcp），不联网、不上传。 - RAW 调用兜底：服务端的每一个工具都能在「工具」页用原始 JSON 调用，服务端升级后无需等待 App 更新。
⚠️ 需要 Root（Magisk / KernelSU / 模拟器自带 su）。没有 root 权限无法部署服务端，也无法读写其它进程的内存。
flowchart LR
subgraph Phone["Android 设备（本机回环）"]
A["GG 控制台<br/>com.ggmcp.control"] -- "HTTP JSON-RPC<br/>127.0.0.1:8788/mcp" --> B["ggmcp 服务端<br/>Go 静态二进制 · root"]
B -- "① 内核驱动（可选）<br/>socket + ioctl 0x7e1a/0x7e1b" --> C["目标进程<br/>（游戏 / 应用）"]
B -- "② 自动降级<br/>process_vm_readv" --> C
B -- "③ 再降级<br/>/proc/<pid>/mem" --> C
end
- 应用只做三件事：组装 JSON-RPC 请求、执行 root shell（部署 / 启停服务）、渲染结果。
- 真正的内存读写、搜索算法、结果集管理全部在
ggmcp服务端完成，读写通道按内核驱动 → process_vm_readv → /proc/<pid>/mem三重复用降级，任意一层不可用都会自动切换。
| 标签页 | 能做什么 |
|---|---|
| 连接 | 改服务地址、连接测试、启动/停止服务、查看服务日志、部署内置二进制并启动、导入自定义二进制、环境自检、写入控制/开机自启脚本、测试 root、GG 修改器绑定/换绑/解绑、读 GG 保存列表、列 GG 数据文件 |
| 进程 | 进程列表（关键字过滤 / 仅应用 / 含内核线程 / 4 种排序 / 分页）、点选附加、分离、目标信息（内存映射概况）、模块列表、暂停/恢复进程 |
| 搜索 | 精确搜索（byte/word/dword/qword/float/double/auto 全类型）、两步搜索 refine、模糊搜索（初始化 → 增大/减小/不变/有变化/范围过滤）、区间搜索、Xor 加密值搜索 |
| 结果 | 结果分页浏览与点选、按地址读/写、单条修改/冻结、批量改成同一值、批量冻结结果集（含范围过滤与坐标对模式）、解冻全部、Hex 转储、监视地址 3 秒、快照保存/列出、结果分析、导出结果、复制地址 |
| 工具 | 读/写/Hex 转储/读原始字节、模块基址、计算偏移、模块列表、指针扫描、暂停/恢复、快照与交叉分析、GG 数据文件与保存列表读取、生成 GG Lua 脚本并回读输出、服务器配置读写、关闭服务器、执行 shell、RAW 调用（可调用全部工具）、列出全部工具 |
| 日志 | 每一次调用的请求参数与响应结果（带时间戳）审计、清空、复制、手动刷新、自动滚动 |
搜索出结果后会自动跳到「结果」页；顶部标题栏实时显示 已连接 · 已附加 pid=… / 结果数 / 冻结数。
| 项目 | 要求 |
|---|---|
| 系统 | Android 8.0 及以上（minSdk 26，targetSdk 34） |
| 权限 | 必须已 Root：Magisk / KernelSU / KitsuneMagisk，或模拟器自带 su |
| 存储 | 约 30 MB（APK 约 7 MB + 设备上解出的服务端二进制约 7 MB） |
| 网络 | 无需联网；仅本机回环 127.0.0.1:8788 |
| 可选 | KPatch-Next + MemoryDriver_IOCTLhook.kpm，装内核模块后内存读写走内核通道；不装则自动降级，功能照常可用 |
- 打开 Releases 下载最新 APK。
- 安装到手机（Android 会提示「未知来源应用」，允许即可）。
- 打开应用 → 进入下一步的「快速上手」。
Release APK 使用 debug 密钥签名，可直接覆盖安装升级；如你有正式签名需求，请按 docs/BUILDING.md 自行配置签名后构建。
需要 JDK 17+ 与 Android SDK。完整步骤（含服务端二进制重编译、签名配置、跨平台命令）见 docs/BUILDING.md，最短路径：
git clone https://github.com/qpalzm2332933171-droid/GGMCP-Control.git
cd GGMCP-Control
./gradlew :app:assembleDebug # Windows: .\gradlew.bat :app:assembleDebug产物：app/build/outputs/apk/debug/app-debug.apk
- 安装并打开应用，首次进入停在「连接」页，会自动做一次连接测试（此时服务还没跑，失败是正常的）。
- 授权 root：点「测试 root」，在 Magisk/KernelSU 弹窗里选择「允许」（建议勾选永久记住），输出里应出现
uid=0。 - 部署服务端：点「部署内置二进制并启动」。应用会按设备 ABI 选择内置的
ggmcp，以 root 写入/data/local/tmp/ggmcp/ggmcp，生成控制脚本并启动服务，最后验证 HTTP 通道。看到[ok] 服务在线即部署成功。 - 可选：开机自启。想每次开机自动拉起服务，点「写入控制/自启脚本」，会写入
/data/adb/service.d/ggmcp.sh（Magisk/KernelSU 重启后自动执行）。 - 选进程：切到「进程」页 → 过滤框输入游戏关键字（如
com.xxx.yyy或进程名）→ 点列表项选中 → 点「附加选中进程」。 - 搜数值：切到「搜索」页 → 填数值（如
100）→ 类型dword、区域all→ 点「搜索」，有结果会自动跳到「结果」页。 - 改数值：在「结果」页点一条结果 → 填入新值 → 「修改选中项」；数值会被游戏改回去时，用「冻结选中项」按住它，用完「解冻全部」。
- 数值变化了怎么办：用两步搜索 —— 先搜旧值 → 回游戏让数值变化 → 回到「搜索」页填新值点「细化 refine」，命中会从几千条缩到个位数。
进程 页附加目标 → 搜索 页填数值 + dword + 区域 all → 搜索 → 结果 页选中 → 修改 / 冻结。
- 搜当前值（例如金币
1280）。 - 回游戏里让金币变化（买东西、打怪）。
- 回到
搜索页填入新值，点 细化 refine —— 只在上一次的结果里过滤，秒级完成。 - 重复 2–3 步，直到只剩 1–3 条结果，再修改/冻结。
适用于血量条、经验条这类只看得见「变多变少」的数值：
搜索页 → 「① 初始化快照」记录当前全部值（建议先选区域，如heap）。- 回游戏让数值增大 → 点「② 增大」；变小 → 点「② 减小」；没变 → 点「② 不变」。
- 反复第 2 步，候选数量会快速收敛；坐标类数值可用
minValue/maxValue做「② 范围过滤」（例如坐标一定在 0–4096 之间）。
搜索页底部「Xor 加密搜索」填入明文数值（游戏里显示的值），点搜索。- 服务端会统计密钥分布，众数密钥就是最可能的加密密钥，并把对应地址设为候选。
- 回游戏让数值变化 → 再次点 Xor 搜索并勾选 refine → 保留密钥不变的地址就是真身。
结果 页 → 「批量冻结结果集」→ 填统一值，可加 minValue/maxValue 过滤垃圾值，勾选「仅成对(X/Z)」只冻结相邻 8 字节成对的坐标对，避免误冻结。
工具 页 → 「模块基址」拿到 libil2cpp.so 等模块基址 → 把结果地址填入「计算偏移」得到相对模块偏移 → 用「指针扫描」找指向该地址的指针，逐步回溯指针链。
连接 页「绑定 GG」可自动发现并绑定设备上的 GG 修改器（改版随机包名也能识别）。
工具 页「读GG文件」可读取 GG 数据目录（/data/data/<包名>/…）内的文件，路径限定在 GG 数据目录内。
工具 页 → 填脚本名与 Lua 内容 → 「写入脚本到 /sdcard/ggmcp」→ 在 GG 里执行（脚本用 io.open 把结果写到 <脚本名>.out.txt）→ 回到应用点「读脚本输出」。
服务端本质是一个标准 MCP 服务，本机任何能发 HTTP 的程序都能操作它：
curl -X POST http://127.0.0.1:8788/mcp -H 'Content-Type: application/json' -d '{
"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"gg_search","arguments":{"value":"100","type":"dword","region":"all"}}
}'配合 adb forward tcp:8788 tcp:8788，电脑上的 MCP 客户端（如支持 MCP 的 AI 助手）也能直接接管手机内存搜索。
- 服务地址：默认
http://127.0.0.1:8788/mcp，可改成局域网内其它设备的地址（例如把服务跑在另一台设备上）。 - 服务进程：启动 / 停止 / 查看日志（
/data/local/tmp/ggmcp/ggmcp.log）。 - 部署内置二进制并启动：一次性完成「停止旧实例 → 写入二进制 → 写入控制脚本 → 启动 → 验证 HTTP」。
- 导入二进制文件…：选择自己编译的 64 位
ggmcp写入设备（32 位设备/其它架构请自行编译）。 - 自检：输出 root 状态、二进制、进程、端口监听、KPM/KPatch 模块目录情况。
- 写入控制/自启脚本：生成
/data/local/tmp/ggmcp/ggmcp_ctl.sh（start|stop|status）与/data/adb/service.d/ggmcp.sh（开机自启）。 - 测试 root：逐个探测常见
su路径（含/data/adb/ksu/bin/su、/debug_ramdisk/su等）并给出命中记录。
列表支持：关键字过滤、仅应用、含内核线程、按「活跃优先 / pid / 活跃度 adj / 名称」排序、分页；点选后可「附加选中进程」，另有分离、目标信息、模块列表、暂停（SIGSTOP）/恢复（SIGCONT）。
- 精确搜索：类型
auto会同时扫byte/word/dword/qword/float并按稀有度给出结果，适合不知道数值类型时先探路；也可指定范围起始/结束地址与「按类型对齐」。 - 细化 refine：只在上一次结果集中过滤，用于两步搜索。
- 模糊搜索：见上文工作流。
- 区间搜索：找落在
[min, max]区间的地址。 - Xor 加密搜索：见上文工作流。
结果集分页浏览；选中一条后可写入、修改、冻结、读取、Hex 转储、监视 3 秒（观察数值是否在变）、复制地址；批量区可「全部结果改为该值」「批量冻结结果集」「解冻全部」「清空结果」；分析与快照区可保存/列出快照、分析结果（值分组 + 地址相邻结构体特征）、导出为 JSON。
读写与转储、模块/偏移/指针、快照与交叉分析、GG 联动（含 Lua 脚本）、服务器配置（冻结间隔、搜索候选上限；可「关闭服务器」释放内存）、shell 执行、RAW 调用、列出全部工具。
每一次工具调用都会记录 → CALL 请求参数与 ← RESP 响应摘要（超长内容自动截断），出错也会记录原因；支持一键复制粘贴到 issue。
服务端共 45 个 MCP 工具，App 已把常用操作做成按钮；其余可通过「工具 → RAW 调用」直接调用（工具名 + JSON 参数）。完整参数表见 docs/TOOLS.md。
| 分组 | 工具 |
|---|---|
| 会话与配置 | gg_status gg_config_get gg_config_set gg_server_stop |
| 进程与目标 | gg_list_processes gg_attach gg_detach gg_target_info gg_module_list gg_pause gg_resume |
| 搜索 | gg_search gg_search_refine gg_search_unknown_init gg_search_range gg_search_xor gg_result_count gg_get_results gg_clear_results |
| 读写与修改 | gg_read gg_read_bytes gg_hex_dump gg_write gg_set_results gg_freeze gg_unfreeze gg_freeze_results |
| 分析与定位 | gg_module_base gg_calc_offset gg_pointer_scan gg_watch gg_analyze_results |
| 快照 | gg_snapshot_results gg_list_snapshots gg_delete_snapshot gg_cross_analyze gg_export_results |
| GameGuardian 联动 | gg_bind_gg gg_switch_gg gg_unbind_gg gg_read_gg_saved gg_list_gg_files gg_read_gg_file gg_lua_write gg_lua_read_out |
| 其它 | gg_shell |
GGMCP-Control/
├── app/ # Android 应用（单模块）
│ ├── build.gradle
│ └── src/main/
│ ├── AndroidManifest.xml
│ ├── assets/ # 内置服务端二进制（部署时写入设备）
│ │ ├── ggmcp_arm64 # 真机 arm64-v8a
│ │ └── ggmcp_x86_64 # 模拟器 / x86_64
│ ├── java/com/ggmcp/control/ # 全部 Java 源码（无第三方依赖）
│ │ ├── MainActivity.java # 框架：顶部状态栏 / 标签页 / 后台任务 / 文件选择
│ │ ├── McpClient.java # MCP(JSON-RPC over HTTP) 客户端
│ │ ├── RootShell.java # su 探测、root 执行、二进制写入、预制脚本
│ │ ├── Prefs.java # 轻量配置存储
│ │ ├── AppLog.java # 全局日志缓冲
│ │ ├── Ui.java # 深色主题控件工厂
│ │ └── screen/ # 六个标签页
│ └── res/ # 深色主题、按钮样式、启动图标（纯 vector）
├── server/ # 服务端源码（上游 GPL-3.0 项目的逐字快照）
├── docs/ # 构建 / 使用 / 工具参考 / 架构 / FAQ
├── scripts/ # 重新编译服务端二进制并放进 assets 的脚本
├── LICENSE # GPL-3.0
├── NOTICE.md # 第三方组件与 GPL 合规声明
└── README.md
设备上的运行时布局：
/data/local/tmp/ggmcp/
├── ggmcp # 服务端二进制（从 APK assets 写入，chmod 755）
├── ggmcp_ctl.sh # start | stop | status
├── ggmcp.log # 运行日志
├── config.json # 运行时配置（搜索上限、冻结间隔等，可持久化）
└── snapshots/ # 结果快照
/data/adb/service.d/ggmcp.sh # 开机自启（可选，Magisk/KernelSU）
/sdcard/ggmcp/ # GG Lua 脚本与脚本输出
应用：JDK 17+、Android SDK（compileSdk 36），Gradle/AGP 由 wrapper 提供（Gradle 9.3.0 / AGP 9.0.1）。
# Linux / macOS
./gradlew :app:assembleDebug
# Windows
.\gradlew.bat :app:assembleDebug服务端二进制（想内置自己编译的版本时）：
# 需要 Go 1.22+（上游实测使用 Go 1.27 交叉编译）
cd server
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o ../app/src/main/assets/ggmcp_arm64 main.go engine.go
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o ../app/src/main/assets/ggmcp_x86_64 main.go engine.go或用仓库内脚本一键完成（自动按 ABI 命名并放入 assets/）：
scripts/build-server-binaries.sh # Linux / macOS / WSL
powershell -ExecutionPolicy Bypass -File scripts/build-server-binaries.ps1 # Windows32 位（
arm/386）无法编译：服务端含0x800000000000这样的 64 位地址常量。需要别的架构请自行准备已编译好的 64 位ggmcp，在应用里用「导入二进制文件…」写入。
更详细的构建、签名与常见报错处理见 docs/BUILDING.md。
| 现象 | 处理 |
|---|---|
无法连接 ggmcp 服务 |
「连接」页点「启动服务」；没部署过就先「部署内置二进制并启动」；仍失败点「自检」看 root / 进程 / 端口 |
部署时提示 Text file busy |
旧实例仍在运行；本版本会先停服再写入，若仍出现请先点「停止服务」再部署 |
| 附加成功但搜不到值 | 区域默认 all（anonymous 在现代 Android 上几乎为空）；也可能数值确实不在内存里，试试换类型或 Xor 加密搜索 |
「读取模式」一直是 memfile |
未安装 KPatch-Next + MemoryDriver KPM，走 /proc/<pid>/mem 兜底，不影响基本改值 |
| 结果页空白 | 旧版本在后台线程切页导致的渲染问题，现已修复（切页会回滚到顶部并清焦点） |
| 服务常驻占内存 | 「工具」页点「关闭服务器」，或重启手机；不再需要时不必开机自启 |
| 搜索很慢 / 结果太多 | 「搜索」页把区域从 all 改成 heap，或先用两步搜索缩小范围；「工具」页可调 searchCandidateMax |
| 悬浮窗 / 后台被杀 | 关掉系统的电池优化，或在最近任务里给应用加锁 |
更多问题（含 GG 文件读取按钮的已知问题）见 docs/FAQ.md。
本项目仅供技术研究与学习，用于理解 Android 内存管理、进程调试、MCP 协议与内核读写原理。
- 请勿用于联网游戏作弊——这可能违反游戏服务条款并导致封号，也会破坏其他玩家的体验。
- 请勿用于任何商业用途或非法用途。
- 使用本工具需要 Root，错误写入内存可能导致目标进程崩溃、存档损坏或系统不稳定。
- 本项目与 GameGuardian 官方、KernelSU/KPatch-Next 项目均无隶属或背书关系。
使用者需自行承担一切后果；作者不对任何直接或间接损失负责。
本项目以 GNU General Public License v3.0（GPL-3.0） 发布，见 LICENSE。
由于内置于 APK 的服务端二进制来自同样以 GPL-3.0 发布的开源项目 gameguardian-mcp-server，本仓库遵守 GPL-3.0：服务端完整源码已随仓库提供（server/ 目录，逐字快照），任何人都可以重新编译出与 APK 内一致的二进制。第三方组件与出处见 NOTICE.md。
- gameguardian-mcp-server — 本项目的服务端与协议实现（GPL-3.0）
- GameGuardian — 内存修改器领域的开创性作品
- KernelSU-Next / KPatch-Next — 提供 KPM 内核补丁框架
- ZYPyDoki/Gg_Docking_Kernel — GG 内核对接思路与驱动
欢迎提交 Issue 与 PR：使用问题请带上「日志」页复制的调用记录与设备信息（Android 版本、Root 方案、是否装了 KPM 模块）。详见 CONTRIBUTING.md。