rootly-mcp-server 2.3.8__tar.gz → 2.3.16__tar.gz

{rootly_mcp_server-2.3.8 → rootly_mcp_server-2.3.16}/.github/workflows/ci.yml

@@ -15,16 +15,16 @@ concurrency:
 
 jobs:
   quality:
-    name: Quality (Python 3.12)
+    name: Quality (Python 3.13)
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@7eb50e6e20e1e2009087999ba91242e80253875f # v7
@@ -53,10 +53,10 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -70,14 +70,14 @@ jobs:
         run: uv run pytest tests/unit/ --cov=src/rootly_mcp_server --cov-report=xml
 
       - name: Run local integration tests
-        if: matrix.python-version == '3.12'
+        if: matrix.python-version == '3.13'
         env:
           ROOTLY_API_TOKEN: ${{ secrets.ROOTLY_API_TOKEN }}
         run: uv run pytest tests/integration/local/ -x
 
       - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.12'
-        uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v5
+        if: matrix.python-version == '3.13'
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v5
         with:
           file: ./coverage.xml
           flags: unittests
@@ -87,15 +87,15 @@ jobs:
     name: Container Tests
     runs-on: ubuntu-latest
     needs: test
-    if: ${{ github.repository == 'Rootly-AI-Labs/rootly-mcp-server' }}
+    if: ${{ github.repository == 'rootlyhq/rootly-mcp-server' }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@7eb50e6e20e1e2009087999ba91242e80253875f # v7
@@ -135,12 +135,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@7eb50e6e20e1e2009087999ba91242e80253875f # v7
@@ -161,12 +161,12 @@ jobs:
     needs: [quality, test, security]
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@7eb50e6e20e1e2009087999ba91242e80253875f # v7

{rootly_mcp_server-2.3.8 → rootly_mcp_server-2.3.16}/.github/workflows/openapi-audit.yml

@@ -36,12 +36,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@7eb50e6e20e1e2009087999ba91242e80253875f # v7
@@ -58,12 +58,12 @@ jobs:
     if: ${{ github.event_name != 'pull_request' }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install uv
         uses: astral-sh/setup-uv@7eb50e6e20e1e2009087999ba91242e80253875f # v7

{rootly_mcp_server-2.3.8 → rootly_mcp_server-2.3.16}/.github/workflows/pypi-release.yml

@@ -13,12 +13,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Set up Python
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
-          python-version: '3.12'
+          python-version: '3.13'
 
       - name: Install uv and build tools
         run: |

{rootly_mcp_server-2.3.8 → rootly_mcp_server-2.3.16}/CHANGELOG.md

@@ -5,6 +5,143 @@ All notable changes to the Rootly MCP Server will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.16] - Released 2026-07-23
+
+### Added
+
+- **Meeting Recordings & Transcripts**: Added read-only tools `get_meeting_recording`, `list_meeting_recordings`, and `list_all_meeting_recordings` so agents can read call transcripts (the `meeting_transcript` / `meeting_transcript_formatted` data). Call `get_meeting_recording` with `include=transcript` for the full transcript. Refreshed the bundled `data/swagger.json` from source to pick up these endpoints
+
+### Fixed
+
+- **Incident Tool Hardening (follow-ups)**: A cluster of robustness fixes for the incident tools. Consolidated the incident-reference error taxonomy into one helper so `update_incident`, `find_related_incidents`, and `suggest_solutions` now report an unknown sequential number as `not_found` and a bad reference as `validation_error` (matching `get_incident`) instead of a generic error. Incident-reference resolution now rejects path-altering `"direct"` references (e.g. `../../…`, embedded slashes/whitespace) so a reference can't redirect the request to a different endpoint. Incident summarization tolerates a present-but-null `attributes` field instead of raising. `update_incident` now normalizes `summary` like `create_incident` (a whitespace-only summary is treated as no field). `search_incidents` multi-page mode now flags truncated results with `meta.partial`/`meta.error` instead of silently returning a partial set as complete. `list_incidents` and `search_incidents` append actionable guidance (use filters / `collect_incidents`) when a deep-page request fails with a client error. Removed the unused, uncapped `pagination.py` helpers
+- **Sequential Incident Lookups (400 Bad Request)**: Resolving an incident by its human-readable number (e.g. `57597`, `#57597`, `INC-57597`) no longer walks the entire incident list to find a match. The old approach binary-searched pages sorted by `-created_at`, and its first probe requested a high `page[number]` that the API rejects with a 400 once an account has enough incidents — so sequential lookups failed regardless of the number passed while UUIDs kept working. `get_incident` (and every other tool that accepts an incident reference) now resolves the number with a single direct `filter[sequential_id]` request. Also made the `INC-` prefix case-insensitive so lowercase `inc-57597` resolves correctly, and capped `suggest_solutions`' page size at the API maximum (100, was 150)
+- **Alert Payload Returned on Detail Lookups**: Single-alert lookups now return the full alert payload, including custom fields. Alert responses were stripped to a whitelist of essential attributes to keep payloads small, but this also dropped the raw `data` payload — where custom fields such as runbook links live (the same data shown under the Rootly UI's alert "payload" tab). The strip now applies only to list/search responses; single-resource detail lookups (`GET /v1/alerts/{id}`) preserve their full attribute set, while relationships are still collapsed to counts and sideloaded `included` data is dropped to keep responses bounded. The curated `get_alert_by_short_id` tool also passes through `data`, `alert_field_values`, and `labels` (plus `external_url` and `updated_at`). Verified end-to-end against a live alert
+
+### Security
+
+- **Dependency Bumps to Resolve Dependabot Alerts**: Raised direct override constraints in `pyproject.toml` (and regenerated `uv.lock`) to pull patched versions of vulnerable transitive dependencies, resolving all 16 open Dependabot alerts:
+  - `starlette` 0.52.1 → 1.3.1 (GHSA-82w8-qh3p-5jfq, -jp82-jpqv-5vv3, -wqp7-x3pw-xc5r, -x746-7m8f-x49c — DoS, SSRF)
+  - `cryptography` 46.0.7 → 49.0.0 (GHSA-537c-gmf6-5ccf — bundled OpenSSL)
+  - `python-multipart` 0.0.28 → 0.0.32 (CVE-2026-40347, GHSA-v9pg-7xvm-68hf, -6jv3-5f52-599m, -vffw-93wf-4j4q — DoS / parameter smuggling)
+  - `pyjwt` 2.12.1 → 2.13.0 (GHSA-xgmm-8j9v-c9wx, -993g-76c3-p5m4, -w7vc-732c-9m39, -jq35-7prp-9v3f, -fhv5-28vv-h8m8 — token forgery / DoS)
+  - `msgpack` 1.1.2 → 1.2.1 (GHSA-6v7p-g79w-8964 — out-of-bounds read)
+  - `authlib` 1.7.0 → 1.7.2 (GHSA-w8p2-r796-3vmq — OAuth open redirect)
+- **Follow-up Dependency Bumps**: Raised override constraints for newly disclosed vulnerabilities in transitive dependencies (`uv.lock` regenerated):
+  - `mcp` 1.26.0 → 1.28.1 (CVE-2026-52870, CVE-2026-52869, CVE-2026-59950)
+  - `joserfc` 1.6.4 → 1.7.4 (PYSEC-2026-2528, PYSEC-2026-2530)
+  - `idna` 3.10 → 3.18 (PYSEC-2026-215)
+  - `click` 8.1.8 → 8.4.2 (PYSEC-2026-2132)
+
+### Testing
+
+- Added coverage for detail-lookup payload preservation, list-response stripping (unchanged), and the `get_alert_by_short_id` payload/custom-field pass-through
+
+## [2.3.14] - Released 2026-06-05
+
+### Features
+
+- **`list_incident_roles` Tool**: Added a curated `list_incident_roles(incident_id)` tool that returns role assignments for an incident (Commander, Postmortem Owner, Scribe, etc.) as a flat table with role metadata and the assigned user. Wraps `GET /v1/incidents/{id}?include=roles` and flattens the JSON:API `included` array so callers don't have to walk the relationships graph. Included in the default hosted tool surface
+
+### Fixed
+
+- **Misnamed Tool Argument Normalization**: Added argument normalization middleware to recover from common LLM/client parameter mistakes before Pydantic validation runs. This now remaps `from`/`to` to `from_date`/`to_date` for `list_shifts`, remaps `max_tokens` to `max_results` for `search_incidents`, and coerces list-shaped schedule/shift identifiers into the CSV form expected by the current tool schemas
+
+### Testing
+
+- Expanded snake_case and argument-normalization coverage for alias handling, CSV coercion, and misnamed-argument recovery paths
+- Added coverage for `list_incident_roles` happy path, unassigned roles, sequential reference resolution, and validation errors
+
+## [2.3.13] - Released 2026-06-01
+
+### Features
+
+- **OAuth Authorization Server Metadata**: Hosted MCP deployments now serve RFC 8414 authorization server metadata so OAuth-capable clients can discover Rootly's authorization endpoints directly from the MCP server
+- **Safe Write Surface Expanded**: The default write-allowed surface now exposes a broader set of non-destructive tools for alerts, alert events, alert routes, alert sources, custom forms, form fields, workflow runs, status page templates, and related resources when write tools are enabled
+
+### Fixed
+
+- **Snake Case Tool Names**: OpenAPI-generated MCP tools are now normalized to `snake_case`, with a compatibility bridge for legacy camelCase callers, so tool discovery and invocation are more predictable across MCP clients
+- **ASGI Response Double-Send Guard**: Hosted auth middleware now suppresses orphaned or duplicate body frames after a response is already dropped or completed, preventing duplicate ASGI response behavior in production
+- **OAuth Scope Compatibility**: Protected resource metadata now advertises a single coarse `all` scope instead of many granular scopes, improving compatibility with MCP clients that fail to forward fine-grained scopes through dynamic client registration
+
+### Infrastructure
+
+- **Docker Base Updated**: The container image now builds on `python:3.13-slim`
+
+### Testing
+
+- Added focused coverage for snake_case normalization and the camelCase alias bridge
+- Added/updated hosted and server allowlist coverage for the expanded write surface
+
+## [2.3.12] - Released 2026-05-28
+
+### Fixed
+
+- **Unfilled Path Templates**: When a tool was called with a missing or misnamed path argument (e.g. `schedule_id` instead of `id`), FastMCP left the literal `{id}` placeholder in the URL and the encoded `%7Bid%7D` was sent upstream, producing a misleading 404 "Not found or unauthorized". The transport layer now detects unfilled placeholders in the URL path and raises a `RootlyValidationError` naming the missing parameter before any upstream call
+- **Deprecated Alert Routing Endpoint**: Tenants with Advanced Alert Routing enabled were repeatedly hitting 403s on `/v1/alert_routing_rules`. The replacement `listAlertRoutes` / `getAlertRoute` operations are now exposed in the default allowlist, and 403 responses with the Advanced Alert Routing message are annotated with a structured `_use_tool` field pointing models at the correct replacement
+- **Schedule Shift Date Range Cap**: `getScheduleShifts` and `listShifts` callers regularly hit opaque 422 errors after sending `from`/`to` windows larger than the upstream cap (1 month and 2 months respectively). A pre-flight check now parses the dates and rejects oversized windows client-side with a clear chunking recommendation. `/v1/override_shifts/*` paths are excluded
+- **Phantom `listIncidents` Tool**: `canonicalize_tool_names()` only expanded legacy → canonical aliases, so an allowlist mentioning `list_incidents` (the canonical name) stripped the curated `listIncidents` proxy. Alias expansion is now bidirectional, keeping both names exposed together during the deprecation window
+- **Missing `createSchedule` In Hosted Slim Profile**: The `/schedules` POST endpoint was already write-allowed, but the operationId wasn't included in the slim hosted tool profile. Added so models can actually create schedules when write tools are enabled
+- **Param-Name Discoverability**: Production logs showed models repeatedly guessing wrong on parameter names that were unobvious from tool descriptions. Tool descriptions now explicitly name the canonical argument shape for `getIncident` (`incident_id`, not `id`), the `max_results <= 10` cap on `search_incidents`, the `user_ids` (not `emails`) contract on `check_responder_availability`, and the plural `schedule_ids` argument on `get_oncall_schedule_summary`
+
+### Testing
+
+- Added focused transport coverage for unfilled-path-template rejection, shift date-range pre-flight (with override-shift lookalike exclusions), alert-routing 403 annotation, and false-positive guards on query-string braces and similar lookalike paths
+- Extended `canonicalize_tool_names` coverage for both directions of the legacy/canonical pair
+
+## [2.3.11] - Released 2026-05-27
+
+### Features
+
+- **Hosted Full Tool Surface by Default**: Hosted MCP deployments now expose the full tool surface by default again, so remote clients no longer miss create/update workflows that were absent from the slimmer hosted profile
+- **Hosted Slim Profile Selector**: Added a slimmer hosted profile of about 70 high-usage tools that clients can opt into with `?tool_profile=slim`, `X-Rootly-Tool-Profile: slim`, or the `ROOTLY_MCP_HOSTED_TOOL_PROFILE` server setting
+
+### Configuration
+
+- **Profile Override Precedence**: `ROOTLY_MCP_ENABLED_TOOLS` remains the highest-precedence override, so operators can still replace either hosted profile with an exact custom allowlist when needed
+
+### Documentation
+
+- **Hosted Profile Guidance**: Updated the README to document full-vs-slim hosted usage options, server-wide profile defaults, and exact allowlist overrides
+
+### Dependencies
+
+- **Lockfile Sync**: Regenerated `uv.lock` so the lockfile matches the current pinned package versions in `pyproject.toml`, including `fastmcp==3.3.1` and `requests==2.34.2`
+
+### Testing
+
+- **Hosted Routing Coverage**: Added coverage for hosted profile resolution, profiled streamable HTTP routing, explicit allowlist bypass behavior, and unknown profile fallback handling
+
+## [2.3.10] - Released 2026-05-26
+
+### Fixed
+
+- **Blank Query Param Forwarding**: The MCP transport now drops empty string, whitespace-only, and empty collection query parameters before forwarding requests upstream, preventing optional blank filters from corrupting pagination or other serialized query values
+- **Alerts Pagination Corruption Guard**: Hardened the shared request path used by OpenAPI-generated tools so requests that include blank optional filters no longer risk serializing `page[size]` incorrectly when valid pagination values are provided
+
+### Testing
+
+- Added focused transport regression coverage for dropping blank query params in both direct parameter transforms and rebuilt outbound request URLs
+
+## [2.3.9] - Released 2026-05-21
+
+### Performance
+
+- **Hosted Default Tool Surface Slimmed**: Default hosted deployments now expose a curated core profile of 55 high-usage tools instead of the full 200+ tool surface, improving MCP client tool-discovery performance while preserving a broad self-hosted default
+- **Hosted and Self-Hosted Defaults Split**: Hosted/serverless instances now default to the slim allowlist, while local and self-hosted deployments continue to expose the full tool catalog unless explicitly overridden
+
+### Configuration
+
+- **Hosted Allowlist Override Behavior**: `ROOTLY_MCP_ENABLED_TOOLS` now cleanly overrides the hosted default profile when operators want a narrower or broader remote tool surface
+
+### Documentation
+
+- **README Deployment Guidance Updated**: Documented the new hosted-versus-self-hosted tool defaults, the hosted override behavior, and the current approximate tool counts for each mode
+
+### Dependencies
+
+- **Lockfile Sync**: Regenerated `uv.lock` so the lockfile matches the current pinned versions in `pyproject.toml`, including `requests==2.34.0` and `pydantic==2.13.4`
+
 ## [2.3.8] - Released 2026-05-19
 
 ### Security

{rootly_mcp_server-2.3.8 → rootly_mcp_server-2.3.16}/CONTRIBUTING.md

@@ -39,19 +39,23 @@ uv pip install <package>
 
 ### 3. Set Up Git Hooks (Recommended)
 
-Install pre-commit hooks to automatically run linting and tests before commits:
+Install pre-commit hooks to automatically run the quality gate before commits:
 
 ```bash
-./scripts/setup-hooks.sh
+make hooks   # or: ./scripts/setup-hooks.sh
 ```
 
-This ensures code quality by running:
-- Ruff linting
-- Pyright type checking
-- Unit tests
+The hook runs `make check` (lint, format check, type checks, unit tests) —
+the same gate CI enforces.
 
 ### 4. Verify Installation
 
 The server should now be ready to use with your MCP-compatible editor.
 
 Additional testing tools are available in the `tests/` directory.
+
+## Common Tasks
+
+The `Makefile` wraps the toolchain; run `make help` to list every target.
+Common ones: `make check` (pre-push gate), `make test`, and `make fetch-spec`
+to refresh the bundled OpenAPI spec from source.

{rootly_mcp_server-2.3.8 → rootly_mcp_server-2.3.16}/Dockerfile

@@ -1,5 +1,5 @@
-# Use Python 3.12 slim image as base
-FROM python:3.12-slim
+# Use Python 3.13 slim image as base
+FROM python:3.13-slim
 
 # Set working directory
 WORKDIR /app
@@ -18,6 +18,14 @@ COPY . .
 # Install the package and its dependencies
 RUN uv pip install --system --no-cache-dir -e .
 
+# Install AgentCat (formerly MCPcat) for hosted telemetry without changing the
+# repo dependency graph. The [community] extra provides FastMCP support, which
+# this server relies on. AgentCat's package metadata pins an older Pydantic
+# range, but the SDK imports successfully with our runtime pin, so we restore
+# the server's pinned version after installation.
+RUN uv pip install --system --no-cache-dir "agentcat[community]==1.0.1" \
+    && uv pip install --system --no-cache-dir pydantic==2.13.4
+
 # Create non-root user
 RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
 

rootly_mcp_server-2.3.16/Makefile

@@ -0,0 +1,87 @@
+.DEFAULT_GOAL := help
+
+PYTHON_VERSION := 3.12
+SPEC_URL       := https://rootly-heroku.s3.amazonaws.com/swagger/v1/swagger.json
+SPEC_PATH      := src/rootly_mcp_server/data/swagger.json
+PKG            := src/rootly_mcp_server
+UV             := uv run --python $(PYTHON_VERSION)
+
+IMAGE := rootly-mcp-server
+
+.PHONY: help install build run \
+        test test-unit test-integration \
+        lint format format-check typecheck security \
+        fetch-spec audit-spec \
+        docker-build docker-test \
+        check ci hooks clean
+
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-16s\033[0m %s\n", $$1, $$2}'
+
+install: ## Install dependencies and the pinned Python via uv
+	uv sync --dev --python $(PYTHON_VERSION)
+
+build: ## Build the sdist and wheel
+	uv build
+
+run: ## Run the MCP server locally (needs ROOTLY_API_TOKEN)
+	$(UV) rootly-mcp-server
+
+# --- tests ---
+test: ## Run the full test suite (with coverage)
+	$(UV) pytest
+
+test-unit: ## Run unit tests only
+	$(UV) pytest tests/unit/
+
+test-integration: ## Run local integration tests (needs ROOTLY_API_TOKEN)
+	$(UV) pytest tests/integration/local/ -x
+
+# --- quality ---
+lint: ## Lint with ruff
+	$(UV) ruff check .
+
+format: ## Auto-format with ruff
+	$(UV) ruff format .
+
+format-check: ## Check formatting without modifying files (CI gate)
+	$(UV) ruff format --check .
+
+typecheck: ## Type-check with pyright and mypy
+	$(UV) pyright
+	$(UV) mypy $(PKG)
+
+security: ## Security scan (bandit blocking; pip-audit advisory, mirrors CI)
+	$(UV) bandit -r src/
+	-$(UV) pip-audit
+
+# --- OpenAPI spec ---
+fetch-spec: ## Refresh the bundled OpenAPI spec from source (never hand-edit it)
+	curl -fsS $(SPEC_URL) -o $(SPEC_PATH)
+
+audit-spec: ## Audit the bundled spec for MCP tool-generation issues
+	$(UV) python scripts/audit_openapi.py --filtered-defaults --instantiate-server
+
+# --- docker (mirrors the CI container-tests job) ---
+docker-build: ## Build the Docker image
+	docker build -t $(IMAGE) .
+
+docker-test: docker-build ## Build the image and run the containerized server smoke test (needs ROOTLY_API_TOKEN)
+	docker run -d --name $(IMAGE) -p 8000:8000 -e ROOTLY_API_TOKEN="$(ROOTLY_API_TOKEN)" $(IMAGE)
+	timeout 30s bash -c 'until curl -fsS http://localhost:8000/health || curl -fsS http://localhost:8000/; do sleep 2; done'
+	MCP_SERVER_URL=http://localhost:8000 $(UV) pytest tests/integration/remote/test_essential.py -v --timeout=60; \
+		status=$$?; docker stop $(IMAGE) && docker rm $(IMAGE); exit $$status
+
+# --- aggregates ---
+check: lint format-check typecheck test-unit ## Fast pre-push gate (mirrors CI quality + unit tests)
+
+ci: lint format-check typecheck security test-unit audit-spec ## Everything CI enforces (excl. docker/remote)
+
+# --- misc ---
+hooks: ## Install the git pre-commit hook
+	./scripts/setup-hooks.sh
+
+clean: ## Remove build and test artifacts
+	rm -rf dist build .pytest_cache .mypy_cache .ruff_cache coverage.xml htmlcov
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +