# Contributing to CKAN MCP
Thanks for your interest in improving the CKAN Open Data MCP server! This guide explains how to set up your environment, propose changes, and ensure contributions ship smoothly.
## Getting Started
1. **Fork & Clone**
```bash
git clone https://github.com/<your-user>/ckan-mcp.git
cd ckan-mcp
```
2. **Create a virtual environment**
```bash
uv venv venv
source venv/bin/activate
```
3. **Install dependencies**
```bash
uv pip install -e ".[dev]"
```
## Development Workflow
- Create a feature branch per change.
- Keep commits focused with imperative messages (e.g., “Add dataset analyzer”).
- Document user-facing changes in `README.md`, `EVALUATION_GUIDE.md`, or examples as appropriate.
- Add or update unit tests under `tests/` that mirror the module layout.
## Quality Gates
Run the full suite before opening a pull request:
```bash
black src/ tests/
ruff check src/ tests/ --fix
mypy src/
pytest tests/ -v
python test_runner.py # optional smoke tests
```
If you touched the MCP entry point or deployment surface, also run:
```bash
python -m ckan_mcp.main # stdio mode
CKAN_MCP_MODE=http python -m ckan_mcp.main # HTTP mode
```
## Code Style & Guidelines
- Python 3.11+, Black-formatted (line length 100), type-hinted.
- Keep helper docstrings concise; add targeted comments only when behavior is non-obvious.
- Avoid hard-coding credentials—rely on env vars like `CKAN_BASE_URL`, `CKAN_SITE_URL`, etc.
- Place fixtures and sample payloads under `examples/`.
## Communications & Conduct
- Be respectful and collaborative—see `CODE_OF_CONDUCT.md`.
- Open an issue before large features to align on requirements.
- Security issues should be reported privately (see `SECURITY.md`).
## Releasing
Maintainers update `pyproject.toml` versions, tag releases, and publish to PyPI/containers once CI is green and documentation is up to date.
