# Contribution Guide

We welcome contributions to the Flutter MCP Toolkit! Please feel free to submit pull requests or report issues on the [GitHub repository](https://github.com/Arenukvern/mcp_flutter).

### Development Setup

1.  Clone the repository.
2.  Inspect the declared agent/maintainer contract:

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

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

    ```bash
    cd mcp_toolkit
    dart pub get

    cd ../mcp_server_dart
    dart pub get

    cd showcase/flutter_test_app
    dart pub get
    ```

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

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

### Editing skills

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

```bash
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/`](/skills) symlinks to `plugin/skills/` so [`npx skills`](https://www.npmjs.com/package/skills) discovers bundles without a recursive search. End-user install docs live in [AI agent overview](/ai_agents/overview); team lockfile template: [`.skills.json.example`](https://github.com/Arenukvern/mcp_flutter/blob/main/.skills.json.example).

Marketplace listing copy: [marketplace_copy.yaml](/ai_agents/marketplace_copy.yaml). Submitting to Claude/Cursor/Codex stores: [marketplace submission runbook](/contributing/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`](https://github.com/Arenukvern/skill_steward/tree/main/skills/release-changelog-harness) — `npx skills add arenukvern/skill_steward --skill release-changelog-harness`
- [binary-release-contract.md](https://github.com/Arenukvern/skill_steward/blob/main/skills/release-changelog-harness/references/binary-release-contract.md)
- [ADR 0010](https://github.com/Arenukvern/skill_steward/blob/main/docs/decisions/0010-binary-releases-for-product-harness-not-meta-steward.md) (Skill Steward defers binaries; mcp_flutter is the reference impl)

Root [CONTRIBUTING.md](https://github.com/Arenukvern/mcp_flutter/blob/main/CONTRIBUTING.md) summarizes the binary train and **install.sh checksum flow** for maintainers.

### Commit messages

Use [Conventional Commits](https://www.conventionalcommits.org/) so
[release-please](https://github.com/googleapis/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`](https://github.com/Arenukvern/mcp_flutter/blob/main/VERSION). [`.github/workflows/release_pr_sync_versions.yml`](https://github.com/Arenukvern/mcp_flutter/blob/main/.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`](https://github.com/Arenukvern/mcp_flutter/blob/main/.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`](https://github.com/Arenukvern/mcp_flutter/blob/main/tool/release/build_release_artifacts.sh)).
6. [`.github/workflows/pub_publish.yml`](https://github.com/Arenukvern/mcp_flutter/blob/main/.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`](https://github.com/Arenukvern/mcp_flutter/blob/main/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](https://github.com/Arenukvern/mcp_flutter/blob/main/CONTRIBUTING.md#maintainers) for the step-by-step checksum flow.

Pending work belongs under `## [Unreleased]` in [CHANGELOG.md](https://github.com/Arenukvern/mcp_flutter/blob/main/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`](https://github.com/Arenukvern/mcp_flutter/blob/main/release-please-config.json), [`.release-please-manifest.json`](https://github.com/Arenukvern/mcp_flutter/blob/main/.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`](https://github.com/Arenukvern/mcp_flutter/blob/main/.github/workflows/release_pr_sync_versions.yml) auto-commits version touchpoint drift, and [`.github/workflows/release_pr_sync_skills.yml`](https://github.com/Arenukvern/mcp_flutter/blob/main/.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.
- Security-impacting changes link to [SECURITY.md](https://github.com/Arenukvern/mcp_flutter/blob/main/SECURITY.md).

### Contributor credit

Contributor credit is managed with
[all-contributors](https://allcontributors.org/). The source of truth is
[`/.all-contributorsrc`](https://github.com/Arenukvern/mcp_flutter/blob/main/.all-contributorsrc),
and the generated table is rendered in the README.

To add a contributor from a PR:

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