Skip to content

Commit 709e464

Browse files
authored
feat(mcpb): one-click Claude Desktop Extension for probe-mcp (#102)
Package probe-mcp as a .mcpb Claude Desktop Extension. Users install with one click — no brew, no JSON config, no PATH setup. CI builds .mcpb bundles for darwin-arm64, darwin-amd64, linux-amd64, and windows-amd64 on every release tag and attaches them as assets. probe-mcp change cmd/probe-mcp/main.go: read PROBE_PROJECT_DIR at startup and os.Chdir into it. The .mcpb manifest's user_config.projectRoot is a directory picker surfaced as this env var, so run_tests, list_files, get_report, init_project resolve paths against the user's Flutter project rather than Claude Desktop's cwd. mcpb/template/manifest.json manifest_version 0.4 schema, server.type 'binary', bundle-relative command via ${__dirname}/probe-mcp, all 18 tools enumerated for the Claude Desktop install dialog, projectRoot directory picker. scripts/build-mcpb.sh Local build helper. Stages binary + rendered manifest into a temp dir, validates manifest with npx @anthropic-ai/mcpb validate, packs via mcpb pack. Substitutes @@Version@@, @@platform@@, @@ENTRY_POINT@@, @@command@@ placeholders. CI (.github/workflows/release.yml) New build-mcpb job runs after build, with a matrix for darwin-arm64, darwin-amd64, linux-amd64, win32-amd64. Downloads the per-platform probe-mcp artifact, runs build-mcpb.sh, uploads the .mcpb. Release job's needs extended to include build-mcpb so the .mcpb assets are attached to the GitHub release alongside binaries. Docs README.md: MCP Server section now leads with 'Install — Option 1: Claude Desktop Extension (recommended)' showing the four .mcpb download links + 4-step install. Manual config relegated to Option 2. website/src/content/docs/tools/mcp.md: same restructuring; manual Claude Desktop / Cursor steps moved under Option 2 as nested H3s. CHANGELOG.md: 0.9.4 entry. Versions bumped to 0.9.4 probe_agent, probe_annotation, probe_gen pubspec.yaml + CHANGELOG.md vscode/package.json docs/wiki/Home.md website/src/content/docs/tools/mcp.md (verify snippet) probe_gen depends on flutter_probe_annotation: ^0.9.4 Local verification Built flutter-probe-darwin-arm64.mcpb via scripts/build-mcpb.sh: schema validation passes, packed size 1.1MB, manifest contains correct version (0.9.4), platforms [darwin], command pointing at ${__dirname}/probe-mcp, projectRoot user_config, 18 tools. go test ./...: all 16 packages pass. staticcheck ./...: zero issues. bash -n scripts/build-mcpb.sh: syntax OK.
1 parent 168264f commit 709e464

15 files changed

Lines changed: 302 additions & 16 deletions

File tree

.github/workflows/release.yml

Lines changed: 53 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -153,8 +153,60 @@ jobs:
153153
name: studio-${{ matrix.os }}-${{ matrix.arch }}
154154
path: ${{ env.STUDIO_ASSET }}
155155

156+
build-mcpb:
157+
name: Build .mcpb extensions
158+
needs: build
159+
runs-on: ubuntu-latest
160+
strategy:
161+
matrix:
162+
include:
163+
- goos: darwin
164+
goarch: arm64
165+
platform: darwin
166+
- goos: darwin
167+
goarch: amd64
168+
platform: darwin
169+
- goos: linux
170+
goarch: amd64
171+
platform: linux
172+
- goos: windows
173+
goarch: amd64
174+
platform: win32
175+
steps:
176+
- uses: actions/checkout@v6
177+
178+
- uses: actions/setup-node@v6
179+
with:
180+
node-version: "22"
181+
182+
- name: Download probe-mcp binary
183+
uses: actions/download-artifact@v8
184+
with:
185+
name: probe-${{ matrix.goos }}-${{ matrix.goarch }}
186+
path: bin
187+
188+
- name: Build .mcpb bundle
189+
env:
190+
GOOS: ${{ matrix.goos }}
191+
GOARCH: ${{ matrix.goarch }}
192+
PLATFORM: ${{ matrix.platform }}
193+
run: |
194+
VERSION="${GITHUB_REF_NAME#v}"
195+
EXT=""
196+
if [ "${GOOS}" = "windows" ]; then EXT=".exe"; fi
197+
BINARY="bin/probe-mcp-${GOOS}-${GOARCH}${EXT}"
198+
chmod +x "$BINARY" || true
199+
mkdir -p mcpb-out
200+
scripts/build-mcpb.sh "$BINARY" "$PLATFORM" "$VERSION" mcpb-out
201+
shell: bash
202+
203+
- uses: actions/upload-artifact@v7
204+
with:
205+
name: mcpb-${{ matrix.goos }}-${{ matrix.goarch }}
206+
path: mcpb-out/*.mcpb
207+
156208
release:
157-
needs: [build, build-studio]
209+
needs: [build, build-studio, build-mcpb]
158210
runs-on: ubuntu-latest
159211
steps:
160212
- uses: actions/checkout@v6

CHANGELOG.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
66

77
## [Unreleased]
88

9+
## [0.9.4] - 2026-05-09
10+
11+
### Added
12+
- **Claude Desktop Extension (`.mcpb`)**`probe-mcp` is now packaged as a one-click Claude Desktop Extension. Users drag `flutter-probe-<platform>-<arch>.mcpb` onto Claude Desktop's Extensions settings, pick their Flutter project directory, and all 18 MCP tools are available. No `brew install`, no JSON config editing, no PATH setup. CI builds and attaches `.mcpb` artifacts for darwin-arm64, darwin-amd64, linux-amd64, and windows-amd64 to every release.
13+
- Manifest declares `server.type: "binary"` and bundles the platform-specific `probe-mcp` executable.
14+
- `user_config.projectRoot` is a directory picker surfaced as the `PROBE_PROJECT_DIR` env var.
15+
- `probe-mcp` reads `PROBE_PROJECT_DIR` at startup and `os.Chdir`s into it so `run_tests`, `list_files`, `get_report`, and `init_project` resolve paths against the user's Flutter project rather than Claude Desktop's working directory.
16+
- `scripts/build-mcpb.sh` produces a bundle locally from any built `probe-mcp` binary; uses `npx @anthropic-ai/mcpb` for schema validation and packing.
17+
- New `build-mcpb` job in `.github/workflows/release.yml` runs after `build`, downloads the per-platform `probe-mcp` artifacts, packs them into `.mcpb` bundles, and attaches them to the GitHub release.
18+
919
## [0.9.3] - 2026-05-09
1020

1121
### Added

README.md

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -485,7 +485,24 @@ Every CLI feature is accessible from MCP. Key capabilities an agent can use:
485485
- **Pre-write validation**`write_test` parses the content before writing; syntax errors are returned immediately without creating the file
486486
- **Interaction recording**`record` captures gestures and returns a `.probe` file
487487

488-
Configure your MCP client:
488+
### Install — Option 1: Claude Desktop Extension (recommended)
489+
490+
Each release publishes a one-click `.mcpb` extension for Claude Desktop. No `brew install`, no JSON config, no PATH setup.
491+
492+
1. Download the bundle for your platform from the [latest release](https://github.com/AlphaWaveSystems/flutter-probe/releases/latest):
493+
- `flutter-probe-darwin-arm64.mcpb` — Apple Silicon Macs
494+
- `flutter-probe-darwin-amd64.mcpb` — Intel Macs
495+
- `flutter-probe-linux-amd64.mcpb` — Linux x86_64
496+
- `flutter-probe-win32-amd64.mcpb` — Windows x86_64
497+
2. In Claude Desktop, open **Settings → Extensions → Install Extension**, pick the `.mcpb` file.
498+
3. When prompted, select your **Flutter project directory** (the folder that contains `probe.yaml` and `tests/`).
499+
4. Done — all 18 tools appear in Claude.
500+
501+
The bundle ships the `probe-mcp` binary inside the extension; auto-updates and lifecycle are managed by Claude Desktop.
502+
503+
### Install — Option 2: manual MCP server config
504+
505+
For Cursor or any other MCP-compatible client, install the binary and point your client at it:
489506

490507
```json
491508
{

cmd/probe-mcp/main.go

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// Command probe-mcp is the standalone MCP (Model Context Protocol) server
22
// for FlutterProbe. It speaks JSON-RPC 2.0 over stdio and exposes the same
3-
// 10 tools available via `probe mcp-server` (which now delegates here).
3+
// tools available via `probe mcp-server` (which now delegates here).
44
//
55
// Configure your MCP client (Claude Desktop, Cursor, etc.) to point at this
66
// binary directly:
@@ -12,6 +12,11 @@
1212
// }
1313
// }
1414
// }
15+
//
16+
// When packaged as a Claude Desktop Extension (.mcpb bundle), users select
17+
// their Flutter project directory at install time and the host passes it
18+
// via PROBE_PROJECT_DIR. probe-mcp chdirs into it on startup so tools like
19+
// run_tests, list_files, and get_report find probe.yaml and tests/.
1520
package main
1621

1722
import (
@@ -23,11 +28,22 @@ import (
2328

2429
// Version is set at build time via -ldflags, e.g.
2530
//
26-
// go build -ldflags="-X main.Version=0.6.0" ./cmd/probe-mcp
31+
// go build -ldflags="-X main.Version=0.9.4" ./cmd/probe-mcp
2732
var Version = "dev"
2833

2934
func main() {
3035
mcp.Version = Version
36+
37+
// Honor PROBE_PROJECT_DIR — set by .mcpb installs from the user_config
38+
// directory picker so tools resolve relative paths (probe.yaml, tests/)
39+
// against the user's Flutter project rather than Claude Desktop's cwd.
40+
if dir := os.Getenv("PROBE_PROJECT_DIR"); dir != "" {
41+
if err := os.Chdir(dir); err != nil {
42+
fmt.Fprintf(os.Stderr, "probe-mcp: PROBE_PROJECT_DIR=%q: %v\n", dir, err)
43+
os.Exit(1)
44+
}
45+
}
46+
3147
if err := mcp.NewServer().Run(); err != nil {
3248
fmt.Fprintln(os.Stderr, "probe-mcp:", err)
3349
os.Exit(1)

docs/wiki/Home.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Welcome to the FlutterProbe wiki. This documentation covers architecture details
1818

1919
## Project Status
2020

21-
FlutterProbe is in active development. Current version: **0.9.3**.
21+
FlutterProbe is in active development. Current version: **0.9.4**.
2222

2323
### Repository Structure
2424

mcpb/template/manifest.json

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
{
2+
"$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
3+
"manifest_version": "0.4",
4+
"name": "flutter-probe",
5+
"display_name": "FlutterProbe",
6+
"version": "@@VERSION@@",
7+
"description": "End-to-end testing for Flutter apps. Manage devices, author and run ProbeScript tests, capture screenshots, generate reports — directly from Claude Desktop.",
8+
"long_description": "FlutterProbe is a high-performance E2E testing framework for Flutter mobile apps. This extension exposes 18 tools to Claude:\n\n- **Device lifecycle** — list, start, and shut down iOS simulators and Android emulators.\n- **Test authoring** — read and write `.probe` files, dump the live widget tree, take screenshots.\n- **Execution** — run tests on a single device, in parallel, or as multi-device composite tests.\n- **Reporting** — read JSON results, generate HTML reports.\n- **Project management** — initialize a new project, record interactions, AI-generate tests from a prompt.\n\nAfter install, Claude can read your widget tree and write tests that target real selectors — no manual JSON config or PATH setup required.",
9+
"author": {
10+
"name": "Alpha Wave Systems",
11+
"url": "https://alphawavesystems.com"
12+
},
13+
"homepage": "https://flutterprobe.dev",
14+
"repository": {
15+
"type": "git",
16+
"url": "https://github.com/AlphaWaveSystems/flutter-probe"
17+
},
18+
"documentation": "https://flutterprobe.dev/tools/mcp/",
19+
"support": "https://github.com/AlphaWaveSystems/flutter-probe/issues",
20+
"license": "BSL-1.1",
21+
"keywords": ["flutter", "testing", "e2e", "probe", "mobile", "android", "ios"],
22+
"server": {
23+
"type": "binary",
24+
"entry_point": "@@ENTRY_POINT@@",
25+
"mcp_config": {
26+
"command": "@@COMMAND@@",
27+
"args": [],
28+
"env": {
29+
"PROBE_PROJECT_DIR": "${user_config.projectRoot}"
30+
}
31+
}
32+
},
33+
"user_config": {
34+
"projectRoot": {
35+
"type": "directory",
36+
"title": "Flutter project directory",
37+
"description": "Path to the Flutter app you want to test. Should contain probe.yaml and a tests/ folder. Tools like run_tests and get_report resolve paths against this directory.",
38+
"default": "${HOME}",
39+
"required": true
40+
}
41+
},
42+
"compatibility": {
43+
"platforms": ["@@PLATFORM@@"]
44+
},
45+
"tools_generated": false,
46+
"tools": [
47+
{"name": "list_devices", "description": "List connected/booted simulators, emulators, and physical devices."},
48+
{"name": "list_simulators", "description": "List all iOS simulators (booted + shutdown)."},
49+
{"name": "list_avds", "description": "List Android Virtual Device names."},
50+
{"name": "start_device", "description": "Boot an Android emulator or iOS simulator."},
51+
{"name": "shutdown_device", "description": "Shut down an iOS simulator or Android emulator."},
52+
{"name": "get_widget_tree", "description": "Dump the live Flutter widget tree from the running app."},
53+
{"name": "take_screenshot", "description": "Capture the current screen and return it as an image."},
54+
{"name": "read_test", "description": "Read the contents of a .probe test file."},
55+
{"name": "write_test", "description": "Create or overwrite a .probe file. Validates ProbeScript syntax before writing."},
56+
{"name": "run_script", "description": "Execute inline ProbeScript without creating a file."},
57+
{"name": "run_tests", "description": "Run .probe test files. Supports composite multi-device tests."},
58+
{"name": "list_files", "description": "List all .probe files in a directory."},
59+
{"name": "lint", "description": "Validate .probe files for syntax errors."},
60+
{"name": "get_report", "description": "Read the most recently modified JSON test run report."},
61+
{"name": "generate_report", "description": "Generate a standalone HTML report from a JSON results file."},
62+
{"name": "generate_test", "description": "AI-generate a .probe test from a natural language prompt."},
63+
{"name": "init_project", "description": "Scaffold a new probe.yaml and tests/ directory."},
64+
{"name": "record", "description": "Record user interactions and generate a .probe file."}
65+
]
66+
}

probe_agent/CHANGELOG.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Changelog
22

3+
## 0.9.4 - 2026-05-09
4+
5+
- Version bump to match CLI v0.9.4. No agent code changes — the .mcpb
6+
Claude Desktop Extension is a CLI/server-side packaging change.
7+
38
## 0.9.3 - 2026-05-09
49

510
- Version bump to match CLI v0.9.3. No agent code changes in this release.

probe_agent/pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ description: >-
33
On-device E2E test agent for FlutterProbe. Embeds in your Flutter app and
44
executes test commands via direct widget-tree access with sub-50ms latency.
55
6-
version: 0.9.3
6+
version: 0.9.4
77
homepage: https://flutterprobe.dev
88
repository: https://github.com/AlphaWaveSystems/flutter-probe
99
issue_tracker: https://github.com/AlphaWaveSystems/flutter-probe/issues

probe_annotation/CHANGELOG.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Changelog
22

3+
## 0.9.4 - 2026-05-09
4+
5+
- Version bump to match CLI v0.9.4. No annotation API changes.
6+
37
## 0.9.3 - 2026-05-09
48

59
- Initial release.

probe_annotation/pubspec.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ description: >-
33
Dart annotations for FlutterProbe — declare ProbeScript end-to-end tests as
44
decorators on your Flutter screen classes. Pair with flutter_probe_gen to
55
generate .probe test files at build time.
6-
version: 0.9.3
6+
version: 0.9.4
77
homepage: https://flutterprobe.dev
88
repository: https://github.com/AlphaWaveSystems/flutter-probe
99
issue_tracker: https://github.com/AlphaWaveSystems/flutter-probe/issues

0 commit comments

Comments
 (0)