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.

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

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

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, VERSION, pubspecs, plugin pins, and runtime version updates.
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 and attaches flutter_mcp_* tarballs + checksums.txt.

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 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_skills.yml auto-commits skill_assets.g.dart when drift is detected; the skill-assets-drift check must still pass before merge. If automation did not run, run make sync-skills locally and push.

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.