# Contributing to TomTom Maps MCP Server

Thank you for your interest in contributing to the TomTom Maps MCP Server! We welcome contributions from the community to help improve and grow this project.

## Code of Conduct

Please note that this project adheres to the [TomTom Code of Conduct](https://tomtominternational.sharepoint.com/:b:/r/sites/intouch2/MyServices/codeofconduct/Documents/20190918_TT_CodeOfConduct_v6-hyperlinks.pdf?csf=1&web=1&e=j2aec3). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

## How to Contribute

### Reporting Issues

If you find a bug or have a suggestion for improving the project:

1. Check if the issue already exists in the [Issues](https://github.com/tomtom-international/tomtom-maps-mcp/issues) section.
2. If not, create a new issue with a clear description, including:
   - Steps to reproduce the problem
   - Expected behavior
   - Actual behavior
   - Environment details (OS, Node.js version, etc.)

### Contributing Code

1. Fork the repository
2. Create a new branch for your feature or bugfix
3. Make your changes, including appropriate test cases
4. Ensure all tests pass by running `pnpm test`, and the checks CI also runs: `pnpm test:soak`, `pnpm test:e2e:protocol` after `pnpm build`, and the spec host suites (see [Adding_new_tools.md](Adding_new_tools.md), *Before opening a PR*)
5. Make sure your code follows the project's coding standards
6. Sign-off your commits according to the Developer Certificate of Origin (DCO)
7. Submit a pull request with a clear description of the changes

### Pull Request Process

1. Update the README.md or documentation with details of changes if appropriate
   - The MCP pages of the docs portal, [docs.tomtom.com](https://docs.tomtom.com/tomtom-maps-mcp/documentation/overview),
     live in an internal TomTom repository. If your change affects them, a maintainer opens the
     matching docs PR there ([`CODING_GUIDELINES.md`](CODING_GUIDELINES.md) § 10)
2. The `Agent review` check must pass. It fails until the `tomtom-mcp-review` skill has posted a
   review on the PR. Dependabot pull requests are exempt. Resolve the conversations that review
   opens before merge.
3. The `Changelog entry` check must pass. A PR titled `feat`, `fix` or with a `!` fails it until it
   adds or rewords an entry under `## [Unreleased]` in `CHANGELOG.md`. Label a fix that users cannot
   see `no-changelog`.
4. The PR will be reviewed by at least two TomTom maintainers
5. You may be asked to make additional changes before your PR is accepted
6. Once approved, a maintainer will merge your PR

## Developer Certificate of Origin (DCO)

All contributions must be signed-off according to the Developer Certificate of Origin (DCO). This attests that you have the right to contribute the code you are submitting.

To sign-off your commits, add the `--signoff` option to your git commit command:

```bash
git commit --signoff -m "Your detailed commit message"
```

Or use the shorthand:

```bash
git commit -s -m "Your detailed commit message"
```

## Coding Standards

- Follow [`CODING_GUIDELINES.md`](CODING_GUIDELINES.md), which is normative for every change
- Maintain 100% test coverage for new code
- Document public APIs using JSDoc comments
- Follow existing code style and formatting
- New tools and tool inputs go through the maps-sdk and must reach the API request; see
  [Adding_new_tools.md](Adding_new_tools.md) for the steps and the checks that enforce it.
- The agent skills live in `.agents/skills/`; `.claude/skills/` holds symlinks to them. On
  Windows, enable Developer Mode and clone with `git clone -c core.symlinks=true`, or Claude Code
  finds text files where the skills should be.
- In Claude Code and Cursor, an agent's `git commit` is denied until the `tomtom-mcp-preflight`
  skill has passed once in the session (`.claude/settings.json`, `.cursor/hooks.json`). The
  denial names the command that records the pass; your own terminal is never gated. The gate
  needs Claude Code 2.1.147 or later, the first whose `PowerShell(...)` hook conditions match.
- Run `pnpm lint` and `pnpm format:changed` before pushing; both are enforced in CI.
  Formatting is only enforced on the files your change touches (`--changed`, compared
  against `main`): the codebase predates any enforced formatter run, so a repo-wide
  `pnpm format` still reports pre-existing drift. Fix it with
  `pnpm exec biome format --write --changed src`, not `pnpm format:fix`, which rewrites all
  of `src`: avoid reformatting untouched files in a feature PR — a dedicated
  formatting-only PR is the place for that.
- Biome's formatter is intentionally disabled for `*.css` (see the override in `biome.json`).
  The previous Prettier setup only ever formatted `src/**/*.{ts,tsx,js,jsx,json}`, so the app
  stylesheets have never been machine-formatted. Enabling it would reindent every stylesheet
  for no functional gain, so keep CSS formatting manual.

## License

By contributing to this project, you agree that your contributions will be licensed under the project's [Apache License 2.0](LICENSE.md).

Thank you for contributing to the TomTom Maps MCP Server!