# algorithmaide-mcp

[中文文档](docs/README.zh-CN.md)

**Special thanks to Junge (军哥) for open-sourcing AlgorithmAide.**

`algorithmaide-mcp` is an MCP server for real-device Android reversing workflows. It wraps AlgorithmAide config writes, AppSwitch/logList sync, LSPosed scope sync, Frida script injection, and runtime log queries into a stable MCP toolset.

## Upstream And Downloads

- **This MCP targets AlgorithmAide Pro (`com.junge.algorithmAidePro`)**.
- **AlgorithmAide Pro APK:** 关注公众号 **算法助手Plus** 下载 APK。
- **LSPosed_mod.zip:** please prepare a CLI-enabled LSPosed_mod package for this workflow.
- **Magisk APK:** please install official Magisk before running this MCP.

## Verified Scope

This project is currently verified only on:

- Android `10` (API 29)
- Root with `Magisk` (`su 0 sh -c ...` works)
- `LSPosed_mod` `1.9.3_mod(7296)` with CLI enabled
- Device sample: Pixel 4

Important compatibility notes:

- Non-mod LSPosed is currently **not supported** because CLI is unavailable.
- Other Android versions and environments may work, but you must validate them yourself.
- LSPosed_mod CLI scope updates are already built into this MCP (`sync_lsposed_scope` and high-level workflow tools).

Before real use, run:

```bash
npm run device:preflight -- --target-package <your.package>
npm run device:smoke:suite -- --target-package <your.package>
```

## Quick Start

Clone and install dependencies:

```bash
git clone https://github.com/vwww-droid/algorithmaide-mcp.git algorithmaide-mcp
cd algorithmaide-mcp
npm install
```

Configure mcp profile:

```json
{
  "mcpServers": {
    "algorithmaide": {
      "command": "node",
      "args": [
        "/absolute/path/to/algorithmaide-mcp/bin/algorithmaide-mcp.js"
      ]
    }
  }
}
```

## Common Commands

```bash
npm run device:preflight -- --target-package com.mb.hawkeye
npm run device:smoke -- --target-package com.mb.hawkeye
npm run device:smoke:suite -- --target-package com.mb.hawkeye
npm run release:selfcheck
npm test
```

## Build Notes (LSPosed_mod)

If you need reproducible LSPosed_mod builds for this workflow, use the pinned-version one-click script from your companion project:

- `/Users/admin/Projects/Reverses/LSPosed_mod/build-last.sh`

This script sets Java from `.java-version`, builds required `libxposed` artifacts, then runs `zipAll`, and should produce a usable LSPosed_mod package.

## Tool Overview

Frequently used tools:

- `read_target_state`
- `apply_algorithm_aide_config`
- `add_custom_hooks`
- `inject_frida_script`
- `query_agent_logs`
- `query_frida_logs`

Full tool contracts: [docs/tool-contracts.md](docs/tool-contracts.md)

## Documentation

- Getting started: [docs/getting-started.md](docs/getting-started.md)
- Compatibility matrix: [docs/compatibility.md](docs/compatibility.md)
- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
- Examples: [examples/README.md](examples/README.md)
- Architecture: [docs/architecture.md](docs/architecture.md)

## Contributing

Issues and PRs are welcome.

When opening an issue, include:

- Device and system info (Android version, root solution, LSPosed version)
- Target package
- Commands you ran
- JSON output from `device:preflight` and `device:smoke:suite`

## License

MIT