From 7aea43eb6ebb896736a0c05cf294e1297e830f1b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?An=C4=B1lcan=20=C3=87ak=C4=B1r?= Date: Wed, 26 Aug 2026 18:44:45 +0300 Subject: [PATCH 1/2] chore(tooling): wire the project's own MCP server Mirrors uptizm#102. This repo had bin/fsa, .artisan/plugins.json and a verification loop written entirely in `./bin/fsa dusk:*` form, but no .mcp.json at all, so a fork inherited the CLI and none of the tools. `.mcp.json` runs `./bin/fsa mcp:serve`: the same dusk, telescope and artisan verbs, offered to an agent as tools in the session that edits the code. The binary is already tracked and executable, and it is byte-identical to uptizm's, so nothing new is installed. docs/verification-loop.md gains the note that the two routes are interchangeable, since both resolve the same running app through the same per-project state under ~/.artisan/sessions/, and that the file stays in CLI form because that form pastes into a terminal. AGENTS.md names it under agent infrastructure, alongside the skills and the reviewer, because that paragraph is what a fork reads to learn what it inherited. --- .github/copilot-instructions.md | 2 +- .mcp.json | 11 +++++++++++ AGENTS.md | 2 +- docs/verification-loop.md | 8 ++++++++ 4 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 .mcp.json diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f61a4cf..9023409 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -71,7 +71,7 @@ This file is canonical. Everything else either points at it or is generated from | `.github/instructions/.instructions.md` | generated from those rules with `applyTo:` frontmatter, so Copilot's PR review applies the same rules | | `docs/verification-loop.md` | how a change is proven: static, visual, and dusk E2E | -Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. +Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. `.mcp.json` wires `./bin/fsa mcp:serve` as a project MCP server, which is the same dusk, telescope and artisan surface `docs/verification-loop.md` drives from the shell, offered as tools instead. After editing this file or any rule, run `bin/sync-instructions` to regenerate the `.github/` mirrors. CI fails when they are out of date. diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..ee2317d --- /dev/null +++ b/.mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "fluttersdk": { + "command": "./bin/fsa", + "args": [ + "mcp:serve" + ], + "cwd": "." + } + } +} diff --git a/AGENTS.md b/AGENTS.md index 27697ef..4332466 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,7 @@ This file is canonical. Everything else either points at it or is generated from | `.github/instructions/.instructions.md` | generated from those rules with `applyTo:` frontmatter, so Copilot's PR review applies the same rules | | `docs/verification-loop.md` | how a change is proven: static, visual, and dusk E2E | -Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. +Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. `.mcp.json` wires `./bin/fsa mcp:serve` as a project MCP server, which is the same dusk, telescope and artisan surface `docs/verification-loop.md` drives from the shell, offered as tools instead. After editing this file or any rule, run `bin/sync-instructions` to regenerate the `.github/` mirrors. CI fails when they are out of date. diff --git a/docs/verification-loop.md b/docs/verification-loop.md index 6fff9dc..c867be2 100644 --- a/docs/verification-loop.md +++ b/docs/verification-loop.md @@ -49,6 +49,14 @@ improvement, rather than looping on the same finding. reads the Semantics tree as a YAML snapshot with stable `[ref=eN]` handles and dispatches real gestures through a six-check actionability gate. +Every verb below has a second face. `.mcp.json` wires `./bin/fsa mcp:serve` as a +project MCP server, so an agent whose client reads that file gets the same dusk, +telescope and artisan surface as tools rather than as shell commands. Both routes +drive the same running app through the same per-project state under +`~/.artisan/sessions/`, so they are interchangeable and can be mixed within one +walk. This file stays written in CLI form because that is the form that can be +pasted into a terminal and read back in a log. + Boot the backend, then the app: ```sh From 2799f29ed8d6654826f9663427b43cb62ad3df05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?An=C4=B1lcan=20=C3=87ak=C4=B1r?= Date: Wed, 26 Aug 2026 19:09:16 +0300 Subject: [PATCH 2/2] docs(mcp): say what a Windows fork has to do with this entry The committed entry is the POSIX shape and nothing said so. `bin/fsa` is a `sh` script, and `fluttersdk_artisan`'s own `mcp:install` refuses that shape on Windows for exactly that reason (`useFsa = _hasFsa() && !_isWindows()`), falling back to a `dart run` command. This repo ships a windows/ runner target and is the thing production apps fork, so a Windows fork opened a server that could not spawn its command with nothing telling them why. The fix is to re-run `mcp:install`, not to hand-edit the file: the tool already knows which of its three shapes a machine has, it is idempotent, and it preserves other server entries. Verified that `dart run :dispatcher mcp:install` resolves here. Keeping the fast shape committed is a measured choice, not an oversight: `./bin/fsa list` is 0.63s against 5.21s for `dart run :dispatcher list`, and a dusk walk pays that per command rather than once per session. Also drops a false clause I had written into the same paragraph: a fresh clone cannot run `mcp:install` either, since `dart run` needs resolved dependencies too. `flutter pub get` is what a clone needs, and it is already the documented first step. --- .github/copilot-instructions.md | 2 +- AGENTS.md | 2 +- docs/verification-loop.md | 14 ++++++++++++++ 3 files changed, 16 insertions(+), 2 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 9023409..9c8c7cc 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -71,7 +71,7 @@ This file is canonical. Everything else either points at it or is generated from | `.github/instructions/.instructions.md` | generated from those rules with `applyTo:` frontmatter, so Copilot's PR review applies the same rules | | `docs/verification-loop.md` | how a change is proven: static, visual, and dusk E2E | -Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. `.mcp.json` wires `./bin/fsa mcp:serve` as a project MCP server, which is the same dusk, telescope and artisan surface `docs/verification-loop.md` drives from the shell, offered as tools instead. +Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. `.mcp.json` wires `./bin/fsa mcp:serve` as a project MCP server, which is the same dusk, telescope and artisan surface `docs/verification-loop.md` drives from the shell, offered as tools instead. That entry is the POSIX shape, since `bin/fsa` is a `sh` script: on Windows, run `dart run :dispatcher mcp:install` to rewrite it into a shape that machine can spawn. After editing this file or any rule, run `bin/sync-instructions` to regenerate the `.github/` mirrors. CI fails when they are out of date. diff --git a/AGENTS.md b/AGENTS.md index 4332466..08ada0d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,7 @@ This file is canonical. Everything else either points at it or is generated from | `.github/instructions/.instructions.md` | generated from those rules with `applyTo:` frontmatter, so Copilot's PR review applies the same rules | | `docs/verification-loop.md` | how a change is proven: static, visual, and dusk E2E | -Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. `.mcp.json` wires `./bin/fsa mcp:serve` as a project MCP server, which is the same dusk, telescope and artisan surface `docs/verification-loop.md` drives from the shell, offered as tools instead. +Other agent infrastructure: skills under `.claude/skills/` (`frontend-design`, `make-component`, `design-first-workflow`), the `component-visual-reviewer` reviewer under `.claude/agents/`, design-culture references under `docs/design-culture/` (Apple HIG, Material 3, Refactoring UI, WCAG, motion, Wind responsive), and the component inventory at `docs/component-registry.md`. `.mcp.json` wires `./bin/fsa mcp:serve` as a project MCP server, which is the same dusk, telescope and artisan surface `docs/verification-loop.md` drives from the shell, offered as tools instead. That entry is the POSIX shape, since `bin/fsa` is a `sh` script: on Windows, run `dart run :dispatcher mcp:install` to rewrite it into a shape that machine can spawn. After editing this file or any rule, run `bin/sync-instructions` to regenerate the `.github/` mirrors. CI fails when they are out of date. diff --git a/docs/verification-loop.md b/docs/verification-loop.md index c867be2..a785bc5 100644 --- a/docs/verification-loop.md +++ b/docs/verification-loop.md @@ -57,6 +57,20 @@ drive the same running app through the same per-project state under walk. This file stays written in CLI form because that is the form that can be pasted into a terminal and read back in a log. +That entry is machine-shaped, and the committed one is the POSIX shape. **On +Windows, run `dart run :dispatcher mcp:install`**: `bin/fsa` is a `sh` script, so +`mcp:install` skips that shape on Windows by design and falls back to a `dart run` +command it can spawn. Regenerating is the fix rather than hand-editing the file, +because the tool already knows which of its three shapes a machine has, and it is +idempotent and preserves any other server entry. + +It is committed in the fast shape because that is what the fast path is for: +measured here, `./bin/fsa list` is 0.63s against 5.21s for +`dart run :dispatcher list`, and a dusk walk pays that per command rather than +once. `bin/fsa` keys its build cache on `pubspec.lock`, which this repo does not +track, so its first run after a clone rebuilds the binary; that clone needs +`flutter pub get` before either route works, which is already the first step. + Boot the backend, then the app: ```sh