quietmcp 0.1.0__tar.gz

quietmcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI (quietmcp)
+
+on:
+  push:
+    branches: [main]
+    paths: ["projects/quietmcp/**"]
+  pull_request:
+    paths: ["projects/quietmcp/**"]
+
+defaults:
+  run:
+    working-directory: projects/quietmcp
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        # quietmcp claims no OS restriction; verify the example/launch scripts run
+        # under Windows' default cp1252 console (where naive Unicode prints crash).
+        include:
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Run tests
+        run: pytest
+      - name: Run the example
+        run: python examples/quickstart.py
+      - name: Smoke-test launch scripts
+        env:
+          NO_PAUSE: "1"
+        run: |
+          python launch/demo-walkthrough.py
+          pip install rich   # only needed to render the demo image, not to use quietmcp
+          python launch/make_demo_svg.py

quietmcp-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Test / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

quietmcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/), and this project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-06-13
+
+### Added
+- `safe_print(...)` — a `print()` drop-in that writes to **stderr**, so it can't
+  corrupt an MCP stdio server's JSON-RPC stream.
+- `get_logger(name, *, level, stream, file, json, trace)` — a logger that writes to
+  stderr/a file (never stdout), sets `propagate=False` (so records can't bubble to a
+  root handler aimed at stdout), is idempotent, and **refuses** `stream=sys.stdout`.
+- `install()` / `uninstall()` / `protect_stdout()` — guard `sys.stdout` so stray
+  **text** writes (yours or a dependency's) are redirected to stderr (`"redirect"`),
+  dropped (`"drop"`), or raise `StdoutPollutionError` (`"strict"`). Returns the real
+  stdout for protocol writes; leaves `sys.stdout.buffer` passing through to the real
+  stream, so the MCP SDK's JSON-RPC bytes are untouched.
+- Trace capture + local viewer: `TraceHandler` tees structured records to a JSONL
+  file; `read_trace` / `render_trace` (text) / `render_trace_html` (a self-contained
+  page) read them back. CLI: `python -m quietmcp view trace.jsonl [--level L] [--html PATH]`.
+- Zero-dependency, fully typed, with a runnable `examples/quickstart.py` and a full
+  offline test suite.
+
+### Changed
+- `python -m quietmcp view` fails cleanly with a short stderr message and exit code
+  2 when the trace file is missing or isn't valid JSONL, instead of dumping a raw
+  traceback. (Errors go to stderr — never stdout.)
+
+### Fixed
+- `read_trace` reads with `utf-8-sig`, so a trace written as UTF-8-with-BOM (common
+  from Windows editors/tooling) loads instead of failing with an "Unexpected UTF-8
+  BOM" error. BOM-less UTF-8 is unaffected.
+- The `examples/quickstart.py` and `launch/demo-walkthrough.py` demos reconfigure
+  their own output to UTF-8, so they no longer crash on Windows' default cp1252
+  console when stdout is piped (the protocol stream the library guards is untouched).
+
+### Notes
+- Honest scope: quietmcp has no dependency on any MCP SDK (it just keeps stdout
+  clean for the one you use), and it guards Python-level writes — not raw OS file
+  descriptor 1 (a subprocess or C extension writing to fd 1 needs OS-level
+  redirection).

quietmcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to quietmcp
+
+Thanks for your interest! quietmcp aims to stay **tiny, dependency-free, and
+laser-focused** on one thing: never letting non-protocol output reach an MCP
+server's stdout. Contributions that keep it that way are welcome.
+
+## Dev setup
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+ruff check .
+```
+
+The whole test suite runs **offline** — no network, no MCP server, no subprocess.
+Stream behaviour is tested with in-memory `StringIO`s and pytest's `capsys`.
+
+## Guidelines
+
+- **Zero dependencies.** quietmcp must not depend on any MCP SDK or third-party
+  package; it should compose with whatever the user already has.
+- **Never write to stdout.** Every code path either targets stderr/a file, or
+  passes protocol bytes through the real stdout deliberately. New features must
+  preserve that invariant (and ideally test it with `capsys`).
+- **Fail loud on misuse.** Pointing a logger at stdout, or a stray write in
+  `strict` mode, should raise a clear error — that's the bug class we exist to catch.
+- **Every change ships with tests and docs.**
+
+## Ideas / good first issues
+
+- An OS-level fd-redirection helper (`os.dup2`) for stdout written by subprocesses
+  or C extensions, as an opt-in beyond the Python-level guard.
+- Async-friendly helpers / an example wiring quietmcp into the official `mcp` SDK's
+  `stdio_server`.
+- A `--follow` (tail) mode for `python -m quietmcp view`.
+- Bridging to MCP's own `notifications/message` logging.
+
+Open an issue to discuss before large changes. Be kind; assume good intent.

quietmcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jenil Soni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quietmcp-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: quietmcp
+Version: 0.1.0
+Summary: Keep your MCP server quiet on stdout — safe print/logging and a stdout guard so debug output can't corrupt the JSON-RPC stream.
+Project-URL: Homepage, https://github.com/thejenilsoni/quietmcp
+Project-URL: Issues, https://github.com/thejenilsoni/quietmcp/issues
+Author: Jenil Soni
+License: MIT
+License-File: LICENSE
+Keywords: agents,debugging,json-rpc,llm,logging,mcp,model-context-protocol,stdio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# quietmcp
+
+> Keep your MCP server quiet on stdout — `print()` and log freely without
+> corrupting the JSON-RPC stream.
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+On an MCP **stdio** server, `stdout` *is* the protocol — every byte is part of the
+JSON-RPC stream the client parses. So the most natural thing in the world, a
+`print("got here")`, silently corrupts that stream and the client breaks with a
+baffling parse error. Worse, a third-party library you don't control can `print` a
+progress bar and take your server down with it.
+
+The fix is mundane — send everything that isn't protocol to **stderr** — but easy
+to get wrong and easy for a dependency to undo. **quietmcp** makes it effortless:
+
+```python
+import quietmcp
+
+real_stdout = quietmcp.install()              # stray writes to stdout now go to stderr
+log = quietmcp.get_logger("my-server")        # logs to stderr, never stdout
+log.info("server starting")
+quietmcp.safe_print("debug: tool called")     # print(), but safe
+
+# hand the REAL stdout to your MCP transport for JSON-RPC:
+run_stdio_server(stdout=real_stdout)
+```
+
+Now nothing — your code or your dependencies — can poison the protocol with a stray
+text write.
+
+---
+
+## Install
+
+```bash
+pip install quietmcp
+```
+
+Zero dependencies, pure standard library.
+
+## The three pieces
+
+### 1. `safe_print` — `print()` that goes to stderr
+
+```python
+from quietmcp import safe_print
+safe_print("about to call tool", tool_name)   # identical to print(), but on stderr
+```
+
+### 2. `get_logger` — a logger that can't reach stdout
+
+```python
+log = quietmcp.get_logger("my-server", level=logging.DEBUG,
+                          file="server.log", json=False, trace="trace.jsonl")
+```
+
+It logs to **stderr** (or a file), and — critically — sets `propagate=False` so your
+records never bubble up to a root logger whose handler might be pointed at stdout.
+It's idempotent, so calling it again with the same name won't stack duplicate
+handlers. Pass `stream=sys.stdout` and it refuses with a clear error: that's the bug
+it exists to prevent.
+
+### 3. `install()` — guard stdout against *everything*
+
+The piece that saves you from libraries you don't control. `install()` replaces
+`sys.stdout` with a guard and returns the real stream:
+
+```python
+real_stdout = quietmcp.install(mode="redirect")   # default: stray writes -> stderr
+```
+
+| mode | a stray `print()` to stdout… |
+|------|------------------------------|
+| `"redirect"` (default) | is written to stderr instead (you still see it) |
+| `"drop"` | is silently discarded |
+| `"strict"` | raises `StdoutPollutionError` — great for catching the offender in tests/CI |
+
+The guard only intercepts **text** writes. The binary layer (`sys.stdout.buffer`) —
+which the Python MCP SDK uses to emit JSON-RPC — passes straight through to the real
+stdout. So protocol output works untouched while `print()`/logging is contained.
+That's exactly the split you want, and it's why `install()` + the MCP SDK just work
+together.
+
+Use it as a context manager when you'd rather scope it (e.g. in tests):
+
+```python
+from quietmcp import protect_stdout, StdoutPollutionError
+
+with protect_stdout("strict") as real_stdout:
+    run_one_request()        # any stray stdout write in here raises
+```
+
+> Note: this guards Python-level writes (`print`, `logging`, `sys.stdout.write`). A
+> subprocess or a C extension writing to fd 1 directly is out of scope — those need
+> OS-level redirection.
+
+## Capture and view a trace
+
+Pass `trace="…"` to `get_logger` (or attach a `TraceHandler`) to tee structured
+records to a JSONL file, then read it back later — your own logs, kept, instead of
+scrolling off stderr:
+
+```python
+log = quietmcp.get_logger("my-server", trace="trace.jsonl")
+log.info("tool call", extra={"tool": "search", "ms": 12})
+```
+
+```bash
+python -m quietmcp view trace.jsonl                  # readable table in the terminal
+python -m quietmcp view trace.jsonl --level WARNING   # filter to WARNING and up
+python -m quietmcp view trace.jsonl --html trace.html # a self-contained browsable page
+```
+
+Programmatically: `read_trace`, `render_trace`, and `render_trace_html`.
+
+## What it does **not** do
+
+- **It doesn't speak MCP.** It has no dependency on any MCP SDK and adds no protocol
+  features — it just keeps your stdout clean so the SDK you already use keeps working.
+- **It doesn't redirect OS file descriptors.** Subprocesses/C libraries writing to
+  fd 1 directly aren't intercepted (that needs `os.dup2`-level redirection).
+- **It's not an observability platform.** The trace viewer is a local convenience,
+  not a hosted dashboard.
+
+## Part of an agent-reliability suite
+
+quietmcp is the first of a small set of framework-agnostic tools for shipping
+agents and agent infrastructure you can trust. More are on the way.
+
+## Contributing
+
+See `CONTRIBUTING.md` in the source distribution. The bar: zero dependencies, never write to
+stdout, and ship tests + docs with every change. MIT licensed.

quietmcp-0.1.0/README.md

@@ -0,0 +1,135 @@
+# quietmcp
+
+> Keep your MCP server quiet on stdout — `print()` and log freely without
+> corrupting the JSON-RPC stream.
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+On an MCP **stdio** server, `stdout` *is* the protocol — every byte is part of the
+JSON-RPC stream the client parses. So the most natural thing in the world, a
+`print("got here")`, silently corrupts that stream and the client breaks with a
+baffling parse error. Worse, a third-party library you don't control can `print` a
+progress bar and take your server down with it.
+
+The fix is mundane — send everything that isn't protocol to **stderr** — but easy
+to get wrong and easy for a dependency to undo. **quietmcp** makes it effortless:
+
+```python
+import quietmcp
+
+real_stdout = quietmcp.install()              # stray writes to stdout now go to stderr
+log = quietmcp.get_logger("my-server")        # logs to stderr, never stdout
+log.info("server starting")
+quietmcp.safe_print("debug: tool called")     # print(), but safe
+
+# hand the REAL stdout to your MCP transport for JSON-RPC:
+run_stdio_server(stdout=real_stdout)
+```
+
+Now nothing — your code or your dependencies — can poison the protocol with a stray
+text write.
+
+---
+
+## Install
+
+```bash
+pip install quietmcp
+```
+
+Zero dependencies, pure standard library.
+
+## The three pieces
+
+### 1. `safe_print` — `print()` that goes to stderr
+
+```python
+from quietmcp import safe_print
+safe_print("about to call tool", tool_name)   # identical to print(), but on stderr
+```
+
+### 2. `get_logger` — a logger that can't reach stdout
+
+```python
+log = quietmcp.get_logger("my-server", level=logging.DEBUG,
+                          file="server.log", json=False, trace="trace.jsonl")
+```
+
+It logs to **stderr** (or a file), and — critically — sets `propagate=False` so your
+records never bubble up to a root logger whose handler might be pointed at stdout.
+It's idempotent, so calling it again with the same name won't stack duplicate
+handlers. Pass `stream=sys.stdout` and it refuses with a clear error: that's the bug
+it exists to prevent.
+
+### 3. `install()` — guard stdout against *everything*
+
+The piece that saves you from libraries you don't control. `install()` replaces
+`sys.stdout` with a guard and returns the real stream:
+
+```python
+real_stdout = quietmcp.install(mode="redirect")   # default: stray writes -> stderr
+```
+
+| mode | a stray `print()` to stdout… |
+|------|------------------------------|
+| `"redirect"` (default) | is written to stderr instead (you still see it) |
+| `"drop"` | is silently discarded |
+| `"strict"` | raises `StdoutPollutionError` — great for catching the offender in tests/CI |
+
+The guard only intercepts **text** writes. The binary layer (`sys.stdout.buffer`) —
+which the Python MCP SDK uses to emit JSON-RPC — passes straight through to the real
+stdout. So protocol output works untouched while `print()`/logging is contained.
+That's exactly the split you want, and it's why `install()` + the MCP SDK just work
+together.
+
+Use it as a context manager when you'd rather scope it (e.g. in tests):
+
+```python
+from quietmcp import protect_stdout, StdoutPollutionError
+
+with protect_stdout("strict") as real_stdout:
+    run_one_request()        # any stray stdout write in here raises
+```
+
+> Note: this guards Python-level writes (`print`, `logging`, `sys.stdout.write`). A
+> subprocess or a C extension writing to fd 1 directly is out of scope — those need
+> OS-level redirection.
+
+## Capture and view a trace
+
+Pass `trace="…"` to `get_logger` (or attach a `TraceHandler`) to tee structured
+records to a JSONL file, then read it back later — your own logs, kept, instead of
+scrolling off stderr:
+
+```python
+log = quietmcp.get_logger("my-server", trace="trace.jsonl")
+log.info("tool call", extra={"tool": "search", "ms": 12})
+```
+
+```bash
+python -m quietmcp view trace.jsonl                  # readable table in the terminal
+python -m quietmcp view trace.jsonl --level WARNING   # filter to WARNING and up
+python -m quietmcp view trace.jsonl --html trace.html # a self-contained browsable page
+```
+
+Programmatically: `read_trace`, `render_trace`, and `render_trace_html`.
+
+## What it does **not** do
+
+- **It doesn't speak MCP.** It has no dependency on any MCP SDK and adds no protocol
+  features — it just keeps your stdout clean so the SDK you already use keeps working.
+- **It doesn't redirect OS file descriptors.** Subprocesses/C libraries writing to
+  fd 1 directly aren't intercepted (that needs `os.dup2`-level redirection).
+- **It's not an observability platform.** The trace viewer is a local convenience,
+  not a hosted dashboard.
+
+## Part of an agent-reliability suite
+
+quietmcp is the first of a small set of framework-agnostic tools for shipping
+agents and agent infrastructure you can trust. More are on the way.
+
+## Contributing
+
+See `CONTRIBUTING.md` in the source distribution. The bar: zero dependencies, never write to
+stdout, and ship tests + docs with every change. MIT licensed.

quietmcp-0.1.0/RELEASE_READINESS.md

@@ -0,0 +1,92 @@
+# quietmcp — Release Readiness (v0.1.0)
+
+**Date:** 2026-06-13 · **Verdict: GO (publish-ready)** — pending only Jenil's
+go-ahead + PyPI credentials.
+
+This is a fresh re-assessment run on **Windows 11 / Python 3.13** (the prior pass,
+2026-06-03, ran in the Linux web container on Python 3.11). The cross-platform run
+surfaced three real Windows footguns, all now fixed in place. quietmcp itself —
+the library — was already solid; the issues were in the demo/launch scripts and one
+file-read encoding.
+
+quietmcp keeps an MCP **stdio** server's stdout clean: a `print()`-safe helper, a
+stdout-refusing logger, a guard that contains stray text writes (yours or a
+dependency's), and a tiny JSONL trace viewer. Zero-dependency core, fully typed.
+
+---
+
+## Verification results (this run, Windows / Py3.13)
+
+| Check | Result |
+|-------|--------|
+| `pip install -e ".[dev]"` | ✅ clean (Python 3.13.13, Windows) |
+| `ruff check .` | ✅ All checks passed |
+| `python -m pytest` | ✅ **36 passed** (was 35; +1 BOM regression test) |
+| `python -m build` | ✅ builds `sdist` + `wheel` in isolated env |
+| Zero-dep import | ✅ `import quietmcp` with no extras; `__version__ == "0.1.0"`, 15 public exports |
+| `py.typed` ships in wheel | ✅ present at `quietmcp/py.typed` |
+| Console-script entry point | ✅ `quietmcp = quietmcp.cli:main` in wheel `entry_points.txt`; `quietmcp --help` works |
+| `examples/quickstart.py` | ✅ runs (incl. **piped stdout** on Windows — see fix #2) |
+| `launch/demo-walkthrough.py` | ✅ runs (incl. piped stdout on Windows — see fix #2) |
+| CLI `view` / `--level` / `--html` / `python -m quietmcp` | ✅ all paths work end-to-end |
+| CLI error paths (missing file, bad JSONL) | ✅ one-line message **to stderr**, exit code 2 |
+| Name availability | ✅ free as of the prior check (**re-verify at publish time** — see below) |
+
+---
+
+## Fixes applied this session (Windows hardening, in place)
+
+1. **`read_trace` rejected UTF-8-with-BOM trace files.** It opened with `utf-8`,
+   which raises "Unexpected UTF-8 BOM" on a BOM'd file (common from Windows
+   editors/tooling — e.g. PowerShell `Out-File -Encoding utf8`). quietmcp's *own*
+   `TraceHandler` writes BOM-less UTF-8, so the self round-trip was fine, but a
+   trace from any BOM-writing tool was unreadable. **Fix:** read with `utf-8-sig`
+   (transparently strips a BOM; identical for BOM-less files). Added a regression
+   test (`test_read_trace_tolerates_utf8_bom`). `src/quietmcp/trace.py`.
+
+2. **The demo scripts crashed on Windows' cp1252 console.** `examples/quickstart.py`
+   and `launch/demo-walkthrough.py` print a `✓` (U+2713); when stdout is a pipe on
+   Windows (CI logs, recordings, this harness), Python falls back to cp1252 and
+   `✓` raises `UnicodeEncodeError` — *after* printing "it worked", so a Windows dev's
+   first run ends in a traceback. **Fix:** each demo best-effort `reconfigure`s its
+   own output to UTF-8 at startup (the protocol stream the library guards is never
+   touched). Root-cause fix, so em-dashes/`✓` render everywhere.
+
+3. **CI never tested Windows.** The matrix was `ubuntu-latest` only, so #1 and #2
+   could never be caught despite `requires-python` declaring no OS restriction.
+   **Fix:** added a `windows-latest` lane (Py3.12) that runs the example + launch
+   scripts under the default console. `.github/workflows/ci.yml`.
+
+All three are committed as code/test/CI/CHANGELOG changes (the "perfect commit"
+discipline). Tests 35 → **36**, still ruff-clean, build still green.
+
+---
+
+## Punch list (non-blocking, post-launch polish)
+
+- **P3 — `install()` mode is sticky.** A second `install("strict")` after
+  `install("redirect")` silently returns the first guard and ignores the new mode
+  (idempotent by design, for "install once at startup"). Consider a docstring note
+  or a `warnings.warn` when `mode` differs from the live guard.
+- **P3 — `get_logger(file=..., stream=...)`** attaches both handlers; with only
+  `file=` it logs to the file alone (no stderr echo). Intended — worth one README
+  sentence so users aren't surprised `file=` silences stderr.
+- **P3 — `render_trace` to a piped console** can still hit cp1252 if a *user's* log
+  message contains non-ASCII (general Python-on-Windows behaviour, not quietmcp's
+  output). Not worth a code change; could be a one-line FAQ note.
+
+None of these block a v0.1.0 launch.
+
+## Pre-publish checklist (when Jenil gives the go-ahead)
+
+1. **Re-verify the name** on PyPI + `github.com/thejenilsoni/quietmcp` (was free at
+   last check; confirm again immediately before upload).
+2. Decide whether the *Unreleased* entries ship as **v0.1.0** (fold them in) or as
+   **v0.1.1** — they're currently staged under *Unreleased*.
+3. Extract `projects/quietmcp/` to its own repo; rewrite sibling links
+   (`../agentvcr/` etc. in README) to absolute `github.com/thejenilsoni/...` URLs.
+4. `python -m build` → `twine check dist/*` → `twine upload` (twine not installed
+   here; needs a PyPI token — **do not upload without Jenil's go-ahead**).
+5. Record the killer demo (noisy dep `print()`s mid-request, JSON-RPC stays clean)
+   per `launch/recording-guide.md`. Consider co-launching with `mcplens` as an
+   "MCP server toolkit."

quietmcp-0.1.0/examples/quickstart.py

@@ -0,0 +1,82 @@
+"""Show that debug output can't corrupt the MCP protocol stream — offline.
+
+Run me:  python examples/quickstart.py
+
+We simulate one MCP request handler. A rude third-party library `print()`s to
+stdout (which on a real server is the JSON-RPC channel), and we also log and
+safe_print debug info. With quietmcp installed, only the actual protocol response
+reaches stdout; everything else is safely redirected to stderr and captured to a
+trace we then render.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+import quietmcp
+
+
+def noisy_library_call() -> dict:
+    # A dependency that rudely writes to stdout — the classic MCP stream-corrupter.
+    print("LIB: download progress 50%")
+    print("LIB: download progress 100%")
+    return {"temperature_c": 21}
+
+
+def handle_request(real_stdout, log) -> None:
+    log.info("handling tools/call", extra={"tool": "get_weather"})
+    quietmcp.safe_print("DEBUG: validating arguments")  # muscle-memory print(), now safe
+    result = noisy_library_call()
+    log.info("tool succeeded", extra={"result": result})
+    # The ONLY thing that should ever hit stdout: the JSON-RPC response.
+    response = {"jsonrpc": "2.0", "id": 1, "result": result}
+    real_stdout.write(json.dumps(response) + "\n")
+    real_stdout.flush()
+
+
+def main() -> None:
+    # Make the demo's own narration readable on any console (e.g. Windows cp1252),
+    # even when stdout is a pipe. Best-effort; this is the display channel, not the
+    # protocol stream the library protects.
+    for _stream in (sys.stdout, sys.stderr):
+        try:
+            _stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        except (AttributeError, ValueError):
+            pass
+
+    protocol = io.StringIO()        # stands in for the real stdout (the MCP channel)
+    stderr_cap = io.StringIO()      # stands in for stderr
+    trace_path = Path(tempfile.gettempdir()) / "quietmcp-demo.jsonl"
+    trace_path.unlink(missing_ok=True)
+
+    saved_out, saved_err = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = protocol, stderr_cap
+    try:
+        real_stdout = quietmcp.install(to=stderr_cap)   # guard stdout; stray writes -> stderr
+        log = quietmcp.get_logger("demo", stream=stderr_cap, trace=str(trace_path))
+        handle_request(real_stdout, log)
+    finally:
+        quietmcp.uninstall()
+        sys.stdout, sys.stderr = saved_out, saved_err
+
+    print("=== stdout — the JSON-RPC channel (must be protocol ONLY) ===")
+    print(protocol.getvalue().strip())
+    print("\n=== stderr — debug + the noisy library, safely redirected ===")
+    print(stderr_cap.getvalue().strip())
+
+    # Prove the protocol stream was never polluted.
+    assert "LIB:" not in protocol.getvalue()
+    assert "DEBUG:" not in protocol.getvalue()
+    assert json.loads(protocol.getvalue())["result"] == {"temperature_c": 21}
+
+    print("\n=== captured trace (python -m quietmcp view ...) ===")
+    print(quietmcp.render_trace(quietmcp.read_trace(trace_path)))
+    print("\nstdout stayed clean — the protocol survived a noisy dependency. ✓")
+
+
+if __name__ == "__main__":
+    main()