tagmanager-mcp: Instructions file for Claude Code

tagmanager-mcp

Google Tag Manager MCP server in Python (stdio, MCPServer from the official mcp SDK v2). v0.1 (read), v0.2 (write) and v0.3 (versions and publishing) are shipped and verified against a real container — the v0.3 end-to-end smoke test ran 2026-07-09; v0.3.2 moved the SDK from mcp 1.x/FastMCP to mcp 2.x/MCPServer with no change to the tools themselves. 24 tools (13 read + 11 write), 71 offline tests. Published on PyPI as tagmanager-mcp; pushing a v* tag releases via GitHub Actions Trusted Publishing (see "Releasing").

Commands

uv sync                                   # deps into .venv (uv, not pip)
uv run nox -s tests                       # the whole 3.10-3.14 matrix, ~24s
uv run nox -s tests-3.12                  # one interpreter
uv run nox -s lint                        # ruff format --check + ruff check
uv run nox -s format                      # ruff format + ruff check --fix
uv run mcp dev tagmanager_mcp/server.py   # MCP Inspector
uv build                                  # sdist + wheel into dist/ (gitignored)
uvx twine check dist/*                    # metadata + README renders on PyPI

nox is backed by uv: every tests session builds its own virtualenv and installs from uv.lock, so the matrix never touches the project .venv. Do not reach for uv run --python 3.10 directly — see the hard constraint below. The test command lives only in noxfile.py; CI calls the sessions.

Register the checkout (not the published version) with Claude Code: claude mcp add --scope user tagmanager-mcp -- <abs path>/.venv/bin/tagmanager-mcp. Restart Claude Code after code changes; tools load only at startup.

Architecture

tagmanager_mcp/
├── __init__.py      # package_version() — feeds serverInfo and the API user agent
├── coordinator.py   # mcp = MCPServer(...) — the one instance everything registers on
├── server.py        # importing the tools modules triggers @mcp.tool() → mcp.run() (stdio)
└── tools/
    ├── client.py    # ADC credential singleton (lazy, threading.Lock); fresh discovery
    │                # client per call. execute() is the mandatory layer for every API
    │                # call: backoff on 429/quota-403/5xx, 4s throttle after the first
    │                # rate limit, HttpError → actionable message, mutating=True for
    │                # writes. Also prevent_stdio_inheritance()
    ├── utils.py     # construct_*_path() (int / numeric string / full path), slim_*(),
    │                # merge_patch() (shallow, null deletes a key), paginate()
    ├── structure.py # list_accounts / list_containers / list_workspaces / get_workspace_status
    ├── tags.py      # list_tags (slim) / get_tag (full) / create / update / delete
    ├── triggers.py  # same shape as tags.py
    ├── variables.py # same shape as tags.py
    └── versions.py  # version reads (list/get/get_live) + create_version / publish_version.
                     # Versions are container-scoped, not under a workspace; create_version
                     # consumes the workspace; responses are always slimmed