mcp-server-sigma 1.0.0__tar.gz

mcp_server_sigma-1.0.0/.coderabbit.yaml

@@ -0,0 +1,35 @@
+language: "en-US"
+
+reviews:
+  # 'chill' provides balanced feedback without nitpicky noise ('quiet' = critical only)
+  profile: "chill"
+
+  # Auto-Review Settings
+  auto_review:
+    enabled: true
+    drafts: false
+    # Skip automatic reviews when PR title contains 'dependabot' or 'bump'
+    ignore_title_keywords:
+      - "dependabot"
+      - "bump"
+
+  # Path Filters: Exclude lockfiles, virtualenvs, and log files from review
+  path_filters:
+    - "!poetry.lock"
+    - "!package-lock.json"
+    - "!.venv/**"
+    - "!**.log"
+
+  # Domain Path Instructions: Enforce project-specific architectural rules automatically
+  path_instructions:
+    - path: "src/sigma_mcp/server.py"
+      instructions: "Ensure all newly added tools declare read_only_hint, destructive_hint, or idempotent_hint annotations, and enforce explicit confirm=True parameters on all delete, archive, deactivate, and bulk-removal endpoints."
+    - path: "src/sigma_mcp/client.py"
+      instructions: "Verify HTTP 429 retry backoff includes jitter and preserves Retry-After minimum delay."
+
+  # Enables '🤖 Prompt for AI Agents' blocks in review comments for one-click resolution
+  enable_prompt_for_ai_agents: true
+
+  # Clean presentation settings
+  poem: false
+  collapse_walkthrough: true

mcp_server_sigma-1.0.0/.dockerignore

@@ -0,0 +1,22 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.git/
+.github/
+tests/
+docs/
+examples/
+scripts/
+skills/
+.env
+.env.example
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+*.md
+!README.md
+.coderabbit.yaml
+.dockerignore
+Dockerfile

mcp_server_sigma-1.0.0/.env.example

@@ -0,0 +1,4 @@
+export SIGMA_CLIENT_ID='your_client_id_here'
+export SIGMA_CLIENT_SECRET='your_client_secret_here'
+# Must match your org's region — Administration > Developer Access > API base URL
+export SIGMA_API_BASE_URL='https://api.us-a.aws.sigmacomputing.com'

mcp_server_sigma-1.0.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for everything in this repository.
+* @christianclaudio

mcp_server_sigma-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,54 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[Bug] "
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear description of the bug.
+
+## Steps to Reproduce
+
+1. Configure environment with `...`
+2. Call tool `sigma_...` with parameters `...`
+3. Observe error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the JSON error response if available.
+
+> **Before pasting:** redact any credentials, tokens, cookies, personal data,
+> and private resource identifiers (member IDs, org IDs, etc.) from the response.
+
+```json
+{
+  "type": "sigma_api_error",
+  "status_code": ...,
+  "method": "...",
+  "path": "...",
+  "detail": ...,
+  "request_id": "..."
+}
+```
+
+> If your report contains sensitive information that cannot be safely redacted,
+> use the [private security advisory](https://github.com/christianclaudio/mcp-server-sigma/security/advisories/new)
+> instead of a public issue.
+
+## Environment
+
+- Python version:
+- OS:
+- Sigma region (e.g., aws-us-east):
+- MCP host (e.g., Claude Desktop, Cursor):
+
+## Additional Context
+
+Any other relevant information.

mcp_server_sigma-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,31 @@
+---
+name: Feature Request
+about: Suggest a new tool or enhancement
+title: "[Feature] "
+labels: enhancement
+assignees: ''
+---
+
+## Summary
+
+A concise description of the feature or enhancement.
+
+## Use Case
+
+Describe the problem this would solve or the workflow it would enable.
+
+## Proposed Solution
+
+How you envision this working. For new tools, include:
+
+- Sigma API endpoint(s) involved
+- Proposed tool name (e.g., `sigma_...`)
+- Parameters and return value
+
+## Alternatives Considered
+
+Other approaches you've considered and why they're less ideal.
+
+## Additional Context
+
+Links to Sigma API docs, related issues, or examples.

mcp_server_sigma-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## What changed
+
+<!-- One or two sentences. Focus on why, not just what. -->
+
+## Checklist
+
+- [ ] `mypy --strict src/` is clean
+- [ ] `ruff check .` and `ruff format --check .` are clean
+- [ ] `pytest tests/test_unit.py tests/test_tools_mocked.py tests/test_enterprise_assertion.py` passes **without a live Sigma org**
+- [ ] `python scripts/check_openapi_drift.py` exits 0 (no wrong-path drift)
+- [ ] If tools were added/removed: tool-count and annotation assertions updated
+- [ ] If a tool writes or deletes: correct annotation (`destructiveHint`) and, where relevant, `dry_run`/`confirm` gating
+- [ ] If behavior changed: README / `docs/` updated
+- [ ] `CHANGELOG.md` updated
+- [ ] No secrets, tokens, or real org IDs committed
+
+## Verification
+
+<!-- Paste the actual command output you ran. -->

mcp_server_sigma-1.0.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      # Batch low-risk bumps into one PR to keep review noise down.
+      minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      actions-minor-and-patch:
+        patterns: ["*"]
+        update-types: ["minor", "patch"]

mcp_server_sigma-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,173 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  lint:
+    name: Lint and types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]" pip-licenses
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: Mypy strict
+        run: mypy --strict src/
+      - name: License compliance
+        run: pip-licenses --fail-on="GNU General Public License" --partial-match --order=license --ignore-packages docutils
+
+  test:
+    name: Tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Unit and mocked tests
+        run: pytest --cov=src/sigma_mcp --cov-report=term-missing --cov-fail-under=100 -q
+
+  contract:
+    name: Tool contract and env gating
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      # Guards the counts published in README against silent drift, and proves
+      # the safety env vars actually change what gets registered.
+      - name: Assert tool counts and safety gating
+        run: python scripts/check_tool_contract.py
+
+  openapi-drift:
+    name: OpenAPI drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+      # Fails the build if any client path is absent from Sigma's published
+      # OpenAPI spec. This is the guard against the wrong-path class of bug.
+      - name: Check client paths against Sigma spec
+        run: python scripts/check_openapi_drift.py
+
+  build:
+    name: Build and package check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build
+        run: python -m build
+      - name: Twine check
+        run: twine check dist/*
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 14
+
+  docker:
+    name: Docker build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - name: Build Docker image
+        run: docker build -t mcp-server-sigma:ci-${{ github.sha }} .
+      - name: Verify entrypoint
+        run: docker run --rm mcp-server-sigma:ci-${{ github.sha }} --help
+
+  codeql:
+    name: CodeQL
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: github/codeql-action/init@v3
+        with:
+          languages: python
+      - uses: github/codeql-action/analyze@v3
+        # SARIF upload may fail with "Resource not accessible by integration" on
+        # repos where the default GITHUB_TOKEN lacks security-events write access.
+        # The scan itself still runs; this only affects result visibility in the
+        # Security tab. Safe to suppress until GitHub fixes token propagation.
+        continue-on-error: true
+
+  live-smoke:
+    name: Live smoke (main only, requires secrets)
+    runs-on: ubuntu-latest
+    needs: [lint, test, contract, openapi-drift]
+    # Never runs on forks or PRs: it needs org credentials and touches a real
+    # Sigma organization.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository_owner == 'christianclaudio'
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Live smoke test
+        env:
+          SIGMA_CLIENT_ID: ${{ secrets.SIGMA_CLIENT_ID }}
+          SIGMA_CLIENT_SECRET: ${{ secrets.SIGMA_CLIENT_SECRET }}
+          SIGMA_API_BASE_URL: ${{ secrets.SIGMA_API_BASE_URL }}
+        # Skips cleanly rather than failing when secrets are unavailable.
+        run: |
+          if [ -z "$SIGMA_CLIENT_ID" ] || [ -z "$SIGMA_CLIENT_SECRET" ] || [ -z "$SIGMA_API_BASE_URL" ]; then
+            echo "One or more Sigma secrets not set; skipping live smoke."
+            exit 0
+          fi
+          PYTHONPATH=src python tests/smoke_test.py

mcp_server_sigma-1.0.0/.github/workflows/dependabot-automerge.yml

@@ -0,0 +1,24 @@
+name: Dependabot Auto-Merge
+
+on: pull_request_target
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@21025c705c08248db411dc16f3619e6b5f9ea21a # v2
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Enable auto-merge for Dependabot PRs
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mcp_server_sigma-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,110 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b  # v5.3.0
+        with:
+          python-version: "3.12"
+          cache: "pip"
+
+      - name: Install build tooling & runtime dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine cyclonedx-bom
+          pip install .
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$TAG" != "$PKG" ]; then
+            echo "Tag $TAG does not match pyproject version $PKG" >&2
+            exit 1
+          fi
+          echo "Tag and version agree: $PKG"
+
+      - name: Build
+        run: python -m build
+
+      - name: Twine check
+        run: twine check dist/*
+
+      - name: Generate CycloneDX SBOM
+        run: cyclonedx-py environment -o sbom.cdx.json
+
+      - uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65822d53b0323c2227  # v4.4.3
+        with:
+          name: dist
+          path: |
+            dist/
+            sbom.cdx.json
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write      # Trusted Publishing (OIDC) — no API token stored
+      attestations: write  # build provenance
+      contents: write      # attach assets to the GitHub Release
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: dist
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373  # v4.1.1
+        with:
+          subject-path: "dist/*"
+
+      # SHA-pinned deliberately: all actions in this workflow use immutable
+      # commit SHAs to protect against supply-chain tag mutations.
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+
+      - name: Attach SBOM to release
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228  # v3.0.2
+        with:
+          files: sbom.cdx.json
+
+  docker:
+    name: Publish Docker image
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+
+      - name: Log in to GHCR
+        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567  # v3.3.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Build and push
+        uses: docker/build-push-action@4f58ea79222b3b9dc2c8bbdd6debcef730109a75  # v6.9.0
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/${{ github.repository }}:${{ steps.version.outputs.version }}
+            ghcr.io/${{ github.repository }}:latest

mcp_server_sigma-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+.env
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Tool caches
+.mypy_cache/
+.ruff_cache/
+
+# Local code-review artifacts
+coderabbit-review*.txt
+uv.lock

mcp_server_sigma-1.0.0/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md
+
+Instructions for AI coding agents (Claude Code, Copilot, Cursor, Windsurf, etc.) working on this repository.
+
+## Project Overview
+
+This is `mcp-server-sigma` — a Python MCP server exposing 155 tools for Sigma Computing's REST API. It runs over stdio and is consumed by AI clients (Claude Desktop, VS Code, etc.).
+
+## Architecture
+
+```
+src/sigma_mcp/
+├── server.py      # MCP tool definitions (2600+ lines, all @mcp.tool() handlers)
+├── client.py      # Async HTTP client (OAuth2, retries, rate-limiting, tenant token exchange)
+├── errors.py      # Error formatting with secret redaction
+├── webhooks.py    # Webhook signature verification + in-memory event buffer
+└── __init__.py    # Version only
+```
+
+## Key Patterns
+
+- **Every tool** is an `async def` decorated with `@mcp.tool()` and `@sigma_tool`
+- `@sigma_tool` is a decorator that adds timing, structured logging, and error handling
+- **Destructive tools** require `confirm: bool = False` — reject if not `True`
+- **Composite tools** (promote, deploy, onboard) orchestrate multiple API calls
+- **Annotations** are applied post-registration via `mcp._tool_manager._tools` (private API, pinned SDK version)
+
+## Development Commands
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Lint + format
+ruff check . && ruff format --check .
+
+# Type check
+mypy --strict src/
+
+# Tests (100% coverage required)
+pytest --cov=src/sigma_mcp --cov-fail-under=100 -q
+
+# Tool contract validation
+python scripts/check_tool_contract.py
+
+# OpenAPI drift check
+python scripts/check_openapi_drift.py
+```
+
+## Testing Conventions
+
+- Tests use `unittest.mock.AsyncMock` to mock `SigmaClient` methods
+- Monkeypatch `srv._client` to inject a mock client
+- No `conftest.py` — each test file is self-contained
+- Coverage must stay at 100% — CI enforces this
+
+## Adding a New Tool
+
+1. Add the client method in `client.py` (async, typed)
+2. Add the `@mcp.tool()` handler in `server.py` with proper docstring
+3. Add the tool name to the appropriate annotation set (`_DESTRUCTIVE_NAMES`, `_IDEMPOTENT_NAMES`, or let it default to `_WRITE_SAFE`)
+4. Update `scripts/check_tool_contract.py` expected counts
+5. Update `README.md` tool count
+6. Add test coverage (must maintain 100%)
+
+## Safety Rules
+
+- Never remove `confirm=True` gates from destructive tools
+- Never expose credentials in error messages (secret redaction is automatic)
+- Bulk-destructive tools are gated behind `SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1`
+- Read-only mode (`SIGMA_MCP_READONLY=1`) filters out all write tools at registration time
+
+## CI Pipeline
+
+The CI runs 7 jobs: lint, test (4 Python versions), contract validation, OpenAPI drift, build+twine, CodeQL, and live smoke (main-only with secrets). All must pass for merge.

mcp_server_sigma-1.0.0/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+## 1.0.0 (2026-08-02)
+
+### Breaking Changes
+- **Bulk-destructive tools are no longer registered by default.** `sigma_bulk_deactivate_members` and `sigma_bulk_remove_team_members` require `SIGMA_MCP_ALLOW_BULK_DESTRUCTIVE=1` to appear in the tool list. Without it, they do not exist from the model's perspective. This is intentional: an unprompted "clean up inactive users" from a model should not have access to bulk deactivation.
+- **Single-Delete Confirmation Gating**: Mandatory `confirm: bool = False` opt-in parameter required on all atomic delete, archive, deactivate, and bulk-remove tools. Callers performing destructive operations must explicitly pass `confirm=True`.
+
+### Added
+- **Native MCP Resources**: Registered `sigma://reference/formulas`, `sigma://reference/capabilities`, `sigma://reference/docs-index`, and `sigma://webhooks/recent` native resources.
+- **Native MCP Prompts**: Registered `provision_tenant_dashboard`, `audit_organization_permissions`, `prepare_data_model`, `onboard_team_member`, `swap_warehouse_source`, and `audit_tenant_connections` native prompts.
+- **Documentation tools**: `sigma_search_docs` (AI-powered semantic search via Sigma's docs MCP) and `sigma_get_doc_page` (fetch any docs page as Markdown).
+- **Structured JSON Logging**: Support for `SIGMA_MCP_LOG_FORMAT=json` with structured log records including execution duration (`duration_ms`).
+- **Network Transport CLI Flags**: Added `--host` and `--port` CLI options for network transport server deployment.
+- **Path Segment Sanitization**: Automated path parameter quoting (`quote(seg, safe="").replace("..", "%2E%2E")`) across all 217 client API methods to prevent path traversal attacks.
+- **Secret & Token Redaction**: Multi-pattern regex scrubbing (`Bearer` tokens, `client_secret`, `access_token`, `subject_token`, and raw JWT `eyJ...`) across error responses and log payloads.
+- **Multi-Tenant Security**: Added `SIGMA_ALLOWED_TENANTS` allowlist check and `SIGMA_STRICT_TENANT_ALLOWLIST=1` fail-closed enforcement for RFC 8693 token exchange.
+- **Single-Delete Confirmation Gating**: Mandatory `confirm: bool = False` opt-in parameter required on all atomic delete, archive, deactivate, and bulk-remove tool calls.
+- **Safety gating**: `SIGMA_MCP_READONLY=1` removes all non-read-only tools from registration (83 tools remain). Composes with profiles (e.g. `admin` + `readonly` = read-only subset of admin tools).
+- **`embed` profile**: `SIGMA_MCP_PROFILE=embed` (55 tools) for embedded analytics workflows — core + embeds, user attributes, tenants, source swap, workspace grants.
+- **Catch-all regex rejection** in `sigma_bulk_deactivate_members`: patterns like `.*`, `.+`, `^.*$`, `.`, or empty string are refused because they would match every member in the org.
+- **10-member hard cap** on `sigma_bulk_deactivate_members`: if the pattern matches more than 10 members, the tool refuses and reports the match list. Prevents accidental org-wide deactivation.
+- **`sigma_formula_pitfalls` tool**: returns a curated Sigma formula reference to prevent hallucinated function names and type errors. Backed by `src/sigma_mcp/reference/formulas.md`.
+- **11 new endpoints**: reports (CRUD, schedules, elements, queries, lineage, sources, duplicate, export), source-swap policies, deployment documents, workbook version history, report schedules.
+- **Tool count now 155** (default), 157 with bulk-destructive opt-in, 83 read-only.
+- **Expanded test suite** covering profile composition, readonly filtering, bulk-gating, annotation completeness, and catch-all regex rejection.
+- **OSS files**: SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE.
+- **`scripts/check_tool_contract.py`**: validates counts, annotations, profiles, and gating. Runs in CI.
+- **docs/formulas.md**: full Sigma formula reference for agent consumption.
+
+### Fixed
+- Annotation counts corrected: 83 read-only, 16 destructive, 8 idempotent.
+- `sigma_promote_workbook` now creates the tag if it doesn't already exist (idempotent).
+
+## 0.2.0 (2026-08-01)
+
+### Breaking Changes
+- Client is now fully async (`httpx.AsyncClient`). All methods are `async def`.
+- All MCP tools are now `async def`. Requires MCP SDK >= 2.0.0.
+
+### Added
+- **Structured error handling**: `SigmaAPIError` class with status, path, method, detail, request_id. `@sigma_tool` decorator wraps all tools — no raw exceptions escape.
+- **8 recipe tools**: export+download, ownership transfer, shared workbooks, input table scan, bulk deactivate, change email, bulk team remove, tenant connection sync.
+- **Multi-tenant auth**: RFC 8693 token exchange via `SigmaClient.for_tenant()`. Per-tenant token cache with auto-refresh.
+- **MCP 2.0 annotations**: All 141 tools annotated with `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.
+- **Tool profiles**: `SIGMA_MCP_PROFILE=core|admin|full` to control tool registration.
+- **OpenAPI drift detection**: `scripts/check_openapi_drift.py` compares client paths against official spec.
+- **GitHub Actions CI**: Matrix on Python 3.10-3.13 with ruff + pytest.
+- **Auto-pagination tools**: `sigma_list_all_*` tools that follow pagination tokens.
+- **PyJWT dependency** for tenant token exchange.
+- Secret redaction in all error messages.
+
+### Fixed
+- `download_query()` now routes through `_request()` for retry/rate-limit handling.
+- `time.sleep` replaced with `await asyncio.sleep` throughout.
+
+## 0.1.0 (2025-06-15)
+
+Initial release. 131 tools covering the Sigma v2 API surface.