fluttersdk-artisan

fluttersdk_artisan

CLI framework and stdio MCP server for Flutter dev loops, designed for LLM agents. The running app exposes a process + VM Service surface plus an MCP server; the agent calls artisan_* tools (or ./bin/fsa <cmd> from a shell) to start the app, hot-reload it, read its logs, evaluate Dart expressions against the running isolate, and discover what other plugin tools (dusk_*, telescope_*) are available, all without leaving the conversation.

This skill assumes the host app already has artisan installed (bin/dispatcher.dart present, lib/app/_plugins.g.dart non-empty, .mcp.json wired). If not, run dart pub add fluttersdk_artisan followed by dart run fluttersdk_artisan install once from the app root, then ./bin/fsa mcp:install to write the MCP entry, then reconnect the client.

1. Core Laws

1. Two MCP boot paths produce two different tool catalogs. The substrate entry dart run fluttersdk_artisan:mcp (via bin/mcp.dart of the artisan package) forces delegateToConsumer: false and surfaces ONLY the 10 substrate tools (artisan_start, artisan_stop, ..., artisan_tinker). The consumer dispatcher entry ./bin/fsa mcp:serve (via bin/dispatcher.dart of the host app) loads lib/app/_plugins.g.dart and surfaces substrate tools PLUS every plugin's mcpTools() (dusk_* from fluttersdk_dusk, telescope_* from fluttersdk_telescope, etc.). Inspect .mcp.json to see which path is wired; ./bin/fsa mcp:serve is the dev default. Diagnose a missing plugin namespace by calling artisan_list: dusk: / telescope: groups appear only when the dispatcher wrapper loaded the provider.

2. State lives in a PER-PROJECT session directory, and it is the single source of truth for connectedness. artisan_start writes ~/.artisan/sessions/<hash>/state.json atomically (pid + vmServiceUri

   • FIFO path + device + ports), keyed by the project root, with the log and the FIFO beside it. Two projects can be driven at once and neither overwrites the other. ~/.artisan/state.json still exists as a pointer to whichever session started last, read as a fallback and used by the hand-written recovery recipe, but it is NOT where your session lives. Every connected tool reads the session on dispatch. When absent, the soft-fail contract holds: artisan_status returns {"running": false}, artisan_stop no-ops (exit 0), artisan_tinker and any plugin tool that needs the VM Service return isError: true with an actionable "Run artisan start first" message. The MCP server stays online either way; failed calls do not kill the session.