This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
MaaMCP is an MCP (Model Context Protocol) server that exposes MaaFramework's automation capabilities to AI assistants. It provides Android device control via ADB and Windows desktop automation via window handles.
# Install dependencies in development mode
pip install -e .
# Run MCP server (standard serial mode)
maa-mcp
# or
python -m maa_mcp
# Run MCP server (pipeline mode with background screenshot thread)
maa-mcp-server
# or
python -m maa_mcp.pipeline_server
# Run tests
pytest tests/ -v
pytest tests/test_basic.py -v # run specific fileThe package has multiple entry points defined in pyproject.toml:
maa-mcp/maa_mcp: Standard MCP server (main.py)maa-mcp-server/maa_mcp_server: Pipeline server with multi-threaded background monitoring (pipeline_server.py)
- core.py: Creates the FastMCP server instance, global registries (
object_registry,controller_info_registry), andControllerInfodataclass - registry.py:
ObjectRegistryclass for managing controller instances by ID - paths.py: Cross-platform data directory management using
platformdirs
| Module | Purpose |
|---|---|
adb.py |
ADB device discovery (find_adb_device_list) and connection (connect_adb_device) |
win32.py |
Windows window discovery (find_window_list) and connection (connect_window) |
vision.py |
Screen capture (screencap) and OCR recognition (ocr) |
control.py |
Input operations: click, double_click, swipe, input_text, click_key, keyboard_shortcut, scroll |
resource.py |
Global Resource/Tasker cache; multi-bundle resource path loading; pipeline node management |
download.py |
OCR model file download utilities |
agent_supervisor.py |
Agent 子进程生命周期管理(MFAAvalonia 风格):从 interface.json 读 agent 配置、TCP 模式启子进程、Windows JobObject 绑定、stdout/stderr 流式日志、start / stop / shutdown_all API(设计文档) |
pipeline_tools.py |
Pipeline protocol docs, single/multi-file load_pipeline & run_pipeline, save_pipeline, clear_pipeline_resources, stop_pipeline(原子地关 Tasker / Agent 子进程 / OCR 循环) |
pipeline/ |
Pipeline mode state management and logging |
- Serial Mode: Synchronous execution where each operation waits for the previous to complete
- Pipeline Mode: Multi-threaded mode where a background thread continuously captures screenshots and caches them in a queue for the main thread to process decisions
All device/window control flows through:
- Discovery functions return device/window identifiers
- Connection functions create
AdbControllerorWin32Controllerinstances (frommaafw) and register them inobject_registry - Operations use
controller_idto look up the controller inobject_registry controller_info_registrystores metadata (controller type, connection params) for eachcontroller_id
maafw>=5.2.6: Core automation framework (MaaFramework)fastmcp>=2.0.0: MCP server frameworkopencv-python>=4.0.0: Image processing for screenshotsloguru>=0.7.0: Loggingplatformdirs>=4.0.0: Cross-platform paths
run_pipeline(controller_id, pipeline_path) accepts either a single path (str) or a list of paths (list[str]). When multiple files are provided, nodes from all files are merged into the same global node table; node next references resolve in the merged namespace (cross-file references work).
Conflict handling:
- Default
on_conflict="strict": any node name conflict raises an error and writes nothing to the Resource on_conflict="overwrite": later file's entire node replaces earlier file's (MaaFramework default); conflicts are reported inresult.warnings
Loading is atomic: all pre-validation (file existence, JSON validity, conflict detection) must pass before a single Resource.override_pipeline(merged) call writes to the Resource. Failures leave the Resource unchanged.
Once loaded, pipeline nodes persist in the Resource until clear_pipeline_resources() is called or the process exits.
MaaFramework's own pipeline parser (meojson json::parsec) accepts JSONC, so MaaMCP must too — otherwise the same file loads in MaaFramework but fails in MaaMCP.
jsonc.py re-implements that semantics in Python (zero new dependencies):
- Allowed:
//line comments,/* */block comments, trailing commas in objects/arrays (a comma in an empty container —{,}/[,]— is still a syntax error, same as MaaFramework) - Rejected (same as MaaFramework): unquoted keys, single-quoted strings,
NaN/Infinity, duplicate keys, lone surrogates (e.g."\ud800")
Where it applies: pipeline files read by load_pipeline / run_pipeline / benchmark_node, the pipeline_json string passed to save_pipeline (output is still normalized standard JSON — comments are dropped), and interface.json read by the agent supervisor.
Implementation note: comments are replaced with equal-length whitespace (newlines preserved), then trailing commas are stripped, then the text goes to stdlib json.loads. Byte offsets are preserved, so stdlib's line/column error positions apply directly to the original file (a leading UTF-8 BOM shifts them by one character, since the BOM is stripped before parsing).
Three deliberate deviations from meojson:
- Numbers that overflow to
inf(1e999) are rejected — MaaMCP re-serializes the parsed result into strict JSON forResource.override_pipeline, so meojson's literal round-trip would write back the invalid literalInfinity. loadsaccepts any top-level value while meojson only accepts objects/arrays (callers still require a non-empty object).- Trailing residue after the top-level value is reported as an error. meojson's
skip_whitespaceconflates "end of input" with "malformed comment start", so it silently accepts and discards a trailing/xor an unterminated block comment; MaaFramework inherits that. This direction is stricter — MaaMCP never accepts a file MaaFramework rejects. An unterminated comment inside the document is rejected by both.
interface.json caveat: MaaMCP tolerates comments there, and so does MFAAvalonia (Newtonsoft.Json skips comments). But MAAGC's own agent/main.py reads that file with stdlib json.load to detect the version — a commented interface.json makes it log an exception and fall back to version "unknown" (it only decides dev-mode vs. venv setup). Keep interface.json comment-free if you rely on MAAGC's version detection.
For pipelines containing action: "Custom" nodes (e.g. MAAGC's TaskProcessor / YearlyTaskProcessor), MaaMCP spawns a Python agent subprocess to host the custom callbacks, following the MFAAvalonia pattern.
How it works:
- When
run_pipelineis called with aresource_path, the supervisor (agent_supervisor.py) looks up the chain for aninterface.jsoncontaining anagentblock. - If found, it generates a random 8-char identifier, creates an
AgentClient.create_tcp(0)(OS-assigned port → identifier"127.0.0.1:<port>"), and binds it to the Resource + Controller + Tasker. - The agent Python subprocess is launched with the identifier appended as the last CLI argument (MAAGC
agent/main.py:382reads it viasys.argv[-1]). - On Windows, the subprocess is bound to a
JobObjectwithJOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSEso ataskkill /Fon MaaMCP automatically reaps the agent. On POSIX,start_new_session=Trueis used plus anatexitfallback.
Lifecycle contract:
run_pipelineauto-starts the agent whenstart_agent=True(default).stop_pipeline(controller_id)atomically stops: OCR loop →tasker.stop()→AgentClient.disconnect()→ subprocessterminate()(3s grace) →kill()→ registry cleanup.atexitregistersagent_supervisor.shutdown_all()as a final safety net.
The agent config schema (read from interface.json):
{
"agent": {
"child_exec": "python",
"child_args": ["-u", "agent/main.py"],
"identifier": "optional-fixed-id",
"timeout": 30,
"auto_start": true
}
}Required MCP tool hygiene: The AI must call stop_pipeline(controller_id) after running a pipeline that auto-started an agent. Otherwise the agent subprocess remains running in the background, holding the TCP port, CPU and memory. JobObject on Windows is a safety net but does not free MaaMCP-side resources (TCP socket, registry entries, loguru file handles).
See docs/research/custom-action-support.md for the full design rationale and reference to MFAAvalonia's AgentHelper.cs.
OCR models and screenshots are stored in platform-specific directories:
- Windows:
C:\Users\<user>\AppData\Local\MaaMCP\ - macOS:
~/Library/Application Support/MaaMCP/ - Linux:
~/.local/share/MaaMCP/
Notes for AI agents (Claude Code, etc.) working in this project. Tool-level details live in the tool descriptions themselves; this section captures cross-cutting patterns.
- Best: 5–10 s/step
- Normal: 10–20 s/step
- Anomaly: >30 s/step → reflect: am I over-explaining, re-verifying, or waiting on the wrong thing?
Speedup tactics (in order of impact):
- Batch parallel tool calls in one round
- Skip intermediate verification (click → input without
screencap/ocrbetween) - Don't re-state what's already obvious; one-line conclusion per action
- When uncertain, ask the user, don't self-argue for 5 s
Before drawing any conclusion from a tool call, verify:
- "What am I measuring + which variable am I controlling?" — defined before running
- Repeated at least 2–3 times; single pass never concludes
- Verified with independent signal (e.g.
screencap+ocr), not by guessing "should be here" - Between each step, asked "did my prior step contaminate this one?"
- Interpreted results counterfactually: "could the dropdown have appeared without my click?" / "could the text have been there from a prior test?"
- "API returned True" ≠ "action took effect visually" — never trust API alone for visual state
ocr/screencapacceptregion=(x,y,w,h): regions use full controller screenshot coordinates. OCR usesJOCR(roi=...); the framework restores the origin automatically. Do not repeat roi in roi_offset.- Shared coordinate basis: Win32/ADB default to a 720-pixel short side. Connection parameter
target_short_sideaccepts another positive integer orNone(native size).screencapdefaults toresolution=None, preserving controller image dimensions. OCR, actions, and Pipelines use that controller's coordinates. Non-720 modes do not automatically adapt existing 720p templates or ROIs. - Locating targets after cropping/resizing:
screencap(..., include_metadata=True)returnspath,coordinate_size,image_size, andimage_to_controller. Map image point(u,v)to(u*sx+ox,v*sy+oy)and round before acting. The default return remains a path string; metadata'spathcan be passed tosave_captured_image. - Win32
clickon Chromium/Electron windows can silent-fail — PostMessage mouse events are dropped, API returns True but no visual change. Keyboard events (post_input_text,post_key_*) still work because Chrome's keyboard handler is more lenient. Tool description has the full caveat. input_textrequires target focus — it sends keyboard events to the focused element. Ifclickfailed to focus,input_textlands elsewhere. Sequence:click(target)→input_text(text)in immediate succession, noscreencap/ocrbetween.- Controller has a lifecycle — system cross-day, Chrome restart, or sleep/wake invalidates
controller_id. Symptom: all operations returnNone/Falsesilently. Fix: re-callfind_window_list()+connect_window(). - Don't conflate "test contamination" with "tool bug" — if a tool worked once and then fails, check the test state before assuming the tool is broken. Window switching, manual user interaction between calls, and stale controllers are common contamination sources.
save_captured_imagewrites into project bundle, not MaaMCP data dir — destination is<bundle_root>/image/<subcategory>/<name>.png(the path TemplateMatch'stemplatefield reads from).bundle_rootis the directory passed toResource.post_bundle(). For MAAGC it'sassets/resource/base/; for MaaFramework sample it's<repo>/sample/resource. Defaultoverwrite=Falseprotects existing templates — passTrueexplicitly when updating.benchmark_nodemeasures wall-clock, not per-node timing — returnedlatency_msis fullpost_task → TaskDetailtime, including entry recognition overhead (~50-200ms). For per-node estimate subtract that baseline.mean_score=Nonewithsuccesses=0means the node never hit — threshold/ROI/template mismatch.run_pipeline/benchmark_nodeaccept per-runpipeline_override— field-level node overrides passed topost_task(same mechanism as interface.json'spipeline_override): tightenroi, tweakexpected/threshold/timeoutfor single-node verification without editing pipeline files. Applies to one run only — the Resource is untouched. Node names not present in the loaded files show up inwarnings(typo'd names silently no-op, so check them).benchmark_noderejects overridingnexton entry/target (would break its isolation chain).run_pipelinesupports tool-sidetimeout_seconds— polls the task and callspost_stop()on expiry, returningstatus="timeout"+ partial node details instead of blocking the MCP call indefinitely (a node that never matches burns its owntimeout, 20s by default). Note: MaaFramework marks a stopped task's own status as succeeded — the tool reports"timeout"explicitly instead of trusting it. Recommended 5-15s for single-node verification;None(default) keeps the old unbounded behavior.
When a TemplateMatch / OCR / ColorMatch node isn't reliable, iterate this loop (issue #36 item #4):
screencap(cid)→ Read source frame, visually locate target regionscreencap(cid, region=(x, y, w, h))→ crop just that region- Read cropped image → confirm it's the intended element
save_captured_image(cropped_path, bundle_root, subcategory, name)→ promote it to a TemplateMatch template- In pipeline JSON:
"recognition": "TemplateMatch", "template": "<subcategory>/<name>.png" benchmark_node(cid, pipeline_path, node=<name>, iterations=10..50)→ inspectmean_score,latency_ms,all_results_samples- If
mean_score< 0.85 orsuccesses < iterations: tighten ROI (smallerregion), raisethreshold, or refresh the template with a fresh capture — try candidate values viapipeline_override={"<name>": {"roi": [...], "threshold": ...}}first (no file edits), then write the winning values back into the pipeline JSON - Repeat 2-7 until stable
For MaaMCP-side pipeline infra testing, see tests/test_dbg_pipeline.py (gated by @pytest.mark.integration; skips if MaaDbgControlUnit DLL isn't shipped).
tests/test_performance_stress.py drives real devices/windows (clicks, swipes, typed text, key presses). It is skipped unless MAA_STRESS=1 is set, and the target must be named explicitly via MAA_STRESS_DEVICE / MAA_STRESS_WINDOW.
Do not "fix" it by picking find_window_list()[0]: the first desktop window is usually the user's editor (VS Code), and the stress test's synthetic clicks/keystrokes land on it — this closed VS Code during a plain pytest tests/ run. This mirrors the rule in win32.py: never auto-select a window when several are available.
- CLAUDE_CN.md: Chinese version of this document
Rule: When updating this file, always sync changes to CLAUDE_CN.md