mcp-server-snowflake: Instructions file for Codex

AGENTS.md

Instructions for AI coding agents (Antigravity, Claude Code, Copilot, Cursor, Windsurf) working on this repository.

🎯 Project Overview

This is mcp-server-snowflake — an Enterprise Model Context Protocol (MCP) server exposing Snowflake's Data Cloud and Cortex AI as MCP tools (the expected tool set lives in scripts/check_tool_contract.py). It runs over stdio, streamable HTTP, or the deprecated SSE transport, and is consumed by AI clients (Claude Desktop, VS Code, Antigravity, Cursor, etc.).

The default tools/list is one flat catalog of all 140 tools. RegexSearchTransform (search_tools + call_tool) is opt-in via --enable-tool-search or SNOWFLAKE_MCP_ENABLE_TOOL_SEARCH=1.

🏗️ Key Paths

• src/snowflake_mcp/server.py — create_server factory; mounts each domain module with namespace=<domain>; stamps all four hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) in _annotate_local_tools; applies --profile and opt-in tool search.
• src/snowflake_mcp/middleware.py — ParentAuditMiddleware (outermost: timing, redact_message on exception args, re-raise the same exception), ReadOnlyGateMiddleware (blocks mutating tools/call names while read-only mode is on), and ErrorHandlingMiddleware (re-raises protocol errors unchanged and redacts tool-result payloads).
• src/snowflake_mcp/errors.py — template v1.6.0 whole-value redaction (redact_secrets, redact_message, redact_payload, tool_error, tool_failure, and status_error, the {"status": "error", ...} ToolError every tool handler raises) plus the Snowflake extras, and redact_error_payload / redact_error_value for tool payloads (any non-None value under a credential key is masked; JSON inside error strings keeps its shape), plus SnowflakeMCPError and AuthenticationError, ResourceNotFoundError, RateLimitError, and SafetyViolationError. Replacement text is [REDACTED]. Messages are redacted at construction.
• src/snowflake_mcp/tools/<domain>.py — one module per domain (queries, databases, tables, warehouses, governance, cortex, recipes, …), each exposing register_<name>_tools(mcp, client), where <name> is usually the singular of the module (for example register_query_tools in queries.py).
• src/snowflake_mcp/connection.py — SnowflakeClient (DictCursor query executor, snowflake.core.Root bridge). config.py — multi-auth resolver (PAT, key-pair, OAuth, user/password, connections.toml). cli.py — stdio / streamable-http / SSE runner (--profile, --enable-tool-search, host-origin protection on both network transports, and the exit-2 refusal of a tokenless HTTP bind to a non-localhost host). auth.py — SNOWFLAKE_MCP_AUTH_TOKEN bearer verifier (SharedTokenVerifier, attached by create_server) and the strict SNOWFLAKE_MCP_ALLOW_UNAUTHENTICATED_BIND opt-in.
• scripts/check_tool_contract.py — source of truth for the expected tool count and annotations. Do not hard-code tool counts elsewhere.
• scripts/check_conformance.sh + conformance-baseline.yml, scripts/check_snowflake_drift.py.
• 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/ — offline unit, mocked, and protocol tests; live checks in tests/test_e2e_live.py behind @pytest.mark.e2e, deselected by the default pytest addopts (-m 'not e2e') and in CI. Version and release-tooling tests are tests/test_version.py, tests/test_release_notes.py, and tests/test_check_version.py. tests/test_otel_spans.py records a failing tool's OpenTelemetry spans with an in-memory exporter (per-test SDK provider, global restored) and asserts no secret appears. tests/conftest.py clears the HTTP auth env vars and the cached module-level server before every test.
• .github/workflows/ — ci.yml (CI checks), release.yml (on a v* tag: build with full history, check the wheel version matches the tag, build the release notes, create the GitHub Release from scripts/release_notes.py with the wheel, sdist, and SBOM attached, then push the GHCR image only after that job succeeds, then a separate attest job with only contents: read, id-token: write and attestations: write attests dist/* and the pushed image digest; PyPI and MCP Registry publishing stay commented out, and the registry job needs attest once enabled), 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; commits version 0.0.0 and one OCI package, the GHCR image, whose tag lives in identifier), Dockerfile, pyproject.toml (console scripts mcp-server-snowflake and snowflake-mcp).