Contribution Guide

We welcome contributions to the Flutter MCP Toolkit! Please feel free to submit pull requests or report issues on the GitHub repository.

Development Setup

1. Clone the repository.

2. Install the dependencies for both the server and the toolkit:

   # Toolkit core package
   cd mcp_toolkit
   dart pub get
   
   # Server package
   cd ../../mcp_server_dart
   dart pub get
   
   # test app (if needed)
   cd ../../flutter_test_app
   dart pub get
   

3. Run the tests:

   dart test
   

Editing skills

Skill bodies are the canonical source of AI-agent guidance, located in plugin/skills/<skill-id>/SKILL.md. After editing any skill:

make sync-skills   # regenerates mcp_server_dart/lib/src/skill_assets.g.dart

CI fails if the generated file is out of sync with plugin/. Commit both the SKILL.md change and the regenerated skill_assets.g.dart.

Repo root skills/ symlinks to plugin/skills/ so npx skills discovers bundles without a recursive search. End-user install docs live in AI agent overview; team lockfile template: .skills.json.example.

Marketplace listing copy: marketplace_copy.yaml. Submitting to Claude/Cursor/Codex stores: marketplace submission runbook.

Maintainers

Use bundled skill flutter-mcp-toolkit-repo-maintainer (local: .cursor/skills/flutter-mcp-toolkit-repo-maintainer) for releases, contracts, and docs.

Cross-repo release contract (Skill Steward): product harness repos ship executables on GitHub Releases with changelog in git. Normative reference:

• release-changelog-harness — npx skills add arenukvern/skill_steward --skill release-changelog-harness
• binary-release-contract.md
• ADR 0010 (Skill Steward defers binaries; mcp_flutter is the reference impl)

Root CONTRIBUTING.md summarizes the binary train and install.sh checksum flow for maintainers.

Commit messages

Use Conventional Commits so release-please can build the changelog and version bumps:

• feat: — new capability (minor bump)
• fix: — bug fix (patch bump)
• docs: — documentation (patch bump when it is the only change in a release)
• perf: — performance improvement
• chore: / refactor: / test: — usually hidden in the generated changelog

Example: feat: add fmt_wait_for_stable_snapshot tool.

Releases

Releases are automated on main via release-please:

1. Merge PRs to main with conventional commit titles.
2. release-please opens or updates a Release PR (e.g. chore: release 3.0.1) with CHANGELOG.md and VERSION. .github/workflows/release_pr_sync_versions.yml derives pubspecs, same-train dependency constraints, plugin pins, runtime version updates, and .release-please-manifest.json from that one version.
3. Review the Release PR, then merge it.
4. release-please creates the vX.Y.Z tag and GitHub release with changelog notes.
5. .github/workflows/release.yml runs on the tag, asserts tag == VERSION, and attaches flutter_mcp_* tarballs + checksums.txt (SHA-256 per tarball, same format as tool/release/build_release_artifacts.sh).
6. .github/workflows/pub_publish.yml publishes pub.dev packages in dependency order: flutter_mcp_toolkit_core, flutter_mcp_toolkit_capability_kernel, flutter_mcp_toolkit_capability_core, then mcp_toolkit.

Consumer install (no clone): install.sh downloads the tarball and checksums.txt from the release URL, verifies SHA-256, then installs to $HOME/.local/bin. See CONTRIBUTING.md — Maintainers for the step-by-step checksum flow.

Pending work belongs under ## [Unreleased] in CHANGELOG.md. release-please promotes that section when the Release PR merges.

CHANGELOG markdown: version headings use [3.0.1] brackets (Keep a Changelog); the file disables MD052 at the top. In bullets, wrap code symbols in backticks — never [Type.member] without a URL.

Config: release-please-config.json, .release-please-manifest.json.

Run make sync-version after changing VERSION, then make check-contracts locally — it includes check_version_sync.sh (version pins) and check_skill_assets_drift.sh (regenerated skill_assets.g.dart matches plugin/).

On Release PRs, .github/workflows/release_pr_sync_versions.yml auto-commits version touchpoint drift, and .github/workflows/release_pr_sync_skills.yml auto-commits skill_assets.g.dart when drift is detected. The skill-assets-drift and version sync checks must still pass before merge. If automation did not run, run make sync-version && make sync-skills locally and push.

Before automated pub.dev publishing can run, each package must have automated publishing enabled in its pub.dev Admin page for repository Arenukvern/mcp_flutter, tag pattern v{{version}}, and GitHub environment pub.dev.

Pull Requests

Before submitting a pull request, please make sure that:

• The code is well-formatted and follows the project's style guide.
• The tests pass.
• The documentation is updated, if necessary.