amplitude-mcp-analytics 0.2.0__tar.gz

amplitude_mcp_analytics-0.2.0/.github/workflows/release-please.yml

@@ -0,0 +1,122 @@
+name: release-please
+
+# Releases are fully automated from conventional-commit history: release-please
+# keeps a Release PR open against `main` (bumping `[project] version` in
+# pyproject.toml and prepending to CHANGELOG.md), and merging that PR tags the
+# release and publishes the built artifacts to PyPI.
+#
+# ---------------------------------------------------------------------------
+# INFRA MUST PROVISION THE FOLLOWING — NOTHING HERE IS SELF-CONFIGURING.
+# Until all three exist, both jobs below fail (they do not silently no-op):
+#
+#   1. A GitHub Actions environment named `pypi-release` on
+#      amplitude/Amplitude-MCP-Analytics-Python. Both jobs run in it. It must
+#      NOT carry a required-reviewer protection rule unless a human approving
+#      every push to main is intended — the rule gates the `release-please`
+#      job too, not just publishing.
+#
+#   2. Two secrets on that environment (not repo- or org-level secrets):
+#        - AMPLITUDE_DEV_EXP_APP_ID
+#        - AMPLITUDE_DEV_EXP_PRIVATE_KEY
+#      Same GitHub App credentials Amplitude-TypeScript / developer-cli use on
+#      their `npm-release` environment; infra copies them across.
+#
+#   3. A PyPI Trusted Publisher on the `amplitude-mcp-analytics` project:
+#        owner:       amplitude
+#        repository:  Amplitude-MCP-Analytics-Python
+#        workflow:    release-please.yml     <- this file's name; renaming the
+#                                              file breaks publishing
+#        environment: pypi-release
+#      The project has never been published, so this has to be created as a
+#      PyPI *pending* publisher before the first release, then it converts to a
+#      normal publisher on first upload. There is no PyPI API token anywhere in
+#      this repo and none should be added.
+# ---------------------------------------------------------------------------
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+  issues: write
+  # OIDC token for PyPI Trusted Publishing (`uv publish`). Declared at the
+  # workflow level because that is the scope uv's token exchange reads.
+  id-token: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-24.04
+    # AMPLITUDE_DEV_EXP_* live on the pypi-release environment (mirroring
+    # developer-cli's npm-release), not repo/org secrets.
+    environment: pypi-release
+    outputs:
+      releases_created: ${{ steps.release.outputs.releases_created }}
+    steps:
+      # Mint a GitHub App installation token so release-please's PRs trigger
+      # downstream workflows (GITHUB_TOKEN-authored events do not, by design,
+      # which would leave test.yml and semantic-pr.yml unrun and the Release PR
+      # BLOCKED behind required checks — or merged with no CI at all).
+      - uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
+        id: app-token
+        with:
+          app-id: ${{ secrets.AMPLITUDE_DEV_EXP_APP_ID }}
+          private-key: ${{ secrets.AMPLITUDE_DEV_EXP_PRIVATE_KEY }}
+
+      - uses: googleapis/release-please-action@16a9c90856f42705d54a6fda1823352bdc62cf38 # v4.4.0
+        id: release
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-24.04
+    needs: release-please
+    # Only the push that merges a Release PR sets this; every other push to
+    # main lands here as 'false' and the job is skipped.
+    if: needs.release-please.outputs.releases_created == 'true'
+    environment: pypi-release
+    steps:
+      - name: Checkout the repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+
+      # uv is installed from PyPI via the runner's Python (no third-party setup
+      # action), the same way test.yml does it.
+      - name: Install uv
+        run: python3 -m pip install --quiet uv
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      # The same gates test.yml enforces on every PR, re-run against the merged
+      # release commit: a red main must not reach PyPI, and unlike a tag push
+      # this artifact cannot be replaced once uploaded.
+      - name: Type check
+        run: uv run pyright src
+
+      - name: Test with coverage
+        run: uv run pytest --cov=amplitude_mcp_analytics -q
+
+      - name: Build the package
+        run: uv build
+
+      # Authenticates to PyPI via OIDC Trusted Publishing: `always` makes uv
+      # exchange the workflow's id-token for a short-lived PyPI token and fail
+      # loudly if that exchange is not available, rather than falling back to
+      # an unauthenticated (or credential-scavenging) upload the way the
+      # default `automatic` would. No UV_PUBLISH_TOKEN / PYPI_TOKEN exists.
+      #
+      # uv also uploads PEP 740 attestations for the wheel and sdist by
+      # default under trusted publishing.
+      #
+      # pypa/gh-action-pypi-publish would do the same thing, but the org's
+      # CI-pinning policy restricts third-party `uses:` lines and uv is already
+      # this repo's only packaging tool.
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

amplitude_mcp_analytics-0.2.0/.github/workflows/semantic-pr.yml

@@ -0,0 +1,67 @@
+name: Semantic PR
+
+# Enforces Conventional Commit PR titles (see CONTRIBUTING.md). This is
+# load-bearing for versioning: we squash-merge, so the PR title becomes the
+# commit message on main, and that message is the only input release-please
+# parses to decide the next version and write the changelog. A wrong type is
+# not a style nit — `chore:` on a user-visible fix ships no release at all.
+#
+# Keep the pattern permissive enough for release-please's own Release PR title
+# ("chore(main): release 1.2.3"), which lands here like any other PR because
+# release-please authors it with a GitHub App token.
+#
+# No third-party actions here by design (org policy allows only actions/* and
+# amplitude/*): a single bash step validates the title directly, so there's
+# nothing to pin or audit. The title is attacker-controlled text (anyone can
+# open a PR), so it is passed through env: rather than interpolated into the
+# script body, to avoid shell injection via a crafted title.
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+    branches: [main]
+
+permissions: {}
+
+jobs:
+  check-title:
+    name: Check PR title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate conventional-commit title
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          pattern='^(feat|fix|chore|docs|test|refactor|perf|ci|build|revert)(\([a-z0-9-]+\))?!?: .+'
+
+          if [[ "$PR_TITLE" =~ $pattern ]]; then
+            echo "PR title is valid: $PR_TITLE"
+            exit 0
+          fi
+
+          echo "::error::PR title does not follow Conventional Commits."
+          cat <<EOF
+
+          Got:      "$PR_TITLE"
+          Expected: <type>(<optional scope>)!: <description>
+
+          Allowed types:
+            feat     - new feature
+            fix      - bug fix
+            chore    - other changes that don't modify src or test files
+            docs     - documentation updates
+            test     - test updates
+            refactor - code change that neither fixes a bug nor adds a feature
+            perf     - performance improvement
+            ci       - CI configuration changes
+            build    - build system or dependency changes
+            revert   - revert a commit
+
+          Examples:
+            feat: add session replay support
+            fix(delivery): retry on 5xx
+            chore(main): release 1.2.0
+
+          See CONTRIBUTING.md for details.
+          EOF
+          exit 1

amplitude_mcp_analytics-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,117 @@
+name: Test
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      # uv is installed from PyPI via the runner's Python (no third-party
+      # setup action); uv then provisions the matrix interpreter itself.
+      - name: Install uv
+        run: python3 -m pip install --quiet uv
+
+      - name: Install dependencies
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: Type check
+        run: uv run pyright src
+
+      - name: Test with coverage
+        run: uv run pytest --cov=amplitude_mcp_analytics --cov-report=term --cov-report=xml -q
+
+  # The SDK integrates by wrapping the mcp package's server internals
+  # (Server.run, request_handlers, request_ctx, FastMCP's tool manager), so a
+  # new mcp release can silently change behavior the unit tests mock around.
+  # This job runs the full suite against the oldest supported SDK and the
+  # newest 1.x to catch that drift. mcp 2.x is intentionally unsupported —
+  # the "2.0.0" matrix entry asserts the adapter's loud rejection
+  # (ConfigurationError) instead of running the suite, so drift in the 2.x
+  # detection heuristics (type name, privatized registry attr) breaks CI
+  # rather than shipping silent non-emission. See core/mcp.py.
+  sdk-compat:
+    name: mcp SDK compat (${{ matrix.mcp-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        mcp-version: ["1.16.0", "latest-1.x", "2.0.0"]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        run: python3 -m pip install --quiet uv
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: Override mcp version
+        run: |
+          if [ "${{ matrix.mcp-version }}" = "latest-1.x" ]; then
+            uv pip install --upgrade "mcp>=1.16,<2"
+          else
+            uv pip install "mcp==${{ matrix.mcp-version }}"
+          fi
+
+      # Verify the override actually took — a resolver fallback that silently
+      # reinstalled the locked version would make this whole job a no-op.
+      - name: Verify override
+        run: |
+          INSTALLED=$(uv run --no-sync python -c "import importlib.metadata; print(importlib.metadata.version('mcp'))")
+          echo "installed mcp==${INSTALLED}"
+          if [ "${{ matrix.mcp-version }}" != "latest-1.x" ] && [ "$INSTALLED" != "${{ matrix.mcp-version }}" ]; then
+            echo "override did not take (wanted ${{ matrix.mcp-version }})" >&2
+            exit 1
+          fi
+          if [ "${{ matrix.mcp-version }}" != "2.0.0" ]; then
+            case "$INSTALLED" in
+              2.*) echo "unexpected mcp 2.x in the 1.x compat job" >&2; exit 1 ;;
+            esac
+          fi
+
+      - name: Test (1.x — full suite)
+        if: matrix.mcp-version != '2.0.0'
+        run: uv run --no-sync pytest -q
+
+      - name: Assert loud 2.x rejection
+        if: matrix.mcp-version == '2.0.0'
+        run: |
+          uv run --no-sync python - <<'EOF'
+          import pytest
+          from mcp.server.mcpserver import MCPServer
+          from mcp.server.lowlevel import Server
+          from amplitude_mcp_analytics import AmplitudeMCPAnalytics
+          from amplitude_mcp_analytics.exceptions import ConfigurationError
+          from amplitude_mcp_analytics.testing import MockAmplitudeMCPAnalytics
+
+          analytics = MockAmplitudeMCPAnalytics(server_name="ci", server_version="0.0.0")
+          for server in (MCPServer("ci"), Server("ci")):
+              with pytest.raises(ConfigurationError, match="mcp>=1.16,<2"):
+                  analytics.instrument_server(server)
+          print("2.x rejection path intact for MCPServer and lowlevel.Server")
+          EOF
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        run: python3 -m pip install --quiet uv
+
+      - name: Ruff
+        run: uv run --frozen ruff check src tests

amplitude_mcp_analytics-0.2.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.python-version
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# IDE / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Env
+.env

amplitude_mcp_analytics-0.2.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

amplitude_mcp_analytics-0.2.0/AGENTS.md

@@ -0,0 +1,135 @@
+# AGENTS.md
+
+Guidance for AI coding agents (and humans) working in this repo. Read this
+before making changes. It captures the tenets and conventions the team aligns
+on so that parallel sessions produce consistent, shippable work.
+
+This file is **internal** to the development team. It is not customer-facing —
+that is what `README.md` is for.
+
+## What this project is
+
+`amplitude-mcp-analytics` is a **public, customer-facing SDK** for tracking
+Model Context Protocol (MCP) server usage in Amplitude — the Python port of
+`@amplitude/mcp-analytics` (Amplitude-MCP-Analytics-Node). It mirrors that
+repo's developer experience (repo layout, constructor shape, mock test client)
+with Python-native tooling, but the **domain model is MCP-native** — servers,
+sessions, tool invocations — and intentionally does not reuse agent vocabulary.
+
+## Tenets
+
+These are the principles we use to break ties when a specific rule doesn't cover
+a situation.
+
+1. **The public API is a promise.** Anything exported becomes a semver contract.
+   Keep the public surface minimal; prefer adding API later over removing it.
+2. **Optimize for the consumer's ease of use.** The common case must work with
+   minimal config and sensible zero-config defaults. Wrap, don't rewrite: an
+   integration should not force consumers to change their existing handler
+   signatures, implement our interfaces, or hand-build values the SDK can
+   derive itself. Advanced hooks (custom resolvers, overrides) are opt-in
+   escape hatches for the long tail — never the required path for the basics.
+3. **Customer-facing artifacts assume zero internal knowledge.** `README.md`,
+   error messages, and published types must make sense to someone outside
+   Amplitude. No internal ticket numbers, no Slack/Linear links, no team jargon.
+4. **Nothing internal or sensitive gets committed — ever.** The repo and its
+   full git history are public. No secrets, API keys, tokens, internal URLs, or
+   customer data. A secret committed once lives in history forever.
+5. **Backwards compatibility is the default.** Don't break consumers or force
+   dependency conflicts. Keep dependency constraints wide (the `mcp>=1.16,<2`
+   range is deliberate); don't re-export a dependency's types into our public
+   API unless we intend to track them.
+6. **Porting is a fork point, not a sync target.** Ported code belongs to
+   this repo once copied; there is no obligation to track upstream.
+7. **Degrade honestly.** When we can't derive something accurately (e.g. a user
+   or session on stateless transport), emit accurate aggregate-only data rather
+   than fabricating it.
+8. **Small, atomic PRs over large ones.** One concern per PR; scoped so a
+   reviewer can hold it in their head.
+9. **When scope is ambiguous, stop and ask** rather than guessing.
+
+## Public API surface
+
+The published surface is **curated, not automatic.**
+
+- The public surface is the explicit `__all__` list in
+  `src/amplitude_mcp_analytics/__init__.py`. Add a name there only when you
+  intend to support importing it forever.
+- The smoke test (`tests/test_smoke.py`) is the tripwire for forgotten public
+  exports — it asserts every expected name exists and is in `__all__`. Keep it
+  green, and update its expected list in the **same PR** as any export change.
+- Internal modules (`src/amplitude_mcp_analytics/core/**`,
+  `src/amplitude_mcp_analytics/utils/**`) exist because public modules import
+  them, but they are **never** exported from the package root. Do not re-export
+  them.
+- Mark internal/test-only symbols with `@internal` in their docstring (the
+  Python stand-in for the Node repo's `@internal` + `stripInternal`; reviewers
+  and agents enforce it by convention). Test-only helpers should also be
+  prefixed `_`.
+- Before changing exports, ask: "Am I willing to support this import for the life
+  of the package?" If not, keep it internal.
+
+## Customer-facing vs internal references
+
+- **No ticket numbers** in `README.md`, shipped source comments, or error messages.
+  Internal references shouldn't be in anything that ships or that a customer reads.
+- Keep maintainer/process docs (porting policy, architecture rationale) out of
+  the customer README; put them here or in `PORTING.md`.
+- **Keep `README.md` in sync with the API.** When you introduce or change public
+  functionality (a new export, a changed signature, a new config option, a new
+  install/usage step), update `README.md` in the **same PR**. Customer-facing
+  docs must never lag the public surface.
+
+## Porting policy
+
+This repo **ports** from Amplitude-MCP-Analytics-Node (rather than vendoring
+from Amplitude-AI-Node, as the Node repo does). See `PORTING.md` for the
+upstream commit, the shared wire contract, and the full table of intentional
+divergences. Rules:
+
+- The **wire contract is shared** with the Node SDK — event names, `[MCP] `
+  property names, property precedence, the anonymous-drop rule, the error
+  taxonomy, and the anchor-derived identity math. Never change it unilaterally;
+  a wire change is a cross-SDK decision.
+- Adapt freely for Python needs; record intentional divergences in the
+  `PORTING.md` table in the same PR.
+- When a Node change is worth pulling over, do it as a normal PR with subject
+  `chore: port <thing> from Amplitude-MCP-Analytics-Node @ <sha>`.
+- Files that carry a provenance header (e.g. `core/delivery.py`) name their
+  upstream source; keep the header accurate when you refresh them.
+
+## Conventions
+
+- **Package manager: `uv`, exclusively.** `uv sync` to install, `uv add` to
+  change dependencies, `uv run` to execute tools. The committed `uv.lock` is
+  the source of truth. Never `pip install` into the project or introduce
+  poetry.
+- **PRs:** link the ticket, reference related PRs, and explicitly call out what is
+  intentionally out of scope or stubbed.
+- **PR titles set the version.** We squash-merge, so the title becomes the
+  commit message release-please parses: `!` or a `BREAKING CHANGE:` footer →
+  major, `feat:` → minor, `fix:`/`perf:`/`docs:`/`revert:` → patch, and
+  `chore:`/`test:`/`refactor:`/`build:`/`ci:` → no release. Choose the type by
+  user-visible impact, and write the title as the changelog line it will
+  become. `semantic-pr.yml` enforces the shape, not the accuracy.
+- **Never hand-edit the version.** `[project] version` in `pyproject.toml`,
+  `CHANGELOG.md` entries, and `.release-please-manifest.json` are owned by
+  release-please (`.github/workflows/release-please.yml`); merging its Release
+  PR is what tags the release and publishes to PyPI over OIDC Trusted
+  Publishing. No PyPI token exists in this repo — don't add one. Release
+  mechanics and the infra prerequisites are in `CONTRIBUTING.md` and that
+  workflow's header comment.
+
+## Verify before you finish
+
+All of these must pass:
+
+```bash
+uv sync
+uv run pyright src
+uv run pytest
+uv run ruff check src tests
+```
+
+Add tests next to the behavior you change. The smoke test in `tests/` is the
+tripwire for forgotten public exports — keep it green.

amplitude_mcp_analytics-0.2.0/CHANGELOG.md

@@ -0,0 +1,118 @@
+# Changelog
+
+Entries below are generated by
+[release-please](https://github.com/googleapis/release-please) from
+Conventional Commit messages when a Release PR merges — it inserts each new
+section directly above the most recent version heading, so don't hand-edit
+this file or add headings of your own.
+
+The `0.1.0` entry was written by hand before release-please took over, and
+**`0.1.0` was never published to PyPI** — it is only the pre-release baseline
+recorded in `.release-please-manifest.json`. There is no `v0.1.0` tag and no
+`0.1.0` distribution; `0.2.0` is this package's first published version, and it
+contains everything described under both headings.
+
+## [0.2.0](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/compare/v0.1.0...v0.2.0) (2026-09-11)
+
+
+### ⚠ BREAKING CHANGES
+
+* anchor-derived device_id values change for every anchor type, and user_id changes for the process anchor. Identities supplied explicitly via set_identity, resolve_identity, or instrument_server(user_id=...) are unaffected. Nothing has been published to PyPI yet, so no released version of this package emitted the old values; the matching Node SDK change is the one with existing data behind it.
+
+### Features
+
+* add Amplitude MCP Analytics SDK for Python ([#1](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/issues/1)) ([978f34e](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/commit/978f34e10ba6acd8136728b9b3f8a9b66cf32e0a))
+
+
+### Bug Fixes
+
+* derive device ids under a private namespace, not NameSpace_OID ([#2](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/issues/2)) ([809c300](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/commit/809c300d27d66a2551b423008d0804020d46f773))
+* keep breaking changes below 1.0.0 until the wire contract settles ([#5](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/issues/5)) ([76432b5](https://github.com/amplitude/Amplitude-MCP-Analytics-Python/commit/76432b532607c7564ce0ff5fa67745766a535942))
+
+## 0.1.0
+
+Initial port of [`@amplitude/mcp-analytics`](https://github.com/amplitude/Amplitude-MCP-Analytics-Node)
+v0.4.1 to Python. Feature parity with the Node SDK:
+
+- `instrument_server` / `instrument_tool` for FastMCP and low-level
+  `mcp.server.lowlevel.Server` (supported range `mcp>=1.16,<2`)
+- The five default events — `[MCP] Session Initialized`, `[MCP] Session
+  Ended`, `[MCP] Tools Listed`, `[MCP] Tool Call Response`, `[MCP] Tool Call
+  Rejected` — with the Node SDK's exact wire contract
+- Identity fallback chain (explicit → authInfo → server identity → anchor →
+  anonymous floor) with cross-SDK-compatible anchor-derived device ids
+- `set_identity`, `set_rationale`, `tool_error`, custom
+  `track_server_event`/`track_tool_event`, autocapture config,
+  `sanitize_error_message` (fail-closed), `emit_anonymous_event`,
+  dry-run/debug modes, serverless unflushed-events warning
+- `MockAmplitudeMCPAnalytics` in-memory test double
+
+### Pre-release API review changes
+
+Applied before the first release, so none of these are breaking changes against
+a published version:
+
+- **MIT `LICENSE`** added, with `license`/classifier/`[project.urls]` metadata
+  in `pyproject.toml`
+- **`amplitude-analytics` is now a hard runtime dependency**; the
+  `[amplitude]` extra is gone (`mcp` stays undeclared — duck-typed, and every
+  consumer already depends on it)
+- **`create_mcp_analytics` removed** — Node's `createMcpAnalytics` alias is
+  redundant with the `AmplitudeMCPAnalytics(...)` constructor
+- **`set_identity` takes keyword arguments** — `set_identity(user_id=...)` on
+  both the module function and the client method; a positional
+  `SetIdentityInput` is still accepted (passing both raises `ValueError`)
+- **`__version__`** exported from the package root, read from installed
+  package metadata
+- **`sanitize_rationale` config option** — rewrites or drops `[MCP] Rationale`
+  before emission, same fail-closed contract as `sanitize_error_message`; no
+  wire change unless configured
+- **SDK warnings now log to `amplitude_mcp_analytics`**, always — the injected
+  Amplitude client's `configuration.logger` is no longer preferred, so hosts
+  silencing the `amplitude` logger no longer lose the SDK's warnings
+- **`debug` logs at DEBUG level** instead of printing to stderr (`dry_run` and
+  the serverless exit warning still print, deliberately)
+- **Re-instrumenting a bound server from a *different* client now warns** —
+  the original binding stays active, as before
+
+### Code-review follow-ups
+
+Also pre-release. Where the Node SDK has the same behavior, fixing it here is a
+deliberate divergence with a row in `PORTING.md`:
+
+- **Release publishing is authorized by the forge, not by PR text** — the
+  hand-rolled `release.yml` / `publish.yml` pair is gone. Releases run through
+  release-please (`.github/workflows/release-please.yml`): the publish job is
+  gated on the action's own `releases_created` output rather than on a PR
+  title prefix and body marker any contributor could copy, and it uploads over
+  PyPI OIDC Trusted Publishing, so there is no long-lived `PYPI_TOKEN` in the
+  repo at all
+- **W3C `traceparent` is read from the HTTP header**, with `_meta.traceparent`
+  as the fallback — a normally propagated header no longer falls through to a
+  fresh anonymous anchor (and, by default, a dropped event) on stateless HTTP.
+  The anchor value is unchanged, so correlation still lines up with the Node
+  SDK; stdio is unaffected
+- **`traceparent` is validated against the full W3C shape** before its trace id
+  becomes a correlation anchor — malformed values such as
+  `00-<trace-id>-0000000000000000-01-junk`, an all-zero parent id, or the `ff`
+  version no longer stitch unrelated requests together. A valid header parses
+  exactly as before
+- **`[MCP] Response Size` / `[MCP] Request Size` now cover pydantic payloads** —
+  a low-level handler returning a `CallToolResult`, or a tool handed a
+  validated model argument, is measured via `model_dump_json` as the size
+  contract documents, instead of silently losing the property. Genuinely
+  unserializable values still omit it
+- **`flush()` / `shutdown()` settle the unflushed counters only after the
+  underlying call succeeds** — a failed flush no longer suppresses the
+  serverless "events were never flushed" warning for events that are still
+  queued
+- **The instrumentation marker is stamped on both views of a server** (a
+  `FastMCP` and its `_mcp_server`), so instrumenting one after the other is a
+  no-op with the usual different-client warning instead of a second client that
+  looks configured while emitting nothing
+- **An empty-string `sanitize_rationale` replacement is emitted** as
+  `[MCP] Rationale: ""` rather than dropped — the sanitizer contract omits the
+  property only on `None`, a non-string, or a raise, which is what
+  `sanitize_error_message` already did
+
+See `PORTING.md` for intentional divergences from the Node SDK.