Merge pull request #51 from netboxlabs/feat/src-layout-and-semantic-release

feat!: restructure to src/ layout and add semantic release

Author: abubnalitic-nbl

.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Python Semantic Release
+        uses: python-semantic-release/python-semantic-release@v10
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Test
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      netbox:
+        image: netboxcommunity/netbox:latest
+        env:
+          SKIP_SUPERUSER: true
+        ports:
+          - 8000:8080
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest -v
+        env:
+          NETBOX_URL: http://localhost:8000
+          NETBOX_TOKEN: ${{ secrets.NETBOX_TOKEN }}

.gitignore

@@ -85,4 +85,8 @@ logs/
 *.bak
 *.swp
 *.swo
+
+# Git worktrees
+.worktrees/
+
 .plans/*

Dockerfile

@@ -33,4 +33,4 @@ ENV PATH="/app/.venv/bin:$PATH"
 
 EXPOSE 8000
 
-CMD ["python", "-u", "server.py"]
+CMD ["netbox-mcp-server"]

README.md

@@ -1,5 +1,12 @@
 # NetBox MCP Server
 
+> **⚠️ Breaking Change in v1.0.0**: The project structure has changed.
+> If upgrading from v0.1.0, update your configuration:
+> - Change `uv run server.py` to `uv run netbox-mcp-server`
+> - Update Claude Desktop/Code configs to use `netbox-mcp-server` instead of `server.py`
+> - Docker users: rebuild images with updated CMD
+> - See [CHANGELOG.md](CHANGELOG.md) for full details
+
 This is a simple read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for NetBox.  It enables you to interact with your data in NetBox directly via LLMs that support MCP.
 
 ## Tools
@@ -26,7 +33,7 @@ This is a simple read-only [Model Context Protocol](https://modelcontextprotocol
     pip install -e .
     ```
 
-3. Verify the server can run: `NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run server.py`
+3. Verify the server can run: `NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<your-api-token> uv run netbox-mcp-server`
 
 4. Add the MCP server to your LLM client. See below for some examples with Claude.
 
@@ -40,7 +47,7 @@ Add the server using the `claude mcp add` command:
 claude mcp add --transport stdio netbox \
   --env NETBOX_URL=https://netbox.example.com/ \
   --env NETBOX_TOKEN=<your-api-token> \
-  -- uv --directory /path/to/netbox-mcp-server run server.py
+  -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server
 ```
 
 **Important notes:**
@@ -61,7 +68,7 @@ For HTTP transport, first start the server manually:
 NETBOX_URL=https://netbox.example.com/ \
 NETBOX_TOKEN=<your-api-token> \
 TRANSPORT=http \
-uv run server.py
+uv run netbox-mcp-server
 ```
 
 Then add the running server to Claude Code:
@@ -91,7 +98,7 @@ Add the server configuration to your Claude Desktop config file. On Mac, edit `~
                 "--directory",
                 "/path/to/netbox-mcp-server",
                 "run",
-                "server.py"
+                "netbox-mcp-server"
             ],
             "env": {
                 "NETBOX_URL": "https://netbox.example.com/",
@@ -176,7 +183,7 @@ For local Claude Desktop or Claude Code usage with stdio transport:
     "mcpServers": {
         "netbox": {
             "command": "uv",
-            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "server.py"],
+            "args": ["--directory", "/path/to/netbox-mcp-server", "run", "netbox-mcp-server"],
             "env": {
                 "NETBOX_URL": "https://netbox.example.com/",
                 "NETBOX_TOKEN": "<your-api-token>"
@@ -198,10 +205,10 @@ export TRANSPORT=http
 export HOST=127.0.0.1
 export PORT=8000
 
-uv run server.py
+uv run netbox-mcp-server
 
 # Or using CLI arguments
-uv run server.py \
+uv run netbox-mcp-server \
   --netbox-url https://netbox.example.com/ \
   --netbox-token <your-api-token> \
   --transport http \
@@ -237,11 +244,11 @@ LOG_LEVEL=INFO
 All configuration options can be overridden via CLI arguments:
 
 ```bash
-uv run server.py --help
+uv run netbox-mcp-server --help
 
 # Common examples:
-uv run server.py --log-level DEBUG --no-verify-ssl  # Development
-uv run server.py --transport http --port 9000       # Custom HTTP port
+uv run netbox-mcp-server --log-level DEBUG --no-verify-ssl  # Development
+uv run netbox-mcp-server --transport http --port 9000       # Custom HTTP port
 ```
 
 ## Docker Usage

claude.md

@@ -18,12 +18,20 @@ A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server th
 
 ```text
 .
-├── server.py              # Main MCP server with tool definitions
-├── netbox_client.py       # NetBox REST API client abstraction
-├── pyproject.toml         # Dependencies and project metadata
-├── README.md              # User-facing documentation
-├── SECURITY.md            # Security policy and reporting
-└── LICENSE                # Apache 2.0 license
+├── src/
+│   └── netbox_mcp_server/
+│       ├── __init__.py          # Package initialization with __version__
+│       ├── __main__.py          # Entry point for module execution
+│       ├── server.py            # Main MCP server with tool definitions
+│       ├── netbox_client.py     # NetBox REST API client abstraction
+│       ├── netbox_types.py      # NetBox object type mappings
+│       └── config.py            # Settings and logging configuration
+├── tests/                        # Test suite
+├── .github/workflows/            # CI/CD automation
+├── pyproject.toml               # Dependencies and project metadata
+├── README.md                    # User-facing documentation
+├── CHANGELOG.md                 # Auto-generated release notes
+└── LICENSE                      # Apache 2.0 license
 ```
 
 **Design Pattern**: Clean separation between MCP server logic (`server.py`) and NetBox API client (`netbox_client.py`) to support future plugin-based implementations.
@@ -35,13 +43,16 @@ A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server th
 uv sync
 
 # Run the server locally (requires env vars)
-NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<token> uv run server.py
+NETBOX_URL=https://netbox.example.com/ NETBOX_TOKEN=<token> uv run netbox-mcp-server
+
+# Alternative: module execution
+uv run -m netbox_mcp_server
 
 # Add to Claude Code (for development/testing)
 claude mcp add --transport stdio netbox \
   --env NETBOX_URL=https://netbox.example.com/ \
   --env NETBOX_TOKEN=<token> \
-  -- uv --directory /path/to/netbox-mcp-server run server.py
+  -- uv --directory /path/to/netbox-mcp-server run netbox-mcp-server
 ```
 
 ## Development Philosophy
@@ -57,6 +68,23 @@ claude mcp add --transport stdio netbox \
 - **Functional where clear**: Use functional, stateless approaches when they improve clarity
 - **Clean core logic**: Keep business logic clean; push implementation details to the edges
 
+## Version Management
+
+This project uses [python-semantic-release](https://python-semantic-release.readthedocs.io/) for automated version management. Versions are automatically determined from commit messages following [Conventional Commits](https://www.conventionalcommits.org/).
+
+**Release triggers:**
+
+- `feat:` commits trigger minor version bumps (1.0.0 → 1.1.0)
+- `fix:` and `perf:` commits trigger patch version bumps (1.0.0 → 1.0.1)
+- Commits with `BREAKING CHANGE:` in the body trigger major version bumps (1.0.0 → 2.0.0)
+- `docs:`, `test:`, `chore:`, `ci:`, `refactor:` commits are logged but don't trigger releases
+
+**Workflow:**
+
+- Merge to `main` automatically triggers release analysis
+- If commits warrant a release, version is bumped and CHANGELOG updated
+- GitHub Release is created with auto-generated release notes
+
 ## Code Standards
 
 ### Python Conventions
@@ -260,7 +288,6 @@ Currently no automated test suite. When adding tests:
 - ❌ **NEVER commit directly to `main`** - Always use feature branches
 - ✅ **DO keep commits professional and concise** and focused on the change
 
-
 ## Decision Heuristics
 
 ### When to Add a New Tool

pyproject.toml

@@ -1,3 +1,7 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
 [project]
 name = "netbox-mcp-server"
 version = "0.1.0"
@@ -12,8 +16,28 @@ dependencies = [
     "pydantic-settings>=2.0",
 ]
 
+[project.scripts]
+netbox-mcp-server = "netbox_mcp_server.server:main"
+
 [dependency-groups]
 dev = [
     "pytest>=8.4.2",
     "pytest-cov>=7.0.0",
+    "python-semantic-release>=10.4.1",
 ]
+
+[tool.semantic_release]
+version_toml = ["pyproject.toml:project.version"]
+version_variables = ["src/netbox_mcp_server/__init__.py:__version__"]
+branch = "main"
+upload_to_vcs_release = true
+build_command = "uv build"
+tag_format = "v{version}"
+
+[tool.semantic_release.commit_parser_options]
+allowed_tags = ["feat", "fix", "docs", "chore", "refactor", "test", "ci", "perf"]
+minor_tags = ["feat"]
+patch_tags = ["fix", "perf"]
+
+[tool.semantic_release.changelog]
+changelog_file = "CHANGELOG.md"

src/netbox_mcp_server/__init__.py

@@ -0,0 +1,9 @@
+"""NetBox MCP Server - Read-only MCP server for NetBox infrastructure data."""
+
+__version__ = "0.1.0"  # Auto-managed by semantic-release
+
+__all__ = ["NetBoxRestClient", "NETBOX_OBJECT_TYPES", "Settings"]
+
+from netbox_mcp_server.netbox_client import NetBoxRestClient
+from netbox_mcp_server.netbox_types import NETBOX_OBJECT_TYPES
+from netbox_mcp_server.config import Settings

src/netbox_mcp_server/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m netbox_mcp_server execution."""
+
+from netbox_mcp_server.server import main
+
+if __name__ == "__main__":
+    main()