Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"name": "flutter-mcp-toolkit",
"source": "./plugin",
"description": "Flutter MCP toolkit: inspect and drive debug apps (semantic snapshot, tap, hot-reload) and register custom MCP tools and resources at runtime from your Flutter app or game via mcp_toolkit — closed agent feedback loop.",
"version": "4.0.0-dev.8",
"version": "4.0.0",
"keywords": [
"flutter",
"dart",
Expand Down
17 changes: 17 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
.git/
.github/
.dart_tool/
**/.dart_tool/
build/
**/build/
coverage/
dist/
node_modules/
.DS_Store
.flutter_mcp/
**/.flutter_mcp/
test/
**/test/
docs/
**/docs/
*.log
7 changes: 7 additions & 0 deletions .github/workflows/pub_publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ on:
workflow_dispatch:

permissions:
actions: write
contents: read
id-token: write

Expand Down Expand Up @@ -40,3 +41,9 @@ jobs:
- name: Publish packages
if: github.event_name == 'push'
run: bash tool/release/publish_pub_packages.sh --execute --skip-existing

- name: Trigger MCP Registry publication
if: github.event_name == 'push'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh workflow run publish_mcp_registry.yml --ref "${GITHUB_REF_NAME}"
94 changes: 94 additions & 0 deletions .github/workflows/publish_mcp_registry.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
name: Publish MCP Registry server

on:
workflow_dispatch:

permissions:
contents: read
packages: write
id-token: write

concurrency:
group: mcp-registry-${{ github.ref_name }}
cancel-in-progress: false

jobs:
publish:
runs-on: ubuntu-latest
environment: mcp-registry-publish
steps:
- name: Checkout
uses: actions/checkout@v5
with:
persist-credentials: false

- name: Require release tag
shell: bash
run: |
set -euo pipefail
if [[ "$GITHUB_REF" != refs/tags/v* ]]; then
echo "::error::This workflow must be run from a v* release tag (got $GITHUB_REF)."
exit 1
fi

- name: Resolve release version
id: version
shell: bash
run: |
set -euo pipefail
version="${GITHUB_REF_NAME#v}"
file_version="$(tr -d '[:space:]' < VERSION)"
if [[ "$version" != "$file_version" ]]; then
echo "::error::Tag ${GITHUB_REF_NAME} does not match VERSION (${file_version})."
exit 1
fi
Comment thread
coderabbitai[bot] marked this conversation as resolved.
echo "version=$version" >> "$GITHUB_OUTPUT"

- name: Synchronize release metadata
env:
RELEASE_VERSION: ${{ steps.version.outputs.version }}
run: bash tool/release/sync_version.sh --version "$RELEASE_VERSION"

- name: Verify MCP Registry contracts
run: bash tool/contracts/check_mcp_registry.sh

- name: Stage workspace lockfile for the image build context
run: cp pubspec.lock mcp_server_dart/pubspec.lock

- name: Log in to GHCR
uses: docker/login-action@v3
with:
registry: ghcr.io
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}

- name: Build and publish OCI image
uses: docker/build-push-action@v6
with:
context: mcp_server_dart
file: Dockerfile.registry
push: true
tags: ghcr.io/arenukvern/flutter-mcp-toolkit:${{ steps.version.outputs.version }}

- name: Install pinned mcp-publisher
env:
MCP_PUBLISHER_VERSION: v1.8.1
MCP_PUBLISHER_SHA256: a06c9096dcb9727c13555b6be26c7effa707b01f06a4c561ba7a3635443cf2cc
shell: bash
run: |
set -euo pipefail
curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}/mcp-publisher_linux_amd64.tar.gz" \
-o mcp-publisher.tar.gz
echo "${MCP_PUBLISHER_SHA256} mcp-publisher.tar.gz" | sha256sum --check --strict -
tar xz mcp-publisher -f mcp-publisher.tar.gz
chmod +x mcp-publisher

- name: Validate server manifest with the Registry
run: ./mcp-publisher validate mcp_server_dart/server.json

- name: Authenticate to MCP Registry with GitHub OIDC
run: ./mcp-publisher login github-oidc

- name: Publish server metadata to MCP Registry
working-directory: mcp_server_dart
run: ../mcp-publisher publish
1 change: 1 addition & 0 deletions .github/workflows/release_pr_sync_versions.yml
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ jobs:
packages/core/README.md \
packages/server_capability_kernel/README.md \
packages/server_capability_core/README.md \
mcp_server_dart/server.json \
packages/core/lib/src/runtime_version.dart \
packages/server_capability_core/lib/src/fmt_capability.dart
git commit -m "chore: sync release version touchpoints"
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,4 @@ mcp_server_dart/flutter_inspector_mcp
# ../flutter_harness
# ../flutter_mcp_video
.steward/benchmark-summaries/*.json
mcp_server_dart/mcp-publisher
2 changes: 1 addition & 1 deletion .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
{
".": "4.0.0-dev.8"
".": "4.0.0"
}
77 changes: 50 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,15 @@ _Inspect and drive a running Flutter app from your AI assistant._
- 📖 **Docs:** [docs.page/arenukvern/mcp_flutter](https://docs.page/arenukvern/mcp_flutter/)
- 🤝 **Contribute:** [guide](docs/contributing/contribution_guide.mdx) · [contributors](docs/contributing/contributors.mdx) · [code of conduct](CODE_OF_CONDUCT.md) · [security](SECURITY.md)

`flutter-mcp-toolkit` is a Dart MCP server + Flutter package that lets AI Agents (Codex, Zed, Cursor, Intent, Claude Code, Cline, etc..) take (semantic snapshots, tap widgets, type into forms, hot-reload, and read logs from a Flutter app) or create __its own tools and resources at runtime__ using MCP Toolkit — without leaving the conversation and work with Flutter apps in closed feedback loop - see example of it described in [OpenAI Agentic Harness](https://openai.com/index/harness-engineering/).
`flutter-mcp-toolkit` is a Dart MCP server + Flutter package for AI agents (Codex, Zed, Cursor, Intent, Claude Code, Cline, and more). Agents can inspect a running Flutter app, take semantic snapshots, tap widgets, type into forms, hot-reload, and read logs. Apps can also register their own MCP tools and resources at runtime via MCP Toolkit — all without leaving the conversation. The result is a closed feedback loop between agent and app; see [OpenAI Agentic Harness](https://openai.com/index/harness-engineering/) for an example of this pattern.

![Watercolor comic infographic explaining flutter-mcp-toolkit: install fmtk, add it to a Flutter app, connect an AI agent, then inspect, tap, reload, and prove changes in a close feedback loop.](docs/assets/flutter-mcp-toolkit-infographic.png)

The picture's story: the toolkit gives an AI assistant a shared window and control loop into a running Flutter app, so it can inspect state, act like a user, hot reload, read proof, and use custom tools from your app instead of guessing.

![View Screenshots](docs/view_screenshots.gif)

> ![NOTICE]: Version 4 is currently a prerelease train. Use `4.0.0-dev.5` only if you are intentionally testing the new architecture; otherwise stay on the latest stable 3.x release until `4.0.0` is promoted.
> ![NOTICE]: Version 4 is now stable. Earlier `4.0.0-dev.*` builds were prerelease testing builds of the new architecture.

## Get started in 4 steps

Expand All @@ -56,23 +56,47 @@ flutter run --debug

That's it. Your AI agent can now inspect and drive the running app — and your app can expose **custom MCP tools at runtime** (see [Dynamic Tools Registration](#dynamic-tools-registration) below).


## 📰 News
-**2026-07-11** - v4 new Live Demos records: [v4 semantic snapshot etc.. with Grok Build CLI](https://youtu.be/P0ObCyt0k3M), [v4 with IntentCall power - WebMCP projection](https://www.youtube.com/watch?v=mX4xxVeImq0)

- **2026-07-11** - v4 new Live Demos records: [v4 semantic snapshot etc.. with Grok Build CLI](https://youtu.be/P0ObCyt0k3M), [v4 with IntentCall power - WebMCP projection](https://www.youtube.com/watch?v=mX4xxVeImq0)

- **2026-05-26** — v3.1.0: Platform-view capture routing, macOS/iOS Simulator host screenshots, web CDP tab capture (SCK → CDP → flutter_layer), and cross-platform showcase platform views.

<!-- TODO(arenukvern): add tool to write news automatically -->

## Install from marketplaces

| Platform | Command / link |
|----------|----------------|
| **Any agent (recommended)** | `flutter-mcp-toolkit init <agent>` — see [AI agent setup](docs/ai_agents/overview.mdx) |
| **Claude Code (git catalog)** | `/plugin marketplace add Arenukvern/mcp_flutter` then install `flutter-mcp-toolkit` |
| **Codex (git catalog)** | `codex plugin marketplace add Arenukvern/mcp_flutter` |
| **Cursor (local plugin)** | `flutter-mcp-toolkit init cursor` |
| **Skills only** | `npx skills add Arenukvern/mcp_flutter -a <agent> -y` (add MCP via `init` or manual JSON) |
| **MCP registries** | [Smithery](https://smithery.ai/server/@Arenukvern/mcp_flutter), [MseeP](https://mseep.ai/app/03aa0f2d-4ef7-40ae-93de-c7b87e0ac32d) |
| Platform | Command / link |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Any agent (recommended)** | `flutter-mcp-toolkit init <agent>` — see [AI agent setup](docs/ai_agents/overview.mdx) |
| **Claude Code (git catalog)** | `/plugin marketplace add Arenukvern/mcp_flutter` then install `flutter-mcp-toolkit` |
| **Codex (git catalog)** | `codex plugin marketplace add Arenukvern/mcp_flutter` |
| **Cursor (local plugin)** | `flutter-mcp-toolkit init cursor` |
| **Skills only** | `npx skills add Arenukvern/mcp_flutter -a <agent> -y` (add MCP via `init` or manual JSON) |
| **MCP registries** | [Official MCP Registry](https://registry.modelcontextprotocol.io) — server `io.github.Arenukvern/flutter-mcp-toolkit` (OCI image: `ghcr.io/arenukvern/flutter-mcp-toolkit`), [Smithery](https://smithery.ai/server/@Arenukvern/mcp_flutter), [MseeP](https://mseep.ai/app/03aa0f2d-4ef7-40ae-93de-c7b87e0ac32d) |

### Docker / MCP Registry install

The official registry serves an OCI image from GHCR. Point any MCP client at it:

```json
{
"mcpServers": {
"flutter-mcp-toolkit": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--network=host",
"ghcr.io/arenukvern/flutter-mcp-toolkit:4.0.0"
]
Comment thread
coderabbitai[bot] marked this conversation as resolved.
}
}
}
```

See [Docker guide](mcp_server_dart/DOCKER.md) for flags, version pinning, and networking notes.

Maintainers submitting to official stores: [marketplace submission runbook](docs/contributing/marketplace_submission_runbook.mdx). Full matrix: [marketplace distribution](docs/ai_agents/marketplace_distribution.mdx).

Expand All @@ -92,27 +116,27 @@ Maintainers submitting to official stores: [marketplace submission runbook](docs

## Published packages

| Package | Pub.dev | Role |
|---|---|---|
| `mcp_toolkit` | [![pub package](https://img.shields.io/pub/v/mcp_toolkit.svg?include_prereleases)](https://pub.dev/packages/mcp_toolkit) [![pub points](https://img.shields.io/pub/points/mcp_toolkit.svg)](https://pub.dev/packages/mcp_toolkit/score) | Flutter app package for runtime MCP tools/resources and toolkit bootstrap. |
| `flutter_mcp_toolkit_core` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_core.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_core) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_core.svg)](https://pub.dev/packages/flutter_mcp_toolkit_core/score) | Pure-Dart shared command/result/capability types. |
| `flutter_mcp_toolkit_capability_kernel` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_capability_kernel.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_capability_kernel) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_capability_kernel.svg)](https://pub.dev/packages/flutter_mcp_toolkit_capability_kernel/score) | Capability kernel contracts for composable MCP units. |
| `flutter_mcp_toolkit_capability_core` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_capability_core.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_capability_core) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_capability_core.svg)](https://pub.dev/packages/flutter_mcp_toolkit_capability_core/score) | Server-side `fmt_*` capability implementation. |
| Package | Pub.dev | Role |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `mcp_toolkit` | [![pub package](https://img.shields.io/pub/v/mcp_toolkit.svg?include_prereleases)](https://pub.dev/packages/mcp_toolkit) [![pub points](https://img.shields.io/pub/points/mcp_toolkit.svg)](https://pub.dev/packages/mcp_toolkit/score) | Flutter app package for runtime MCP tools/resources and toolkit bootstrap. |
| `flutter_mcp_toolkit_core` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_core.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_core) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_core.svg)](https://pub.dev/packages/flutter_mcp_toolkit_core/score) | Pure-Dart shared command/result/capability types. |
| `flutter_mcp_toolkit_capability_kernel` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_capability_kernel.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_capability_kernel) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_capability_kernel.svg)](https://pub.dev/packages/flutter_mcp_toolkit_capability_kernel/score) | Capability kernel contracts for composable MCP units. |
| `flutter_mcp_toolkit_capability_core` | [![pub package](https://img.shields.io/pub/v/flutter_mcp_toolkit_capability_core.svg?include_prereleases)](https://pub.dev/packages/flutter_mcp_toolkit_capability_core) [![pub points](https://img.shields.io/pub/points/flutter_mcp_toolkit_capability_core.svg)](https://pub.dev/packages/flutter_mcp_toolkit_capability_core/score) | Server-side `fmt_*` capability implementation. |

The server binary lives in `mcp_server_dart` and is shipped through GitHub
Release artifacts as `flutter-mcp-toolkit`, `fmtk`, and
`flutter-mcp-toolkit-server`; it is not a pub.dev package.

## Development support

| Need | Start here |
|---|---|
| Contribute code or docs | [CONTRIBUTING.md](CONTRIBUTING.md) · [Contribution guide](docs/contributing/contribution_guide.mdx) |
| Add or credit contributors | [Contributors guide](docs/contributing/contributors.mdx) · [`.all-contributorsrc`](.all-contributorsrc) |
| Report vulnerabilities | [SECURITY.md](SECURITY.md) |
| Validate local changes | `steward probe --json --profile quick` · `make check-contracts` |
| Maintain releases | [Release train notes](CONTRIBUTING.md#maintainers) · [`flutter-mcp-toolkit-repo-maintainer`](plugin/skills/flutter-mcp-toolkit-repo-maintainer/SKILL.md) |
| Install or update agent skills | [AI agent setup](docs/ai_agents/overview.mdx) · [Marketplace distribution](docs/ai_agents/marketplace_distribution.mdx) |
| Need | Start here |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Contribute code or docs | [CONTRIBUTING.md](CONTRIBUTING.md) · [Contribution guide](docs/contributing/contribution_guide.mdx) |
| Add or credit contributors | [Contributors guide](docs/contributing/contributors.mdx) · [`.all-contributorsrc`](.all-contributorsrc) |
| Report vulnerabilities | [SECURITY.md](SECURITY.md) |
| Validate local changes | `steward probe --json --profile quick` · `make check-contracts` |
| Maintain releases | [Release train notes](CONTRIBUTING.md#maintainers) · [`flutter-mcp-toolkit-repo-maintainer`](plugin/skills/flutter-mcp-toolkit-repo-maintainer/SKILL.md) |
| Install or update agent skills | [AI agent setup](docs/ai_agents/overview.mdx) · [Marketplace distribution](docs/ai_agents/marketplace_distribution.mdx) |

## What it does

Expand All @@ -134,7 +158,6 @@ works in this [short YouTube video](https://www.youtube.com/watch?v=Qog3x2VcO98)
The same `arguments.connection` targeting is supported by the CLI's `exec`,
`batch`, daemon `command/execute`, daemon `watch/start`, and snapshot step args.


> [!NOTE]
> There is official [MCP Server for Flutter from Flutter team](https://github.com/dart-lang/ai/tree/main/pkgs/dart_mcp_server) which exposes Dart tooling.
> The **main goal of this project** is to bring power of MCP server tools by creating them in Flutter app, using **dynamic MCP tools registration** and close feedback loop for AI Agent. See how it works in [short YouTube video](https://www.youtube.com/watch?v=Qog3x2VcO98). See [Quick Start](https://docs.page/arenukvern/mcp_flutter) for more details. See [original motivation](https://github.com/Arenukvern/mcp_flutter/blob/main/CHANGELOG.md#210) behind the idea.
Expand Down
Loading
Loading