Skip to content

Contributing

Contributions are welcome! Every little bit helps, and credit will always be given.

Environment setup

Fork and clone the repository, then:

cd unblu-mcp
uv sync

This installs all dependencies including dev tools. If uv is not installed, see the uv installation guide.

Run the CLI with uv run unblu-mcp [ARGS...].

Tasks

This project uses poethepoet as a task runner. Run poe to list all available tasks. Key tasks:

  • poe check — lint + type check (parallel)
  • poe fix — auto-fix lint issues and format
  • poe test — run tests (excluding slow)
  • poe docs — serve documentation locally

Development

  1. Create a branch: git switch -c feature-or-bugfix-name
  2. Make your changes
  3. Commit — git hooks automatically run formatting, linting, and tests

Don't worry about the changelog — it is generated automatically from commit messages.

Commit messages

This project uses Conventional Commits. A git hook enforces the format, so you'll get immediate feedback if the message doesn't match:

<type>[(scope)]: Subject


[Body]

Subject and body must be valid Markdown. Subject must have proper casing (uppercase for first letter if it makes sense), but no dot at the end, and no punctuation in general.

Scope and body are optional. Type can be:

  • build: About packaging, building wheels, etc.
  • chore: About packaging or repo/files management.
  • ci: About Continuous Integration.
  • deps: Dependencies update.
  • docs: About documentation.
  • feat: New feature.
  • fix: Bug fix.
  • perf: About performance.
  • refactor: Changes that are not features or bug fixes.
  • style: A change in code style/format.
  • tests: About tests.

If you write a body, please add trailers at the end (for example issues and PR references, or co-authors), without relying on GitHub's flavored Markdown:

Body.

Issue #10: https://github.com/namespace/project/issues/10
Related to PR namespace/other-project#15: https://github.com/namespace/other-project/pull/15

Common types: feat, fix, docs, refactor, test, ci, chore, perf.

Pull requests

Link to any related issue in the PR description. Keep commits focused — one logical change per commit. We squash-merge PRs, so don't worry about a clean commit history within the PR.