coding-tools-mcp 0.2.0__tar.gz → 0.2.1__tar.gz

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: coding-tools-mcp
-Version: 0.2.0
+Version: 0.2.1
 Summary: Workspace-confined coding tools exposed as an MCP server.
 Author: Coding Tools MCP Contributors
 License:                                  Apache License
@@ -535,6 +535,16 @@ The runtime binds one workspace root per server process. Paths are workspace-rel
 
 `--permission-mode safe` is the default. `--permission-mode trusted` opens local-development gates while keeping secret filtering and destructive-command checks. `--permission-mode dangerous` disables `exec_command` permission gates for operators who accept that risk inside an isolated runner. Do not use dangerous mode for untrusted workspaces or untrusted MCP clients.
 
+## Telemetry
+
+The server sends anonymous usage telemetry (per-tool success/latency counters
+and version/platform dimensions — never paths, arguments, commands, or file
+contents) to help prioritize fixes. Disable it with
+`CODING_TOOLS_MCP_TELEMETRY=off` or `DO_NOT_TRACK=1`; it is automatically off
+in CI. `CODING_TOOLS_MCP_TELEMETRY=debug` prints every event to stderr instead
+of sending. The full event list and guarantees are in
+[docs/telemetry.md](docs/telemetry.md).
+
 ## Compliance
 
 ```bash

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/README.md

@@ -307,6 +307,16 @@ The runtime binds one workspace root per server process. Paths are workspace-rel
 
 `--permission-mode safe` is the default. `--permission-mode trusted` opens local-development gates while keeping secret filtering and destructive-command checks. `--permission-mode dangerous` disables `exec_command` permission gates for operators who accept that risk inside an isolated runner. Do not use dangerous mode for untrusted workspaces or untrusted MCP clients.
 
+## Telemetry
+
+The server sends anonymous usage telemetry (per-tool success/latency counters
+and version/platform dimensions — never paths, arguments, commands, or file
+contents) to help prioritize fixes. Disable it with
+`CODING_TOOLS_MCP_TELEMETRY=off` or `DO_NOT_TRACK=1`; it is automatically off
+in CI. `CODING_TOOLS_MCP_TELEMETRY=debug` prints every event to stderr instead
+of sending. The full event list and guarantees are in
+[docs/telemetry.md](docs/telemetry.md).
+
 ## Compliance
 
 ```bash

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/coding_tools_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Coding Tools MCP server package."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

coding_tools_mcp-0.2.1/coding_tools_mcp/envutils.py

@@ -0,0 +1,20 @@
+"""Small stdlib-only helpers shared across the package.
+
+A leaf module: it imports nothing from the package, so both server.py and
+modules server.py itself imports (like telemetry.py) can use these without
+creating an import cycle.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+ENV_PREFIX = "CODING_TOOLS_MCP"
+
+
+def truthy_env(value: str | None) -> bool:
+    return (value or "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/coding_tools_mcp/protocol.py

@@ -87,7 +87,8 @@ def dispatch_rpc(runtime: Any, request: dict[str, Any]) -> dict[str, Any] | None
                 raise JsonRpcError(-32600, "Server is already initialized")
             validate_initialize_request(request)
             runtime.protocol_version = validate_initialize_params(params)
-            result = runtime.initialize()
+            client_info = params.get("clientInfo")
+            result = runtime.initialize(client_info if isinstance(client_info, dict) else None)
             runtime.initialized = True
         elif method == "notifications/initialized":
             return None

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/coding_tools_mcp/server.py

@@ -32,6 +32,7 @@ from pathlib import Path, PurePosixPath
 from typing import Any, cast
 
 from . import __version__
+from .envutils import ENV_PREFIX, truthy_env
 from .errors import JsonRpcError, ToolFailure
 from .oauth import (
     OAUTH_CODE_TTL_SECONDS,
@@ -70,6 +71,7 @@ from .protocol import (
     validate_rpc_envelope,
 )
 from .project_context import ProjectContext, load_project_context
+from .telemetry import SessionTelemetry
 from .textutils import DEFAULT_MAX_LINES, truncate_text_head
 from .tool_results import make_tool_result
 from .transport_http import HTTPSessionManager
@@ -242,7 +244,6 @@ ENV_FLAG_OPTIONS = {
 }
 NETWORK_LITERAL_COMMANDS = {"echo", "printf", "grep", "egrep", "fgrep", "rg", "cat", "head", "tail", "wc"}
 INLINE_SCRIPT_PERMISSION = "inline_script"
-ENV_PREFIX = "CODING_TOOLS_MCP"
 RUNTIME_ROOT_DIR_NAME = "coding-tools-mcp"
 SPECIAL_DEVICE_PATHS = ("/dev/null", "/dev/zero", "/dev/random", "/dev/urandom")
 DNS_RESOLVER_READ_ROOTS = (
@@ -391,10 +392,6 @@ def parse_shell_env_set(value: str | None) -> dict[str, str]:
     return {str(key): str(item) for key, item in parsed.items()}
 
 
-def truthy_env(value: str | None) -> bool:
-    return (value or "").strip().lower() in {"1", "true", "yes", "on"}
-
-
 def env_int(name: str, fallback: int) -> int:
     raw = (os.environ.get(name) or "").strip()
     try:
@@ -689,10 +686,6 @@ LANDLOCK_ACCESS_FS_TRUNCATE = 1 << 14
 LANDLOCK_ACCESS_FS_IOCTL_DEV = 1 << 15
 
 
-def utc_now() -> str:
-    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-
-
 def json_response_payload(payload: Any) -> bytes:
     return json.dumps(payload, sort_keys=True, separators=(",", ":")).encode("utf-8")
 
@@ -1137,6 +1130,7 @@ class Runtime:
         oauth_config: OAuthConfig | None = None,
         project_context: ProjectContext | None = None,
         fake_readonly_annotations: bool = False,
+        transport: str = "stdio",
     ) -> None:
         self.workspace = Workspace(workspace)
         self.enable_view_image = enable_view_image
@@ -1198,6 +1192,7 @@ class Runtime:
         self.request_sessions_lock = threading.Lock()
         self.request_context = threading.local()
         self.initialized = False
+        self.telemetry = SessionTelemetry(permission_mode=self.permission_mode, transport=transport)
         self._tool_handlers = {name: getattr(self, name) for name in TOOL_REGISTRY}
 
     def _set_runtime_dir(self, runtime_dir: Path) -> None:
@@ -1220,6 +1215,7 @@ class Runtime:
                 terminate_process_group(session.process, signal.SIGTERM)
             session.drain_readers()
         shutil.rmtree(self.runtime_dir, ignore_errors=True)
+        self.telemetry.finish()
 
     def _ensure_runtime_dirs(self) -> None:
         candidates = [self.runtime_dir]
@@ -1285,7 +1281,8 @@ class Runtime:
             return False
         return is_relative_to(resolved, self.runtime_dir)
 
-    def initialize(self) -> dict[str, Any]:
+    def initialize(self, client_info: dict[str, Any] | None = None) -> dict[str, Any]:
+        self.telemetry.record_session_start(client_info, self.protocol_version)
         return {
             "protocolVersion": self.protocol_version,
             "capabilities": {"tools": {"listChanged": False}},
@@ -1487,17 +1484,26 @@ class Runtime:
         }
 
     def emit_tool_trace(self, name: str, args: dict[str, Any], payload: dict[str, Any], started_at: float) -> None:
+        raw_error = payload.get("error")
+        error = raw_error if isinstance(raw_error, dict) else {}
+        duration_ms = int((time.time() - started_at) * 1000)
+        self.telemetry.record_tool_call(
+            name,
+            ok=bool(payload.get("ok")),
+            error_code=error.get("code"),
+            duration_ms=duration_ms,
+            truncated=bool(payload.get("truncated")),
+        )
         if os.environ.get(f"{ENV_PREFIX}_TRACE") != "1":
             return
-        error = payload.get("error") if isinstance(payload.get("error"), dict) else {}
         event = {
             "event": "tool_call",
             "timestamp": datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
             "tool": name,
             "ok": bool(payload.get("ok", False)),
             "status": payload.get("status"),
-            "error_code": error.get("code") if isinstance(error, dict) else None,
-            "duration_ms": int((time.time() - started_at) * 1000),
+            "error_code": error.get("code"),
+            "duration_ms": duration_ms,
             "session_id": payload.get("session_id"),
             "truncated": payload.get("truncated"),
             "args": redact_for_trace(args),
@@ -5412,6 +5418,7 @@ def build_runtime(
     oauth_config: OAuthConfig | None = None,
     emit_warning: bool = True,
     project_context: ProjectContext | None = None,
+    transport: str = "stdio",
 ) -> Runtime:
     workspace = Path(args.workspace or os.environ.get(f"{ENV_PREFIX}_WORKSPACE") or os.getcwd())
     runtime = Runtime(
@@ -5424,6 +5431,7 @@ def build_runtime(
         oauth_config=oauth_config,
         project_context=project_context,
         fake_readonly_annotations=runtime_policy.fake_readonly_annotations,
+        transport=transport,
     )
     if emit_warning and runtime.capabilities.skip_all_permissions:
         print(
@@ -5550,7 +5558,7 @@ def run_http(args: argparse.Namespace) -> int:
         )
         return 2
 
-    runtime = build_runtime(args, runtime_policy, auth_token=auth_token, oauth_config=oauth_config)
+    runtime = build_runtime(args, runtime_policy, auth_token=auth_token, oauth_config=oauth_config, transport="http")
 
     def runtime_factory() -> Runtime:
         return build_runtime(
@@ -5560,6 +5568,7 @@ def run_http(args: argparse.Namespace) -> int:
             oauth_config=oauth_config,
             emit_warning=False,
             project_context=runtime.project_context,
+            transport="http",
         )
 
     server = RuntimeHTTPServer((args.host, args.port), MCPHandler, runtime, runtime_factory)

coding_tools_mcp-0.2.1/coding_tools_mcp/telemetry.py

@@ -0,0 +1,336 @@
+"""Anonymous product telemetry: counters and enums sent to PostHog over HTTPS.
+
+The wire payload is a closed schema built exclusively from tool names, error
+codes, durations, counts, and version/platform strings. It is structurally
+incapable of carrying file paths, tool arguments, command lines, or file
+contents. The exact event list is documented in docs/telemetry.md.
+
+Controls, evaluated on every send decision:
+
+- ``CODING_TOOLS_MCP_TELEMETRY=off`` (or ``0``/``false``/``no``) disables sending.
+- ``DO_NOT_TRACK=1`` disables sending.
+- ``CI`` set truthy disables sending so CI runs never pollute usage data.
+- ``CODING_TOOLS_MCP_TELEMETRY=debug`` prints events to stderr instead of sending.
+
+Sending never blocks a tool call: ``record_tool_call`` only increments in-memory
+counters under its lock, events queue on a bounded queue serviced by a daemon
+thread, failures are swallowed, and overflow is dropped. Nothing
+telemetry-related is written to disk except one random install id under
+``~/.coding-tools-mcp/id``, used only to de-duplicate active-user counts;
+deleting that file resets the identity.
+
+Events are emitted only for sessions that completed a real MCP ``initialize``
+handshake, so importing this module or exercising a Runtime directly (as unit
+tests do) produces no traffic.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import platform
+import sys
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+from urllib.request import Request, urlopen
+
+from . import __version__
+from .envutils import ENV_PREFIX, truthy_env, utc_now
+
+POSTHOG_ENDPOINT = "https://us.i.posthog.com/batch/"
+# Public write-only ingest key: it can create events but never read them back.
+POSTHOG_PROJECT_KEY = "phc_ySPcp83qCtwWyTECxpHpZsouvucHUQ5bhQnLUoYMPqdG"
+
+ERROR_EVENTS_PER_SESSION = 20
+FLUSH_INTERVAL_SECONDS = 30.0
+FLUSH_BATCH_SIZE = 50
+QUEUE_LIMIT = 500
+SEND_TIMEOUT_SECONDS = 3.0
+
+_LABEL_LIMIT = 64
+_OFF_VALUES = {"0", "off", "false", "no", "disable", "disabled"}
+_DURATION_BUCKETS = ((100, "dur_lt_100ms"), (1_000, "dur_lt_1s"), (10_000, "dur_lt_10s"))
+_DURATION_OVERFLOW = "dur_gte_10s"
+
+
+def telemetry_mode() -> str:
+    """Return ``"on"``, ``"off"``, or ``"debug"`` from the environment."""
+
+    raw = (os.environ.get(f"{ENV_PREFIX}_TELEMETRY") or "").strip().lower()
+    if raw == "debug":
+        return "debug"
+    if raw in _OFF_VALUES:
+        return "off"
+    if truthy_env(os.environ.get("DO_NOT_TRACK")) or truthy_env(os.environ.get("CI")):
+        return "off"
+    return "on"
+
+
+def _label(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text[:_LABEL_LIMIT] if text else None
+
+
+def _looks_like_install_id(value: str) -> bool:
+    return len(value) == 32 and all(character in "0123456789abcdef" for character in value)
+
+
+_install_id_lock = threading.Lock()
+_install_id: str | None = None
+
+
+def install_id() -> str:
+    """A random per-install id, never derived from hardware, hostname, or paths.
+
+    Persisted so active-user counts de-duplicate across sessions; falls back to
+    a per-process id when the home directory is unwritable.
+    """
+
+    global _install_id
+    cached = _install_id
+    if cached:
+        return cached
+    with _install_id_lock:
+        if _install_id:
+            return _install_id
+        path = Path.home() / ".coding-tools-mcp" / "id"
+        try:
+            value = path.read_text(encoding="utf-8").strip()
+        except OSError:
+            value = ""
+        if not _looks_like_install_id(value):
+            value = uuid.uuid4().hex
+            try:
+                path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+                path.write_text(value + "\n", encoding="utf-8")
+                path.chmod(0o600)
+            except OSError:
+                pass
+        _install_id = value
+        return value
+
+
+def _post(events: list[dict[str, Any]]) -> None:
+    """Deliver one batch; prints in debug mode, never raises, never uses stdout."""
+
+    if not events:
+        return
+    mode = telemetry_mode()
+    if mode == "off":
+        return
+    if mode == "debug":
+        for event in events:
+            print(
+                f"telemetry (not sent): {json.dumps(event, sort_keys=True, separators=(',', ':'))}",
+                file=sys.stderr,
+                flush=True,
+            )
+        return
+    try:
+        request = Request(
+            POSTHOG_ENDPOINT,
+            data=json.dumps({"api_key": POSTHOG_PROJECT_KEY, "batch": events}).encode("utf-8"),
+            headers={"Content-Type": "application/json", "User-Agent": "coding-tools-mcp-telemetry"},
+        )
+        with urlopen(request, timeout=SEND_TIMEOUT_SECONDS):
+            pass
+    except Exception:  # noqa: BLE001 - telemetry must never surface failures
+        pass
+
+
+class _Sender:
+    """Bounded background queue that posts event batches off the caller's thread."""
+
+    def __init__(self) -> None:
+        self._wake = threading.Condition(threading.Lock())
+        self._queue: list[dict[str, Any]] = []
+        threading.Thread(target=self._run, name="coding-tools-mcp-telemetry", daemon=True).start()
+
+    def enqueue(self, events: list[dict[str, Any]], *, wake: bool = False) -> None:
+        if not events:
+            return
+        with self._wake:
+            room = QUEUE_LIMIT - len(self._queue)
+            if room > 0:
+                self._queue.extend(events[:room])
+            if wake or len(self._queue) >= FLUSH_BATCH_SIZE:
+                self._wake.notify_all()
+
+    def flush(self) -> None:
+        with self._wake:
+            batch, self._queue = self._queue, []
+        _post(batch)
+
+    def _run(self) -> None:
+        while True:
+            with self._wake:
+                self._wake.wait(timeout=FLUSH_INTERVAL_SECONDS)
+                batch, self._queue = self._queue, []
+            _post(batch)
+
+
+_sender_lock = threading.Lock()
+_sender: _Sender | None = None
+
+
+def _get_sender() -> _Sender:
+    global _sender
+    with _sender_lock:
+        if _sender is None:
+            _sender = _Sender()
+            atexit.register(_sender.flush)
+        return _sender
+
+
+class SessionTelemetry:
+    """Per-session in-memory counters emitted as closed-schema events.
+
+    ``record_tool_call`` only increments dictionary counters under its lock;
+    event dictionaries are built after the lock is released. Events exist only
+    for sessions activated by a real MCP ``initialize``
+    (``record_session_start``).
+    """
+
+    def __init__(self, *, permission_mode: str, transport: str = "stdio") -> None:
+        self._session_id = uuid.uuid4().hex
+        self._started_monotonic = time.monotonic()
+        self._base_properties: dict[str, Any] = {
+            "version": __version__,
+            "os": sys.platform,
+            "arch": platform.machine(),
+            "python": f"{sys.version_info.major}.{sys.version_info.minor}",
+            "transport": _label(transport),
+            "permission_mode": _label(permission_mode),
+            "session_id": self._session_id,
+            "$process_person_profile": False,
+        }
+        self._client_name: str | None = None
+        self._client_version: str | None = None
+        self._protocol_version: str | None = None
+        self._tools: dict[str, dict[str, Any]] = {}
+        self._error_events_sent = 0
+        self._errors_dropped = 0
+        self._failure_streak: tuple[str, int] | None = None
+        self._active = False
+        self._finished = False
+        self._lock = threading.Lock()
+
+    def record_session_start(self, client_info: dict[str, Any] | None, protocol_version: str) -> None:
+        with self._lock:
+            if self._active or self._finished:
+                return
+            self._active = True
+            if client_info:
+                self._client_name = _label(client_info.get("name"))
+                self._client_version = _label(client_info.get("version"))
+            self._protocol_version = _label(protocol_version)
+        if telemetry_mode() != "off":
+            self._emit([self._event("session_start", {})], wake=True)
+
+    def record_tool_call(
+        self, tool: str, *, ok: bool, error_code: str | None, duration_ms: int, truncated: bool
+    ) -> None:
+        emit_error: tuple[str, int] | None = None
+        with self._lock:
+            stats = self._tools.get(tool)
+            if stats is None:
+                stats = self._tools[tool] = {"calls": 0, "errors": {}, "buckets": {}, "truncated": 0}
+            stats["calls"] += 1
+            bucket = _DURATION_OVERFLOW
+            for limit, name in _DURATION_BUCKETS:
+                if duration_ms < limit:
+                    bucket = name
+                    break
+            stats["buckets"][bucket] = stats["buckets"].get(bucket, 0) + 1
+            if truncated:
+                stats["truncated"] += 1
+            if ok:
+                self._failure_streak = None
+            else:
+                code = _label(error_code) or "UNKNOWN"
+                stats["errors"][code] = stats["errors"].get(code, 0) + 1
+                streak = 1
+                if self._failure_streak and self._failure_streak[0] == tool:
+                    streak = self._failure_streak[1] + 1
+                self._failure_streak = (tool, streak)
+                if self._active:
+                    if self._error_events_sent < ERROR_EVENTS_PER_SESSION:
+                        self._error_events_sent += 1
+                        emit_error = (code, streak)
+                    else:
+                        self._errors_dropped += 1
+        if emit_error is not None and telemetry_mode() != "off":
+            self._emit(
+                [
+                    self._event(
+                        "tool_error",
+                        {
+                            "tool": _label(tool),
+                            "error_code": emit_error[0],
+                            "duration_ms": duration_ms,
+                            "consecutive_failures": emit_error[1],
+                        },
+                    )
+                ]
+            )
+
+    def finish(self) -> None:
+        with self._lock:
+            if self._finished:
+                return
+            self._finished = True
+            if not self._active or telemetry_mode() == "off":
+                return
+            duration_ms = int((time.monotonic() - self._started_monotonic) * 1000)
+            events = []
+            for tool, stats in sorted(self._tools.items()):
+                failures = sum(stats["errors"].values())
+                properties: dict[str, Any] = {
+                    "tool": _label(tool),
+                    "calls": stats["calls"],
+                    "ok": stats["calls"] - failures,
+                    "errors": failures,
+                    "truncated": stats["truncated"],
+                }
+                for code, count in sorted(stats["errors"].items()):
+                    properties[f"err_{code}"] = count
+                properties.update(stats["buckets"])
+                events.append(self._event("tool_summary", properties))
+            events.append(
+                self._event(
+                    "session_end",
+                    {
+                        "duration_ms": duration_ms,
+                        "tool_calls": sum(stats["calls"] for stats in self._tools.values()),
+                        "distinct_tools": len(self._tools),
+                        "errors_dropped": self._errors_dropped,
+                    },
+                )
+            )
+        self._emit(events, wake=True)
+
+    def _event(self, name: str, properties: dict[str, Any]) -> dict[str, Any]:
+        merged: dict[str, Any] = {
+            **self._base_properties,
+            "client_name": self._client_name,
+            "client_version": self._client_version,
+            "protocol_version": self._protocol_version,
+        }
+        merged.update(properties)
+        return {
+            "event": name,
+            "distinct_id": install_id(),
+            "timestamp": utc_now(),
+            "properties": merged,
+        }
+
+    def _emit(self, events: list[dict[str, Any]], *, wake: bool = False) -> None:
+        if telemetry_mode() == "off":
+            return
+        _get_sender().enqueue(events, wake=wake)

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/coding_tools_mcp/transport_stdio.py

@@ -11,7 +11,7 @@ class StdioRuntime(Protocol):
     protocol_version: str
     initialized: bool
 
-    def initialize(self) -> dict[str, Any]: ...
+    def initialize(self, client_info: dict[str, Any] | None = None) -> dict[str, Any]: ...
 
     def list_tools(self) -> dict[str, Any]: ...
 

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/coding_tools_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: coding-tools-mcp
-Version: 0.2.0
+Version: 0.2.1
 Summary: Workspace-confined coding tools exposed as an MCP server.
 Author: Coding Tools MCP Contributors
 License:                                  Apache License
@@ -535,6 +535,16 @@ The runtime binds one workspace root per server process. Paths are workspace-rel
 
 `--permission-mode safe` is the default. `--permission-mode trusted` opens local-development gates while keeping secret filtering and destructive-command checks. `--permission-mode dangerous` disables `exec_command` permission gates for operators who accept that risk inside an isolated runner. Do not use dangerous mode for untrusted workspaces or untrusted MCP clients.
 
+## Telemetry
+
+The server sends anonymous usage telemetry (per-tool success/latency counters
+and version/platform dimensions — never paths, arguments, commands, or file
+contents) to help prioritize fixes. Disable it with
+`CODING_TOOLS_MCP_TELEMETRY=off` or `DO_NOT_TRACK=1`; it is automatically off
+in CI. `CODING_TOOLS_MCP_TELEMETRY=debug` prints every event to stderr instead
+of sending. The full event list and guarantees are in
+[docs/telemetry.md](docs/telemetry.md).
+
 ## Compliance
 
 ```bash

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/coding_tools_mcp.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ apps/desktop-client/mcp_desktop_client/locales/app_zh_CN.qm
 apps/desktop-client/mcp_desktop_client/locales/app_zh_CN.ts
 coding_tools_mcp/__init__.py
 coding_tools_mcp/__main__.py
+coding_tools_mcp/envutils.py
 coding_tools_mcp/errors.py
 coding_tools_mcp/landlock_exec.py
 coding_tools_mcp/oauth.py
@@ -23,6 +24,7 @@ coding_tools_mcp/processes.py
 coding_tools_mcp/project_context.py
 coding_tools_mcp/protocol.py
 coding_tools_mcp/server.py
+coding_tools_mcp/telemetry.py
 coding_tools_mcp/textutils.py
 coding_tools_mcp/tool_results.py
 coding_tools_mcp/transport_http.py
@@ -34,4 +36,5 @@ coding_tools_mcp.egg-info/entry_points.txt
 coding_tools_mcp.egg-info/requires.txt
 coding_tools_mcp.egg-info/top_level.txt
 tests/test_desktop_client.py
-tests/test_release_checks.py
+tests/test_release_checks.py
+tests/test_telemetry.py

{coding_tools_mcp-0.2.0 → coding_tools_mcp-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coding-tools-mcp"
-version = "0.2.0"
+version = "0.2.1"
 description = "Workspace-confined coding tools exposed as an MCP server."
 requires-python = ">=3.11"
 dependencies = [

coding_tools_mcp-0.2.1/tests/test_telemetry.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import tempfile
+import unittest
+from collections.abc import Iterator
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+from coding_tools_mcp import telemetry
+from coding_tools_mcp.protocol import dispatch_rpc
+from coding_tools_mcp.server import Runtime
+from coding_tools_mcp.telemetry import ERROR_EVENTS_PER_SESSION, SessionTelemetry
+
+_ENV_KEYS = ("CODING_TOOLS_MCP_TELEMETRY", "DO_NOT_TRACK", "CI")
+
+
+@contextlib.contextmanager
+def scrubbed_env(**overrides: str) -> Iterator[None]:
+    """Run with the telemetry-controlling variables removed, then overridden.
+
+    The ambient environment (CI sets ``CI=true``; sandboxes may set
+    ``CODING_TOOLS_MCP_*``) must never decide what these tests observe.
+    """
+
+    with patch.dict(os.environ):
+        for key in _ENV_KEYS:
+            os.environ.pop(key, None)
+        os.environ.update(overrides)
+        yield
+
+
+class _CapturingSender:
+    def __init__(self) -> None:
+        self.events: list[dict[str, object]] = []
+
+    def enqueue(self, events: list[dict[str, object]], *, wake: bool = False) -> None:
+        self.events.extend(events)
+
+    def flush(self) -> None:
+        pass
+
+
+def _initialize(runtime: Runtime, client_name: str = "test-client") -> None:
+    response = dispatch_rpc(
+        runtime,
+        {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {"clientInfo": {"name": client_name, "version": "9.9.9"}},
+        },
+    )
+    assert response is not None and "error" not in response
+
+
+class TelemetryModeTests(unittest.TestCase):
+    def test_default_is_on(self) -> None:
+        with scrubbed_env():
+            self.assertEqual(telemetry.telemetry_mode(), "on")
+
+    def test_env_switch_disables(self) -> None:
+        for value in ("off", "0", "false", "no", "disabled"):
+            with self.subTest(value=value), scrubbed_env(CODING_TOOLS_MCP_TELEMETRY=value):
+                self.assertEqual(telemetry.telemetry_mode(), "off")
+
+    def test_do_not_track_disables(self) -> None:
+        with scrubbed_env(DO_NOT_TRACK="1"):
+            self.assertEqual(telemetry.telemetry_mode(), "off")
+
+    def test_do_not_track_overrides_explicit_on(self) -> None:
+        with scrubbed_env(CODING_TOOLS_MCP_TELEMETRY="on", DO_NOT_TRACK="1"):
+            self.assertEqual(telemetry.telemetry_mode(), "off")
+
+    def test_ci_disables(self) -> None:
+        with scrubbed_env(CI="true"):
+            self.assertEqual(telemetry.telemetry_mode(), "off")
+
+    def test_debug_mode(self) -> None:
+        with scrubbed_env(CODING_TOOLS_MCP_TELEMETRY="debug"):
+            self.assertEqual(telemetry.telemetry_mode(), "debug")
+
+
+class OffMeansOffTests(unittest.TestCase):
+    def test_disabled_session_never_reaches_the_sender(self) -> None:
+        for overrides in ({"CODING_TOOLS_MCP_TELEMETRY": "off"}, {"DO_NOT_TRACK": "1"}, {"CI": "1"}):
+            with self.subTest(overrides=overrides), scrubbed_env(**overrides):
+                get_sender = Mock()
+                with patch.object(telemetry, "_get_sender", get_sender):
+                    with tempfile.TemporaryDirectory() as tmp:
+                        runtime = Runtime(Path(tmp))
+                        _initialize(runtime)
+                        runtime.call_tool("get_default_cwd", {})
+                        runtime.call_tool("read_file", {"path": "missing.txt"})
+                        runtime.close()
+                get_sender.assert_not_called()
+
+    def test_post_sends_nothing_when_disabled(self) -> None:
+        with scrubbed_env(CODING_TOOLS_MCP_TELEMETRY="off"):
+            with patch.object(telemetry, "urlopen", Mock()) as opener:
+                telemetry._post([{"event": "session_start"}])
+            opener.assert_not_called()
+
+    def test_debug_mode_prints_to_stderr_and_does_not_send(self) -> None:
+        with scrubbed_env(CODING_TOOLS_MCP_TELEMETRY="debug"):
+            stderr = io.StringIO()
+            with patch.object(telemetry, "urlopen", Mock()) as opener:
+                with contextlib.redirect_stderr(stderr):
+                    telemetry._post([{"event": "session_start", "properties": {}}])
+            opener.assert_not_called()
+        output = stderr.getvalue()
+        self.assertIn("telemetry (not sent):", output)
+        self.assertIn("session_start", output)
+
+
+def _run_probe_session() -> _CapturingSender:
+    sender = _CapturingSender()
+    with scrubbed_env(), patch.object(telemetry, "_get_sender", lambda: sender):
+        with tempfile.TemporaryDirectory() as tmp:
+            marker = "leakprobe-a8f3"
+            workspace = Path(tmp) / marker
+            workspace.mkdir()
+            (workspace / f"{marker}.txt").write_text("leakprobe-content\n", encoding="utf-8")
+            runtime = Runtime(workspace)
+            _initialize(runtime, client_name="clientinfo-probe")
+            runtime.call_tool("get_default_cwd", {})
+            runtime.call_tool("read_file", {"path": f"{marker}-missing.txt"})
+            runtime.call_tool("read_file", {"path": f"{marker}-missing.txt"})
+            runtime.close()
+    return sender
+
+
+class SessionEventTests(unittest.TestCase):
+    def test_payload_never_contains_paths_arguments_or_content(self) -> None:
+        sender = _run_probe_session()
+        serialized = json.dumps(sender.events)
+        self.assertNotIn("leakprobe", serialized)
+        self.assertNotIn("missing.txt", serialized)
+
+    def test_session_events_carry_the_closed_schema(self) -> None:
+        sender = _run_probe_session()
+        by_name: dict[str, list[dict[str, object]]] = {}
+        for event in sender.events:
+            by_name.setdefault(str(event["event"]), []).append(event)
+        self.assertEqual(len(by_name["session_start"]), 1)
+        self.assertEqual(len(by_name["session_end"]), 1)
+        self.assertEqual(len(by_name["tool_error"]), 2)
+
+        properties = by_name["session_start"][0]["properties"]
+        assert isinstance(properties, dict)
+        self.assertEqual(properties["$process_person_profile"], False)
+        self.assertEqual(properties["transport"], "stdio")
+        self.assertEqual(properties["permission_mode"], "safe")
+        # clientInfo values are enum-like labels, truncated, and expected here.
+        self.assertEqual(properties["client_name"], "clientinfo-probe")
+
+        errors = by_name["tool_error"]
+        first = errors[0]["properties"]
+        second = errors[1]["properties"]
+        assert isinstance(first, dict) and isinstance(second, dict)
+        self.assertEqual(first["tool"], "read_file")
+        self.assertEqual(first["error_code"], "NOT_FOUND")
+        self.assertEqual(first["consecutive_failures"], 1)
+        self.assertEqual(second["consecutive_failures"], 2)
+
+        summaries = {
+            str(event["properties"]["tool"]): event["properties"]  # type: ignore[index]
+            for event in by_name["tool_summary"]
+        }
+        self.assertEqual(summaries["read_file"]["calls"], 2)
+        self.assertEqual(summaries["read_file"]["ok"], 0)
+        self.assertEqual(summaries["read_file"]["err_NOT_FOUND"], 2)
+        self.assertEqual(summaries["get_default_cwd"]["calls"], 1)
+        self.assertEqual(summaries["get_default_cwd"]["ok"], 1)
+
+        end = by_name["session_end"][0]["properties"]
+        assert isinstance(end, dict)
+        self.assertEqual(end["tool_calls"], 3)
+        self.assertEqual(end["distinct_tools"], 2)
+        self.assertEqual(end["errors_dropped"], 0)
+
+    def test_sessions_without_initialize_emit_nothing(self) -> None:
+        sender = _CapturingSender()
+        with scrubbed_env(), patch.object(telemetry, "_get_sender", lambda: sender):
+            with tempfile.TemporaryDirectory() as tmp:
+                runtime = Runtime(Path(tmp))
+                runtime.call_tool("get_default_cwd", {})
+                runtime.call_tool("read_file", {"path": "missing.txt"})
+                runtime.close()
+        self.assertEqual(sender.events, [])
+
+    def test_error_events_are_capped_and_drops_are_counted(self) -> None:
+        sender = _CapturingSender()
+        with scrubbed_env(), patch.object(telemetry, "_get_sender", lambda: sender):
+            session = SessionTelemetry(permission_mode="safe")
+            session.record_session_start({"name": "cap"}, "2025-11-25")
+            for _ in range(ERROR_EVENTS_PER_SESSION + 5):
+                session.record_tool_call(
+                    "apply_patch", ok=False, error_code="PATCH_CONTEXT_MISMATCH", duration_ms=5, truncated=False
+                )
+            session.finish()
+        errors = [event for event in sender.events if event["event"] == "tool_error"]
+        self.assertEqual(len(errors), ERROR_EVENTS_PER_SESSION)
+        end = next(event for event in sender.events if event["event"] == "session_end")
+        properties = end["properties"]
+        assert isinstance(properties, dict)
+        self.assertEqual(properties["errors_dropped"], 5)
+
+    def test_duration_buckets_and_finish_is_idempotent(self) -> None:
+        sender = _CapturingSender()
+        with scrubbed_env(), patch.object(telemetry, "_get_sender", lambda: sender):
+            session = SessionTelemetry(permission_mode="safe")
+            session.record_session_start(None, "2025-11-25")
+            for duration in (50, 500, 5_000, 50_000):
+                session.record_tool_call("exec_command", ok=True, error_code=None, duration_ms=duration, truncated=True)
+            session.finish()
+            session.finish()
+        summaries = [event for event in sender.events if event["event"] == "tool_summary"]
+        self.assertEqual(len(summaries), 1)
+        properties = summaries[0]["properties"]
+        assert isinstance(properties, dict)
+        for bucket in ("dur_lt_100ms", "dur_lt_1s", "dur_lt_10s", "dur_gte_10s"):
+            self.assertEqual(properties[bucket], 1)
+        self.assertEqual(properties["truncated"], 4)
+        self.assertEqual(len([event for event in sender.events if event["event"] == "session_end"]), 1)
+
+
+class DocumentationDriftTests(unittest.TestCase):
+    def test_documented_schema_matches_emitted_events(self) -> None:
+        doc = (Path(__file__).resolve().parents[1] / "docs" / "telemetry.md").read_text(encoding="utf-8")
+        emitted = {str(event["event"]) for event in _run_probe_session().events}
+        self.assertEqual(emitted, {"session_start", "tool_error", "tool_summary", "session_end"})
+        for name in emitted:
+            self.assertIn(f"`{name}`", doc)
+        self.assertIn(f"max {ERROR_EVENTS_PER_SESSION} per session", doc)
+
+
+class InstallIdTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self._saved = telemetry._install_id
+        telemetry._install_id = None
+
+    def tearDown(self) -> None:
+        telemetry._install_id = self._saved
+
+    def test_install_id_is_random_stable_and_resettable(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            with patch.dict(os.environ, {"HOME": tmp}):
+                first = telemetry.install_id()
+                self.assertEqual(telemetry.install_id(), first)
+                path = Path(tmp) / ".coding-tools-mcp" / "id"
+                self.assertEqual(path.read_text(encoding="utf-8").strip(), first)
+                self.assertEqual(path.stat().st_mode & 0o777, 0o600)
+                self.assertEqual(path.parent.stat().st_mode & 0o777, 0o700)
+
+                telemetry._install_id = None
+                path.unlink()
+                second = telemetry.install_id()
+                self.assertNotEqual(second, first)
+                self.assertEqual(len(second), 32)
+
+
+if __name__ == "__main__":
+    unittest.main()