# 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.  Install the dependencies for both the server and the toolkit:

    ```bash
    # 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:

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

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

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](/ai_agents/marketplace_copy.yaml). Submitting to Claude/Cursor/Codex stores: [marketplace submission runbook](/contributing/marketplace_submission_runbook).

### 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`, [`VERSION`](https://github.com/Arenukvern/mcp_flutter/blob/main/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`](https://github.com/Arenukvern/mcp_flutter/blob/main/.github/workflows/release.yml) runs on the tag and attaches `flutter_mcp_*` tarballs + `checksums.txt`.

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 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`](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** 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.
