# Contributing to DBT Core MCP
Thank you for your interest in contributing to the DBT Core MCP Server!
## Development Setup
1. **Install uv:**
```bash
# Windows (PowerShell)
# See installation options: https://docs.astral.sh/uv/getting-started/installation/
pip install uv # or use the standalone installer
```
2. **Clone the repository:**
```bash
git clone https://github.com/NiclasOlofsson/dbt-core-mcp.git
cd dbt-core-mcp
```
3. **Run tests:**
```bash
uv sync --group dev
uv run pytest
```
## Development Workflow
### Environment Management
uv manages a project-local virtual environment for you:
- Run `uv sync` to create/sync the `.venv` with all dependencies.
- Use `uv run <command>` to execute tools inside that environment without manually activating it.
- Optional: activate `.venv` manually if you prefer a shell (`source .venv/bin/activate` on bash, `.venv\Scripts\Activate.ps1` on PowerShell).
### Running Tests
```bash
# Run all tests
uv sync --group dev
uv run pytest
# Run tests with coverage (pytest - add coverage plugin if needed)
uv run pytest --cov
# Run against multiple Python versions (use matrix in CI or uv python pin locally)
# e.g., uv run --python 3.10 pytest
```
### Code Quality
```bash
# Lint code with Ruff
uv run ruff check src tests
# Format code with Ruff
uv run ruff format src tests
# Check formatting without applying
uv run ruff format --check src tests
# Run type checking
uv run pyright src tests
```
**Note:** Type checking currently reports some annotation issues that need to be addressed in future contributions.
### Building the Project
```bash
# Build wheel and source distribution
uv build
# Build only wheel
uv build --only wheel
# Build only source distribution
uv build --only sdist
```
### Working with Dependencies
```bash
# Install project dependencies
uv sync --group dev
# Enter a shell in the venv (optional)
source .venv/bin/activate # bash
# On Windows PowerShell: .venv\Scripts\Activate.ps1
```
### Available Scripts
The project defines several convenient validation commands:
- `uv run pytest` - Run pytest
- `uv run ruff check src tests` - Lint code with Ruff
- `uv run ruff format src tests` - Format code with Ruff
- `uv run ruff format --check src tests` - Check code formatting
- `uv run pyright src tests` - Run pyright type checking
### Running Individual Commands
```bash
# Run any Python command in the environment
uv run python -m dbt_core_mcp
# Run the server directly for testing
uv run python -m dbt_core_mcp --help
# Enter a shell in the development environment
source .venv/bin/activate # or use uv run for commands
```
## Development Environment
uv creates and manages a virtual environment (`.venv`) in your project directory when you run `uv sync`. This environment:
- Is used automatically when you run commands via `uv run`
- Contains all project dependencies and development tools
- Can be recreated by re-running `uv sync` if dependencies change
- Can be entered manually if preferred (see Environment Management above)
## Quick Reference
| Command | Description |
|---------|-------------|
| `uv run pytest` | Run all tests with pytest |
| `uv run ruff check src tests` | Lint code with Ruff |
| `uv run ruff format src tests` | Auto-format code with Ruff |
| `uv run ruff format --check src tests` | Check code formatting |
| `uv run pyright src tests` | Run pyright type checking |
| `uv build` | Build wheel and source distribution |
| `uv run` | Run commands in the project environment |
| `uv sync` | Sync dependencies (creates .venv) |
| `uv cache clean` | Clean cache (useful if needed) |
## Code Style
- Follow PEP 8 conventions
- Use type hints where appropriate
- Include docstrings for all public functions and classes
- Keep functions focused and small
## Testing
- Add tests for new functionality
- Ensure all existing tests pass
- Test both success and error cases
## Submitting Changes
1. **Fork the repository**
2. **Create a feature branch:**
```bash
git checkout -b feature/your-feature-name
```
3. **Make your changes**
4. **Run tests**
5. **Commit with clear messages:**
```bash
git commit -m "Add feature: description of changes"
```
6. **Push and create a pull request**
## Areas for Contribution
- **Bug fixes** - Check the issue tracker
- **Documentation** -dbt integration features
- **Testing** - Improve test coverage
- **Performance** - Optimize dbt operations
## Release Process
This project uses [bump-my-version](https://github.com/callowayproject/bump-my-version) for version management and automated PyPI releases.
### Creating a Release
1. **Ensure all changes are committed and pushed:**
```bash
git status # should be clean
git push
```
2. **Draft release notes with AI (from git log):**
- Ask the AI to review the git log between the previous tag and `HEAD`.
- The AI should produce a short Markdown summary grouped into **only**:
- **Features** (code changes from `feat` commits)
- **Fixes** (code changes from `fix` commits)
- **Exclude** non-code items (docs, tests, chores, refactors without behavior change).
- Example output:
- **Features**
- Add tool metadata helpers and discovery system.
- Add server lifespan context manager for graceful shutdown.
- **Fixes**
- [List only code fixes; omit docs/tests/chores]
- Save this summary to a temporary file **outside the repo** or in a **gitignored** location (e.g., `temp_auto/`).
- This ensures bump-my-version creates an **annotated tag** with your release notes.
3. **Bump the version (with annotated tag message):**
```bash
# For bug fixes (0.2.5 → 0.2.6)
uv run bump-my-version bump patch --tag-message "$(cat release_notes.txt)"
# For new features (0.2.5 → 0.3.0)
uv run bump-my-version bump minor --tag-message "$(cat release_notes.txt)"
# For breaking changes (0.2.5 → 1.0.0)
uv run bump-my-version bump major --tag-message "$(cat release_notes.txt)"
# Or set a specific version
uv run bump-my-version bump --new-version 1.0.0 --tag-message "$(cat release_notes.txt)"
```
4. **Push the version bump and tag:**
```bash
git push --follow-tags
```
5. **GitHub Actions will automatically:**
- Run quality checks (format, typecheck, tests)
- Build the package
- Create a GitHub Release with auto-generated release notes
- Publish to PyPI
> **Note:** The entire release process is automated via GitHub Actions. Once you push the tag, the CI pipeline handles building, testing, creating the GitHub release, and publishing to PyPI. The release notes should come from your annotated tag message.
### Version Scheme
We follow [Semantic Versioning](https://semver.org/):
- **MAJOR** - Breaking changes
- **MINOR** - New features (backward compatible)
- **PATCH** - Bug fixes
### What Not to Do
- ❌ Don't manually edit version in `pyproject.toml`
- ❌ Don't create tags manually
- ❌ Don't trigger the release workflow manually (it runs automatically on tag push)
## Code of Conduct
Be respectful, inclusive, and constructive in all interactions.
## Questions?
Feel free to open an issue for questions or discussions!
