ptm-mcp 0.1.0__tar.gz

ptm_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: ptm-mcp
+Version: 0.1.0
+Summary: MCP stdio server for the Prompt Test Manager API
+Author: PTM Team
+License: Proprietary
+Project-URL: Homepage, https://github.com/15five/prompt-test-manager
+Project-URL: Repository, https://github.com/15five/prompt-test-manager
+Project-URL: Changelog, https://github.com/15five/prompt-test-manager/blob/main/packages/ptm-mcp/CHANGELOG.md
+Project-URL: Issues, https://github.com/15five/prompt-test-manager/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp<2.0,>=1.2
+Requires-Dist: ptm-client<1.0,>=0.3.0
+Requires-Dist: pydantic<3.0,>=2.8
+Requires-Dist: packaging<26.0,>=24.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "dev"
+Requires-Dist: pytest-cov<7.0,>=5.0; extra == "dev"
+Requires-Dist: responses<1.0,>=0.25; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.6; extra == "dev"
+
+# ptm-mcp
+
+MCP (Model Context Protocol) stdio server for the Prompt Test Manager API.
+
+Lets agents built on top of MCP-capable clients (Claude Desktop, Claude Code, Codex, Goose) call PTM as first-class tools: list prompts, run evaluations, submit optimizations. All traffic is tagged with `X-PTM-Client: ptm-mcp/<version>` + a per-process `X-PTM-MCP-Session` UUID so the PTM backend can rate-limit, budget, and audit agent traffic separately from humans and service accounts.
+
+## Quickstart
+
+```bash
+# 1. Mint a PTM token (prompts for your PTM URL + email + password)
+bash scripts/mint-ptm-mcp-token.sh     # macOS / Linux
+pwsh scripts/mint-ptm-mcp-token.ps1    # Windows
+
+# 2. Wire into your MCP client of choice
+bash scripts/install-claude-desktop.sh # Claude Desktop (macOS / Linux)
+pwsh scripts/install-claude-desktop.ps1 # Claude Desktop (Windows)
+
+# Claude Code - macOS / Linux
+claude mcp add --transport stdio --scope user ptm -- uvx ptm-mcp
+
+# Claude Code - Windows
+claude mcp add --transport stdio --scope user ptm -- cmd /c uvx ptm-mcp
+
+# Codex (any OS)
+codex mcp add ptm -- uvx ptm-mcp
+
+# Env vars can be set via `--env KEY=VAL` on either command.
+# Full setup + token flow: docs/mcp-integration.md
+
+# Uninstall Claude Desktop entry (creates a timestamped backup):
+bash scripts/uninstall-claude-desktop.sh       # macOS / Linux
+pwsh scripts/uninstall-claude-desktop.ps1      # Windows
+```
+
+Full setup + troubleshooting: `docs/mcp-integration.md`.
+
+## Status
+
+Phase 2 complete: 17 tools (canary + 12 read + 4 write), 5 resource URI patterns, read-only gate, live end-to-end integration. Ships at `0.1.0`.
+
+## Prereqs
+
+- Python >= 3.12 in a venv you control.
+- PTM backend >= 1.9.0 (MCP middleware chokepoint landed in 1.9.0; older backends cannot enforce agent-scoped limits).
+- For the stdio smoke test: Node >= 18 (for `npx @modelcontextprotocol/inspector`) or a global install of the MCP Inspector CLI.
+
+## Install
+
+```
+pip install ptm-mcp
+```
+
+Requires Python >= 3.12. `ptm-mcp` pulls in `ptm-client` and the `mcp` SDK automatically. For pinned, runtime-tested versions see `pyproject.toml` in the release tag.
+
+### From source (dev mode)
+
+```
+git clone git@github.com:15five/prompt-test-manager
+cd prompt-test-manager
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -e packages/ptm-client
+pip install -e "packages/ptm-mcp[dev]"
+```
+
+Dev mode is what CI exercises. When developing locally, wire your MCP client config at `PYTHONPATH=packages/ptm-mcp/src:packages/ptm-client/src` so edits in `src/` are picked up without reinstalling.
+
+## Environment variables
+
+Consumed at startup. Missing required values fail fast with a descriptive error.
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `PTM_API_BASE_URL` | yes | - | e.g. `https://ptm.example.com` |
+| `PTM_API_TOKEN` | yes | - | PTM bearer. Service-account tokens preferred. |
+| `PTM_MCP_READ_ONLY` | no | `true` | Flip to `false` to unlock the 4 write tools. |
+| `PTM_MCP_TIMEOUT_SECONDS` | no | `30` | Per-request timeout (1..600). |
+| `PTM_MCP_LOG_LEVEL` | no | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. |
+
+Startup scrubs every env var outside a narrow allow-list (cloud creds, GitHub tokens, `PATH` - all get dropped). See `src/ptm_mcp/env.py`.
+
+## Claude Desktop config snippet
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "ptm": {
+      "command": "uvx",
+      "args": ["ptm-mcp"],
+      "env": {
+        "PTM_API_BASE_URL": "http://localhost:8010",
+        "PTM_API_TOKEN": "ptm_u_PASTE_HERE",
+        "PTM_MCP_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+`uvx` handles Python provisioning + caching automatically; no PYTHONPATH needed when installed from PyPI. Other clients (Claude Code, Codex): see `docs/mcp-integration.md` for client-specific wire-up.
+
+## Tool inventory
+
+### Read (13)
+
+`list_providers`, `list_prompts`, `get_prompt`, `get_prompt_tests`, `list_prompt_versions`, `get_prompt_version`, `compare_prompt_versions`, `list_runs`, `get_run`, `get_run_report`, `get_optimization_status`, `get_optimization_history`, `get_optimization_detail`.
+
+### Write (4, gated by `PTM_MCP_READ_ONLY`)
+
+`run_manual_eval`, `run_prompt_eval`, `submit_optimization`, `cancel_optimization`.
+
+### Resources (5 URI patterns)
+
+- `ptm://prompts/{prompt_id}` - active version's `prompt_text` (text/plain)
+- `ptm://prompts/{prompt_id}/v{N}` - that version's `prompt_text` (text/plain)
+- `ptm://runs/{run_key}/report.md` - markdown report (text/markdown)
+- `ptm://runs/{run_key}/report.html` - HTML report (text/html)
+- `ptm://optimizations/{optimization_id}/report.md` - markdown summary (text/markdown)
+
+Dynamic segments are allow-list validated (`^[a-zA-Z0-9_.-]+$` plus explicit `.`/`..` rejection). See `docs/mcp-security.md`.
+
+## Security defaults
+
+- `PTM_MCP_READ_ONLY=true` blocks every write tool at call time.
+- `X-PTM-Client` + `X-PTM-MCP-Session` on every outbound request.
+- Env scrub at startup.
+- Startup preflight (`/healthz` + `/auth/me` + `/meta`) with exponential backoff on transient failures and dedicated exit codes per failed layer.
+
+Full details: `docs/mcp-security.md`.
+
+## Development
+
+```
+pip install -e packages/ptm-client
+pip install -e 'packages/ptm-mcp[dev]'
+PYTHONPATH=packages/ptm-mcp/src:packages/ptm-client/src \
+  pytest packages/ptm-mcp/tests -q
+ruff check packages/ptm-mcp/src packages/ptm-mcp/tests
+ruff format --check packages/ptm-mcp/src packages/ptm-mcp/tests
+```
+
+End-to-end smoke (requires a running backend and Node for `npx`):
+
+```
+PTM_API_BASE_URL=http://localhost:8010 \
+PTM_API_TOKEN="ptm_u_..." \
+bash scripts/smoke_mcp_inspector.sh
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | clean shutdown |
+| `1` | unhandled exception |
+| `2` | `/healthz` unreachable after 31s of backoff |
+| `3` | `/auth/me` rejected the token |
+| `4` | backend version < 1.9.0 or unparseable |
+| `130` | interrupted (SIGINT) |
+
+## See also
+
+- `docs/mcp-integration.md` - end-user setup
+- `docs/mcp-developer.md` - adding a tool
+- `docs/mcp-security.md` - tokens, env, headers, read-only, kill switch
+- `docs/mcp-admin.md` - ops runbook + alert response

ptm_mcp-0.1.0/README.md

@@ -0,0 +1,167 @@
+# ptm-mcp
+
+MCP (Model Context Protocol) stdio server for the Prompt Test Manager API.
+
+Lets agents built on top of MCP-capable clients (Claude Desktop, Claude Code, Codex, Goose) call PTM as first-class tools: list prompts, run evaluations, submit optimizations. All traffic is tagged with `X-PTM-Client: ptm-mcp/<version>` + a per-process `X-PTM-MCP-Session` UUID so the PTM backend can rate-limit, budget, and audit agent traffic separately from humans and service accounts.
+
+## Quickstart
+
+```bash
+# 1. Mint a PTM token (prompts for your PTM URL + email + password)
+bash scripts/mint-ptm-mcp-token.sh     # macOS / Linux
+pwsh scripts/mint-ptm-mcp-token.ps1    # Windows
+
+# 2. Wire into your MCP client of choice
+bash scripts/install-claude-desktop.sh # Claude Desktop (macOS / Linux)
+pwsh scripts/install-claude-desktop.ps1 # Claude Desktop (Windows)
+
+# Claude Code - macOS / Linux
+claude mcp add --transport stdio --scope user ptm -- uvx ptm-mcp
+
+# Claude Code - Windows
+claude mcp add --transport stdio --scope user ptm -- cmd /c uvx ptm-mcp
+
+# Codex (any OS)
+codex mcp add ptm -- uvx ptm-mcp
+
+# Env vars can be set via `--env KEY=VAL` on either command.
+# Full setup + token flow: docs/mcp-integration.md
+
+# Uninstall Claude Desktop entry (creates a timestamped backup):
+bash scripts/uninstall-claude-desktop.sh       # macOS / Linux
+pwsh scripts/uninstall-claude-desktop.ps1      # Windows
+```
+
+Full setup + troubleshooting: `docs/mcp-integration.md`.
+
+## Status
+
+Phase 2 complete: 17 tools (canary + 12 read + 4 write), 5 resource URI patterns, read-only gate, live end-to-end integration. Ships at `0.1.0`.
+
+## Prereqs
+
+- Python >= 3.12 in a venv you control.
+- PTM backend >= 1.9.0 (MCP middleware chokepoint landed in 1.9.0; older backends cannot enforce agent-scoped limits).
+- For the stdio smoke test: Node >= 18 (for `npx @modelcontextprotocol/inspector`) or a global install of the MCP Inspector CLI.
+
+## Install
+
+```
+pip install ptm-mcp
+```
+
+Requires Python >= 3.12. `ptm-mcp` pulls in `ptm-client` and the `mcp` SDK automatically. For pinned, runtime-tested versions see `pyproject.toml` in the release tag.
+
+### From source (dev mode)
+
+```
+git clone git@github.com:15five/prompt-test-manager
+cd prompt-test-manager
+python3.12 -m venv .venv && source .venv/bin/activate
+pip install -e packages/ptm-client
+pip install -e "packages/ptm-mcp[dev]"
+```
+
+Dev mode is what CI exercises. When developing locally, wire your MCP client config at `PYTHONPATH=packages/ptm-mcp/src:packages/ptm-client/src` so edits in `src/` are picked up without reinstalling.
+
+## Environment variables
+
+Consumed at startup. Missing required values fail fast with a descriptive error.
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `PTM_API_BASE_URL` | yes | - | e.g. `https://ptm.example.com` |
+| `PTM_API_TOKEN` | yes | - | PTM bearer. Service-account tokens preferred. |
+| `PTM_MCP_READ_ONLY` | no | `true` | Flip to `false` to unlock the 4 write tools. |
+| `PTM_MCP_TIMEOUT_SECONDS` | no | `30` | Per-request timeout (1..600). |
+| `PTM_MCP_LOG_LEVEL` | no | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` / `CRITICAL`. |
+
+Startup scrubs every env var outside a narrow allow-list (cloud creds, GitHub tokens, `PATH` - all get dropped). See `src/ptm_mcp/env.py`.
+
+## Claude Desktop config snippet
+
+`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "ptm": {
+      "command": "uvx",
+      "args": ["ptm-mcp"],
+      "env": {
+        "PTM_API_BASE_URL": "http://localhost:8010",
+        "PTM_API_TOKEN": "ptm_u_PASTE_HERE",
+        "PTM_MCP_READ_ONLY": "true"
+      }
+    }
+  }
+}
+```
+
+`uvx` handles Python provisioning + caching automatically; no PYTHONPATH needed when installed from PyPI. Other clients (Claude Code, Codex): see `docs/mcp-integration.md` for client-specific wire-up.
+
+## Tool inventory
+
+### Read (13)
+
+`list_providers`, `list_prompts`, `get_prompt`, `get_prompt_tests`, `list_prompt_versions`, `get_prompt_version`, `compare_prompt_versions`, `list_runs`, `get_run`, `get_run_report`, `get_optimization_status`, `get_optimization_history`, `get_optimization_detail`.
+
+### Write (4, gated by `PTM_MCP_READ_ONLY`)
+
+`run_manual_eval`, `run_prompt_eval`, `submit_optimization`, `cancel_optimization`.
+
+### Resources (5 URI patterns)
+
+- `ptm://prompts/{prompt_id}` - active version's `prompt_text` (text/plain)
+- `ptm://prompts/{prompt_id}/v{N}` - that version's `prompt_text` (text/plain)
+- `ptm://runs/{run_key}/report.md` - markdown report (text/markdown)
+- `ptm://runs/{run_key}/report.html` - HTML report (text/html)
+- `ptm://optimizations/{optimization_id}/report.md` - markdown summary (text/markdown)
+
+Dynamic segments are allow-list validated (`^[a-zA-Z0-9_.-]+$` plus explicit `.`/`..` rejection). See `docs/mcp-security.md`.
+
+## Security defaults
+
+- `PTM_MCP_READ_ONLY=true` blocks every write tool at call time.
+- `X-PTM-Client` + `X-PTM-MCP-Session` on every outbound request.
+- Env scrub at startup.
+- Startup preflight (`/healthz` + `/auth/me` + `/meta`) with exponential backoff on transient failures and dedicated exit codes per failed layer.
+
+Full details: `docs/mcp-security.md`.
+
+## Development
+
+```
+pip install -e packages/ptm-client
+pip install -e 'packages/ptm-mcp[dev]'
+PYTHONPATH=packages/ptm-mcp/src:packages/ptm-client/src \
+  pytest packages/ptm-mcp/tests -q
+ruff check packages/ptm-mcp/src packages/ptm-mcp/tests
+ruff format --check packages/ptm-mcp/src packages/ptm-mcp/tests
+```
+
+End-to-end smoke (requires a running backend and Node for `npx`):
+
+```
+PTM_API_BASE_URL=http://localhost:8010 \
+PTM_API_TOKEN="ptm_u_..." \
+bash scripts/smoke_mcp_inspector.sh
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | clean shutdown |
+| `1` | unhandled exception |
+| `2` | `/healthz` unreachable after 31s of backoff |
+| `3` | `/auth/me` rejected the token |
+| `4` | backend version < 1.9.0 or unparseable |
+| `130` | interrupted (SIGINT) |
+
+## See also
+
+- `docs/mcp-integration.md` - end-user setup
+- `docs/mcp-developer.md` - adding a tool
+- `docs/mcp-security.md` - tokens, env, headers, read-only, kill switch
+- `docs/mcp-admin.md` - ops runbook + alert response

ptm_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ptm-mcp"
+version = "0.1.0"
+description = "MCP stdio server for the Prompt Test Manager API"
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "Proprietary"}
+authors = [{name = "PTM Team"}]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: Other/Proprietary License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Intended Audience :: Developers",
+  "Typing :: Typed",
+]
+dependencies = [
+  "mcp>=1.2,<2.0",
+  "ptm-client>=0.3.0,<1.0",
+  "pydantic>=2.8,<3.0",
+  "packaging>=24.0,<26.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.2,<9.0",
+  "pytest-asyncio>=0.23,<1.0",
+  "pytest-cov>=5.0,<7.0",
+  "responses>=0.25,<1.0",
+  "ruff>=0.6,<1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/15five/prompt-test-manager"
+Repository = "https://github.com/15five/prompt-test-manager"
+Changelog = "https://github.com/15five/prompt-test-manager/blob/main/packages/ptm-mcp/CHANGELOG.md"
+Issues = "https://github.com/15five/prompt-test-manager/issues"
+
+# Note: the live ``list_providers`` stdio smoke test expects the MCP
+# Inspector CLI to be on PATH. Inspector is a Node package published as
+# ``@modelcontextprotocol/inspector`` (not a PyPI package - the ``mcp-inspector``
+# name on PyPI is an unrelated placeholder). Install globally with
+# ``npm i -g @modelcontextprotocol/inspector`` or let the test invoke it
+# through ``npx``. See scripts/smoke_mcp_inspector.sh.
+
+[project.scripts]
+ptm-mcp = "ptm_mcp.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

ptm_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ptm_mcp-0.1.0/src/ptm_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""ptm-mcp: MCP stdio server for the Prompt Test Manager API."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ptm_mcp-0.1.0/src/ptm_mcp/__main__.py

@@ -0,0 +1,22 @@
+"""CLI entry point. Invoked as ``python -m ptm_mcp`` or ``ptm-mcp``."""
+
+from __future__ import annotations
+
+
+def main() -> int:
+    import asyncio
+    import logging
+
+    from .server import run
+
+    try:
+        return asyncio.run(run())
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # noqa: BLE001 - top-level boundary
+        logging.getLogger("ptm_mcp").exception("fatal: %s", exc)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ptm_mcp-0.1.0/src/ptm_mcp/config.py

@@ -0,0 +1,59 @@
+"""Runtime configuration parsed from environment variables.
+
+ptm-mcp is a stdio server started by an MCP client (Claude Desktop, Goose,
+etc.) which passes env vars through to the spawned process. We fail fast on
+missing or malformed required values so the client surfaces a clear error
+instead of a cryptic 401 on the first tool call.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+MIN_BACKEND_VERSION = "1.9.0"
+
+
+@dataclass(frozen=True)
+class Settings:
+    ptm_api_base_url: str
+    ptm_api_token: str
+    read_only: bool = True
+    timeout_seconds: int = 30
+    log_level: str = "INFO"
+
+
+class ConfigError(RuntimeError):
+    """Raised when required env vars are missing or malformed."""
+
+
+def load_settings() -> Settings:
+    """Load ptm-mcp settings from environment. Fail fast on missing required vars."""
+    base = os.environ.get("PTM_API_BASE_URL", "").strip()
+    token = os.environ.get("PTM_API_TOKEN", "").strip()
+    if not base:
+        raise ConfigError("PTM_API_BASE_URL is required")
+    if not token:
+        raise ConfigError("PTM_API_TOKEN is required")
+
+    read_only_env = os.environ.get("PTM_MCP_READ_ONLY", "true").strip().lower()
+    read_only = read_only_env not in ("false", "0", "no", "")
+
+    try:
+        timeout = int(os.environ.get("PTM_MCP_TIMEOUT_SECONDS", "30"))
+    except ValueError as exc:
+        raise ConfigError("PTM_MCP_TIMEOUT_SECONDS must be an integer") from exc
+    if timeout < 1 or timeout > 600:
+        raise ConfigError("PTM_MCP_TIMEOUT_SECONDS must be in 1..600")
+
+    log_level = os.environ.get("PTM_MCP_LOG_LEVEL", "INFO").upper()
+    if log_level not in ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+        raise ConfigError(f"PTM_MCP_LOG_LEVEL invalid: {log_level}")
+
+    return Settings(
+        ptm_api_base_url=base,
+        ptm_api_token=token,
+        read_only=read_only,
+        timeout_seconds=timeout,
+        log_level=log_level,
+    )

ptm_mcp-0.1.0/src/ptm_mcp/env.py

@@ -0,0 +1,54 @@
+"""Startup env-var scrubber.
+
+ptm-mcp inherits the full environment of the MCP client (Claude Desktop,
+Goose, etc.), which typically contains cloud credentials, GitHub tokens,
+and similar secrets unrelated to PTM. The stdio server does not subprocess
+anything, so it has no legitimate use for most of those. We drop everything
+outside a narrow allow-list at startup to shrink the blast radius if the
+process is ever compromised.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger("ptm_mcp.env")
+
+
+# NO PATH in the allow-list. stdio ptm-mcp does not subprocess anything.
+# Adding PATH later would require an opt-in and a documented subprocess caller.
+# See ~/dev/docs/code-review-1.md item C1.
+_ALLOWED_PREFIXES = ("PTM_", "LC_")
+_ALLOWED_EXACT = frozenset(
+    {
+        "HOME",
+        "USER",
+        "LANG",
+        "TZ",
+        "TERM",
+        "PYTHONPATH",
+        "PYTHONUNBUFFERED",
+        "SSL_CERT_FILE",
+        "REQUESTS_CA_BUNDLE",
+    }
+)
+
+
+def scrub_env() -> int:
+    """Remove env vars outside the allow-list. Returns count dropped."""
+    dropped: list[str] = []
+    for key in list(os.environ):
+        if key in _ALLOWED_EXACT:
+            continue
+        if any(key.startswith(p) for p in _ALLOWED_PREFIXES):
+            continue
+        dropped.append(key)
+        del os.environ[key]
+    if dropped:
+        logger.info(
+            "[ptm-mcp] Scrubbed %d env vars at startup. Kept %d.",
+            len(dropped),
+            len(os.environ),
+        )
+    return len(dropped)

ptm_mcp-0.1.0/src/ptm_mcp/headers.py

@@ -0,0 +1,48 @@
+"""MCP chokepoint signal headers.
+
+The PTM backend middleware (``@app.middleware("http")``) reads
+``X-PTM-Client`` to classify incoming requests as MCP-tagged and
+``X-PTM-MCP-Session`` to correlate the whole agent conversation with
+rows in ``mcp_usage`` and ``RunRecord.mcp_session_id``. See
+``docs/mcp-ptm-phase1.md`` sections 18.1 and 18.6.
+"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from . import __version__
+
+
+def new_session_id() -> str:
+    """UUID for the lifetime of one ptm-mcp server process.
+
+    Attached to every outbound HTTP call as ``X-PTM-MCP-Session``. The
+    backend correlates this with ``mcp_usage`` and ``RunRecord.mcp_session_id``
+    for forensic replay of an agent conversation.
+    """
+    return str(uuid4())
+
+
+def build_client_headers(session_id: str) -> dict[str, str]:
+    """Return the MCP-chokepoint signal headers the backend middleware reads."""
+    return {
+        "X-PTM-Client": f"ptm-mcp/{__version__}",
+        "X-PTM-MCP-Session": session_id,
+    }
+
+
+def install_client_headers(client, session_id: str) -> None:
+    """Merge MCP headers onto an existing ``PTMClient``.
+
+    v0.3.0 exposes ``client._headers`` as a plain dict; mutating it is the
+    simplest path that does not fork the client. If a future release hides
+    the dict, this helper becomes the single place to adapt.
+    """
+    headers = getattr(client, "_headers", None)
+    if headers is None or not isinstance(headers, dict):
+        raise RuntimeError(
+            "PTMClient does not expose a mutable _headers dict; update ptm-mcp to "
+            "match the current ptm-client shape."
+        )
+    headers.update(build_client_headers(session_id))