flutter-driver-mcp AGENTS.md

AGENTS.md

Welcome! If you are an AI agent (or a human new to the codebase) looking to contribute to flutter-driver-mcp, this guide provides the necessary architectural context, conventions, and workflows you need to be effective.

🧭 Design Philosophy

These six principles define the soul of the project. Every feature, error message, and API choice should reinforce them. If a change conflicts with any of these, rethink the approach.

1. Agent-First, Not Human-First

This is not a testing framework that happens to have an MCP wrapper. It is purpose-built for LLM agents. Every design decision should be evaluated through the lens of: "Does this make the agent more effective?" — not "Does this look nice in a terminal?" Human developers benefit as a side effect, but the agent is always the primary user.

2. Zero-Friction Entry

A user should go from "I have a Flutter project" to "an agent is controlling it" in one tool call. No pubspec.yaml edits, no entitlement files, no configuration steps, no validate_project pre-flight. The harness imports only dart:* and package:flutter_test — both already in every Flutter project. If you're about to add an external dependency to the harness, stop and find another way.

3. Errors That Coach

A blind error like "Widget not found" costs the agent a retry loop — burning tokens, time, and user patience. Every error in this project should answer three questions: What went wrong? Why? What should the agent try instead? Examples of this in practice:

• "Target is not scrollable and is not inside a scrollable container. Use tap() instead."
• "App uses a custom router like GoRouter. Please use the tap() tool to navigate on-screen elements instead."
• "Too many elements found. Consider using a more specific finder, or pass an 'index' parameter."
• "Did you mean key: [<submit_btn>]?" (fuzzy match on failed finder)

When adding new handlers, always throw errors that suggest the next action. Never throw raw exceptions without context.