Contribution Guide

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

1. Clone the repository.

Inspect the declared agent/maintainer contract:

steward doctor --json
steward actions list --json
steward action inspect fmt.check.tool-prefix --json
steward probe --json --profile quick

Install the dependencies for the app package, server, and test app:

cd mcp_toolkit
dart pub get

cd ../mcp_server_dart
dart pub get

cd ../flutter_test_app
dart pub get

Run the focused tests for the package you changed, then run the repo gate before opening a PR:

steward probe --json --profile quick
make check-contracts

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.

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.

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 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.

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.
• Security-impacting changes link to SECURITY.md.

Contributor credit is managed with all-contributors. The source of truth is /.all-contributorsrc, and the generated table is rendered in the README.

To add a contributor from a PR:

npx all-contributors-cli add <github-login> code,doc
npx all-contributors-cli generate

Commit the updated .all-contributorsrc and README.md together. Use the smallest accurate contribution type set; non-code work such as docs, bug reports, security review, user testing, tutorials, research, infrastructure, and maintenance is welcome.