mcp-server-sigma: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents (Antigravity, Claude Code, Copilot, Cursor, Windsurf) working on this repository or integrating Sigma Computing cloud analytics capabilities.

🎯 Project Overview

This is mcp-server-sigma — an enterprise Python Model Context Protocol (MCP) server for Sigma Computing, built on its public REST API (v2 and v3alpha); scripts/check_openapi_drift.py lists the spec endpoints the client does not cover. Bulk-destructive tools are listed in full and refused at call time unless enabled; the expected per-profile tool counts live in scripts/check_tool_contract.py.

Primary Purpose: Expose deep cloud business intelligence, embedded analytics, workbook lineage, SQL data modeling, user/team administration, and tenant token exchange to AI agents with strict enterprise safety gates, offline testing, and multi-tenant token isolation.

🏗️ Key Paths

• src/sigma_mcp/server.py — root gateway: create_server mounts the domain sub-servers (workbooks, datasets, elements, workspace, admin) with matching namespaces, then applies the job allowlist, the read-only filter, and (on full only) Tool Search or Code Mode; prompts, resources.
• src/sigma_mcp/profiles.py — PROFILES (full, readonly, and the job profiles analyst, author, modeler, embed, access_admin), their tool allowlists, FULL_ONLY_TOOLS, BULK_DESTRUCTIVE_TOOLS, and the readOnlyHint filter.
• src/sigma_mcp/tools/<domain>.py — domain sub-servers (admin, datasets, elements, workbooks, workspace); tools/common.py holds the ANNOTATION_* constants and shared helpers.
• src/sigma_mcp/client.py — async HTTP client (SigmaClient, _encode_segment(), RFC 8693 token exchange). SSRFSafeAsyncTransport resolves each request's host once (the ASCII/IDNA name, off the event loop), checks every address, and connects only to a checked one through a pinned httpcore network backend, trying the next checked address if a connect fails while the request's connect timeout lasts (one deadline shared by all the addresses, not a fresh timeout for each); the URL keeps the hostname for the Host header, TLS SNI, certificate verification and per-hostname connection pooling. A host with no checked address and Unix sockets are refused. The API client, the documentation fetches and scripts/check_openapi_drift.py all use it. httpx ignores env proxies whenever a transport is passed (allow_env_proxies = trust_env and transport is None), so connections always go direct through the pin; egress-proxy deployments need a proxy-aware transport, which isn't provided; trust_env=False on the drift fetch is belt-and-braces. errors.py — exceptions and secret redaction. auth.py — SharedTokenVerifier, the FastMCP TokenVerifier that create_server() attaches at build whenever SIGMA_MCP_AUTH_TOKEN is set (stripped, non-blank), so main(), fastmcp run and http_app() all enforce it (constant-time compare; stdio ignores it); main() also attaches it at serve time if the env was set after import, and refuses (exit 2) a tokenless HTTP bind to a host other than 127.0.0.1, ::1 or localhost unless SIGMA_MCP_ALLOW_UNAUTHENTICATED_BIND=1. webhooks.py — HMAC verification. middleware.py — read-only gate (readOnlyHint only, unwraps the Tool Search call_tool proxy) and the admin bulk-destructive gate. config.py — settings.
• scripts/check_tool_contract.py — source of truth for expected tool counts and annotations. README.md and four test files repeat some of these counts (SIGNED_OFF in tests/test_profiles.py, the 257 in tests/test_unit.py, tests/test_enterprise_assertion.py and tests/test_layered.py), so change them together; do not add new copies.
• scripts/check_openapi_drift.py, scripts/write_ops_check.py (live create-and-teardown against a Sigma org; needs SIGMA_CLIENT_ID, SIGMA_CLIENT_SECRET, and SIGMA_API_BASE_URL), scripts/check_conformance.sh + conformance-baseline.yml.
• scripts/release_notes.py — release body from squash commits since the previous v* tag. scripts/check_version.py — runs after the build and reads the version from the single wheel in dist/ (the file that ships, as release.yml's tag check does); fails on 0.0.0 (no git metadata) or 0.0.1.devN (no reachable tag, a shallow checkout).
• tests/ — unit tests are offline; live network tests live in tests/test_e2e_live.py (marked pytest.mark.e2e, deselected by default pytest addopts -m 'not e2e', run with -m e2e). That test sets no skip and no env check; tool calls use get_client, which requires SIGMA_CLIENT_ID and SIGMA_CLIENT_SECRET. The unmarked test_dispatch_tool_call_offline in that file stays in the default suite. tests/test_integration_live.py skips unless SIGMA_LIVE_TESTS=1 and SIGMA_CLIENT_ID are set. Security-hardening, webhook, and protocol tests are tests/test_security_hardening.py, tests/test_webhooks.py, and tests/test_protocol.py. Profile, read-only, and composition tests are tests/test_profiles.py and tests/test_layered.py. Version and release-tooling tests are tests/test_version.py, tests/test_release_notes.py, and tests/test_check_version.py.
• .github/workflows/ — ci.yml, release.yml (on a v* tag: build with full history, check the wheel version matches the tag, build the release notes, publish to PyPI, create the GitHub Release from scripts/release_notes.py, then push the Docker image only after the publish job succeeds, then stamp the tag version into server.json and publish to the MCP Registry in a last registry job that needs the Docker job), sigma-drift-monitor.yml, dependabot-automerge.yml (squash auto-merge only for Dependabot PRs whose highest update is minor or patch; major updates wait for a human review).
• server.json (MCP Registry metadata), Dockerfile, pyproject.toml.