Metadata-Version: 2.1
Name: poco-mcp
Version: 0.1.2
Summary: Local MCP server for Poco-based game automation
License: CC BY-NC 4.0
Keywords: mcp,poco,airtest,unity,game-automation
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: Microsoft :: Windows
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: airtest>=1.3.5
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pocoui>=1.0.94
Requires-Dist: pydantic<3.0.0,>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Provides-Extra: report
Requires-Dist: allure-pytest<3.0.0,>=2.13.0; extra == "report"
Requires-Dist: pytest<10.0.0,>=8.0.0; extra == "report"

# poco-mcp

Small local stdio MCP server for live Unity Poco automation.

The server exposes seven tools:

- `observe`: compact visible UI snapshot with stable refs and locators; use `query` to narrow candidates and `include_world=true` for buildings and map HUDs
- `tap`: click one explicit ref, locator, text, or normalized position; optionally wait for text or page scope evidence
- `swipe`: scroll a view by direction and normalized anchor; observe again after each swipe to find an off-screen target
- `wait`: wait for a text or node name to appear or disappear
- `exists`: cheap remote Poco existence check
- `input_text`: type into a focused input
- `run_steps`: execute a previously verified sequence of stable selectors in one MCP call; page and text checks use Poco selectors rather than hierarchy dumps

`observe` and `tap` return `timings_ms` for MCP-side latency. Model tokens and
API cost must be recorded by the model host, not this local MCP.

## Install

```powershell
pip install poco-mcp
poco-mcp
```

## Claude Code Skills

The package includes the verified live-flow and script-export skills, but
Claude Code discovers skills from the current project rather than from Python's
site-packages. Install them once in the user's project:

```powershell
cd <project-directory>
poco-mcp-init
```

This creates `.claude/skills/live-script-builder` and
`.claude/skills/poco-script-export`. Existing skills are left untouched. Use
`poco-mcp-init --force` to update only the files managed by this package.

For a source checkout, install the development extras before running tests:

```powershell
pip install -e ".[dev]"
pytest -q
```

## Shareable Allure Report

Install the optional reporting dependencies on the machine that executes
generated regression scripts:

```powershell
pip install -e ".[report]"
```

Install Allure 2 Commandline with `--single-file` support, or point the runner
at an existing `allure.cmd`. Generate one self-contained Allure HTML file that
can be sent directly to another person. The report keeps Allure cases, semantic
steps, failure attachments, and captured START/PASS/FAIL execution logs.

```powershell
$allureCli = "D:\qa_tools\qa_tools\ai_test_skill\allure\node_modules\.bin\allure.cmd"
poco-mcp-test "outputs\scripts\游戏\个人主页\头像框装扮\test_启用头像框.py" --allure-single-report --allure-command $allureCli --clean
```

For a single script, the default output is
`<script-directory>/reports/<timestamp>/allure-html-single/index.html`; that
`index.html` is the only file that needs to be shared. Runs containing multiple
input paths use `outputs/reports/<timestamp>/` instead. Pass a directory after
`--allure-single-report` when a fixed output location is preferred.

Pytest continues with later independent tests after a failed test; each
individual business flow stops at its first failed step.

## 常用执行命令

推荐直接使用一键入口。批量执行装扮目录并生成一份汇总 Allure 报告：

```powershell
.\run-report.cmd "outputs\scripts\游戏\个人主页\装扮"
```

批量执行装扮目录、但排除工厂装扮脚本：

```powershell
.\run-report.cmd "outputs\scripts\游戏\个人主页\装扮" --ignore "outputs\scripts\游戏\个人主页\装扮\test_工厂装扮启用.py"
```

执行单个脚本：

```powershell
.\run-report.cmd "outputs\scripts\游戏\个人主页\Boss装备\test_帽子装备强化.py"
```

首次使用时安装项目和报告依赖：

```powershell
pip install -e ".[report]"
```

执行 Boss 装备的帽子强化脚本，并生成可直接发送的 Allure 单文件报告：

```powershell
python -m poco_mcp.test_runner "outputs\scripts\游戏\个人主页\Boss装备\test_帽子装备强化.py" --allure-single-report --allure-command "D:\qa_tools\qa_tools\ai_test_skill\allure\node_modules\.bin\allure.cmd"
```

执行其他脚本时，只需替换命令中的 `.py` 路径：

```powershell
python -m poco_mcp.test_runner "<脚本路径.py>" --allure-single-report --allure-command "D:\qa_tools\qa_tools\ai_test_skill\allure\node_modules\.bin\allure.cmd"
```

单脚本报告默认生成在：

```text
<脚本所在目录>\reports\<时间戳>\allure-html-single\index.html
```

批量报告默认生成在被执行目录的
`reports\<时间戳>\allure-html-single\index.html`。每个脚本是一个独立用例；
某个用例失败后，pytest 会继续执行后续用例，并在同一份报告中汇总结果。

### 速度说明

- 导出的 pytest 脚本直接使用已验证选择器，不再执行探索和整树观察。
- `wait(timeout=10)` 是最长等待时间，节点提前出现就立即继续，并非固定等待10秒。
- 同一批次复用一个 Unity Poco 连接，避免每个脚本重复查找窗口和握手。
- Allure 单文件只在整批结束后生成一次；本机验证通常约需10到15秒，批量运行时由全部用例共同分摊。
- 总执行时间主要取决于游戏页面切换、脚本中明确要求的等待和用例数量。

## Allure Reports

Use the regular multi-file Allure report only when local `allure open` browsing
or history assets are needed.

```powershell
# One semantic test script
poco-mcp-test outputs\scripts\游戏\个人主页\Boss装备\test_帽子宝石升级.py --allure-report outputs\allure-report --clean

# A suite directory
poco-mcp-test outputs\scripts\商业化\商店 --allure-report outputs\allure-report --clean
```

Raw results are written to `outputs/allure-results/`. The generated HTML is in
`outputs/allure-report/`. Future exported scripts use semantic Allure steps and
attach a screenshot only when a step fails.

## License

This project is licensed under [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/).
Commercial use is not permitted.

Run it with the configured Python environment:

```powershell
$env:PYTHONPATH = "$PWD\src"
python -m poco_mcp.server
```

Set `POCO_MCP_HOST` and `POCO_MCP_PORT` when the target is not the default
`127.0.0.1:5001`. Install `pocoui` and `airtest` in the same environment.
