Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
56 lines (39 loc) · 2.35 KB

CONTRIBUTING.md

File metadata and controls

56 lines (39 loc) · 2.35 KB

Contributing

Thanks for considering a contribution to teslamate-mcp. This guide should get you from a fresh clone to a passing PR in a few minutes.

Setup

git clone https://github.com/cobanov/teslamate-mcp.git
cd teslamate-mcp
cp env.example .env   # set at least DATABASE_URL
uv sync               # installs runtime + dev dependencies

Day-to-day commands

uv run teslamate-mcp list-tools         # confirm the package imports
uv run teslamate-mcp stdio              # run the stdio server
uv run teslamate-mcp http               # run the HTTP server
uv run ruff check src tests             # lint
uv run ruff format src tests            # format
uv run pytest                           # full test suite (Docker-backed integration tests skip if Docker is absent)

CI runs the same ruff check, ruff format --check, and pytest commands on every push and pull request, so running them locally before pushing means fewer back-and-forth round trips.

Adding a predefined query

  1. Drop a single-statement SELECT into src/teslamate_mcp/queries/ — for example my_query.sql.

  2. Add a sibling my_query.toml with the tool's MCP-facing identity:

    name = "get_my_data"
description = "One short sentence describing what the tool returns."

  3. Restart the server. The registry picks the file up automatically, and teslamate-mcp list-tools should show the new entry.

Coding conventions

  • Python 3.11+, type-annotated.
  • Ruff handles both lint and format; please make sure both pass before pushing.
  • Prefer composition over inheritance, and avoid speculative abstractions — a bug fix should not pull in unrelated refactors.
  • Comments should explain non-obvious why, not what.

Commit and PR style

  • Keep commits focused: one logical change per commit, with a subject line that fits on one screen.
  • Reference issues in the body when applicable.
  • Open the PR against main. Describe what changed, why, and any user-visible impact.

Reporting bugs and requesting features

Use the GitHub issue tracker. A useful bug report includes the version (teslamate-mcp --version), the command you ran, what you expected, and what actually happened — with logs whenever possible.

For security issues, see SECURITY.md instead — please do not file public issues for vulnerabilities.