Skip to content

Contributing

Thanks for wanting to improve netbox-agent-mcp. This is a short working guide — see docs/DEVELOPMENT.md for architecture and extension procedures.

Prerequisites

  • Python 3.11–3.14
  • uv for dependency management — do not use pip.

Setup

git clone https://github.com/magicboxlab-ai/netbox-agent-mcp.git
cd netbox-agent-mcp
uv sync                              # installs runtime + dev deps
uv run pre-commit install            # enables gitleaks + ruff on every commit

Workflow

uv run pytest                        # unit tests (default)
uv run pytest tests/unit/services/test_query_service.py::test_name -v
uv run ruff check .                  # lint
uv run ruff format .                 # auto-format

CI runs ruff + pytest on Python 3.11 / 3.12 / 3.13, plus gitleaks for secret scanning. All three must pass before a PR can merge.

Integration and contract tests need a live NetBox:

scripts/netbox_docker_up.sh          # spins up netbox-docker locally
export NETBOX_URL=http://localhost:8000/
export NETBOX_TOKEN=<token>
uv run pytest -m integration
uv run pytest -m contract            # schema-drift detector

Conventions

  • Read-only by design. No create/update/delete tools. Proposals that add write surface are out of scope.
  • Tool docstrings are the LLM-facing contract. Any tool under tools/ — invest in the docstring: args, response shape, when to use vs a similar tool, worked example. If you change a response shape, update docs/SYSTEM_PROMPT.md in the same PR.
  • Specific exceptions from exceptions.py. No bare except or raw ValueError.
  • Type hints required on all function signatures.
  • Filter grammar rejects multi-hop filters (device__site_id). Do two-step lookups instead.

Adding an object type / tool / response signal

Procedures are in docs/DEVELOPMENT.md under "Extending".

Commit messages

Write in the imperative, present tense, lowercase-first-word after the type prefix:

chore: prepare for GitHub release
fix: drop stale pagination cursor when total_count == 0
refactor: consolidate __in filter helper

No AI-authored / co-author attribution lines, no emoji.

Reporting bugs

Open an issue with the bug report template. Include NetBox version, server version, and minimal reproduction.

Security vulnerabilities

Do not open a public issue. See SECURITY.md for private reporting.