greenlight-mcp 0.1.0__tar.gz

greenlight_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ai-ward
+
+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.

greenlight_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: greenlight-mcp
+Version: 0.1.0
+Summary: See what your MCP server is actually doing -- a transparent stdio proxy and live trace viewer for the Model Context Protocol.
+License: MIT
+Project-URL: Homepage, https://github.com/ai-ward/greenlight
+Project-URL: Issues, https://github.com/ai-ward/greenlight/issues
+Keywords: mcp,model-context-protocol,debugging,proxy,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: mcp>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+```
+  .-----.
+  |  🔴  |
+  |  🟡  |
+  |  🟢  |
+  '-----'
+   greenlight
+```
+
+# greenlight
+
+See what your MCP server is actually doing.
+
+A transparent stdio proxy for the Model Context Protocol. Point it at
+your real server command instead of running that command directly, and
+it relays every byte exactly as before -- while recording every JSON-RPC
+message to a structured log you can watch live or replay.
+
+Right now, if an MCP integration isn't working, you're debugging blind:
+no visibility into what got sent, what came back, or why a call failed.
+Greenlight exists to fix that.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+(Not yet published to PyPI as `greenlight-mcp` -- install from source for now.)
+
+## Use it
+
+Wherever you'd normally configure a server command, wrap it:
+
+```bash
+greenlight run -- npx -y @some/mcp-server
+```
+
+instead of
+
+```bash
+npx -y @some/mcp-server
+```
+
+Every message that passes through gets logged to `./sessions/`. Watch it:
+
+```bash
+greenlight tail                 # replay the most recent session
+greenlight tail -f              # follow a session that's still running
+greenlight tail path/to/log.jsonl
+```
+
+Trace output is colorized by status: green for a clean success, yellow
+for a slow-but-fine call, red for anything that actually failed --
+including MCP tool-level failures (`result.isError`), not just
+transport-level JSON-RPC errors, which are a different thing and easy to
+miss if you only check for the obvious one. See `notes/day1.md` for why
+that distinction mattered enough to write a whole note about it.
+
+## How it works
+
+`greenlight run` spawns your real server as a subprocess and sits
+between it and the real MCP client, relaying stdin/stdout on two
+threads. Every line is parsed as JSON-RPC, correlated by request id
+(so a response knows its own method name and latency), and written to a
+JSONL file. The one rule the whole thing depends on: nothing but the
+child process's actual bytes ever reaches Greenlight's own stdout --
+logging and UI output only ever go to stderr or to disk. A single stray
+print to stdout would corrupt the protocol stream the real client is
+parsing.
+
+## Status
+
+- [x] `greenlight run` -- transparent proxy, validated end-to-end against
+      a real MCP server (not a mock)
+- [x] `greenlight tail` -- live trace viewer, both static replay and
+      genuine live-follow (verified separately, not assumed)
+- [x] Windows PATH resolution for `npx`-style commands
+- [ ] Tested against a real npx-launched server (so far only validated
+      against a Python fixture server)
+- [ ] HTTP/SSE transport (stdio only for now -- covers the common local
+      MCP server case)
+- [ ] Published to PyPI
+
+## Notes
+
+[`notes/`](notes/) is a running engineering log, not a cleaned-up
+retrospective -- what broke, how it was found, why the fix is what it is.

greenlight_mcp-0.1.0/README.md

@@ -0,0 +1,88 @@
+```
+  .-----.
+  |  🔴  |
+  |  🟡  |
+  |  🟢  |
+  '-----'
+   greenlight
+```
+
+# greenlight
+
+See what your MCP server is actually doing.
+
+A transparent stdio proxy for the Model Context Protocol. Point it at
+your real server command instead of running that command directly, and
+it relays every byte exactly as before -- while recording every JSON-RPC
+message to a structured log you can watch live or replay.
+
+Right now, if an MCP integration isn't working, you're debugging blind:
+no visibility into what got sent, what came back, or why a call failed.
+Greenlight exists to fix that.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+(Not yet published to PyPI as `greenlight-mcp` -- install from source for now.)
+
+## Use it
+
+Wherever you'd normally configure a server command, wrap it:
+
+```bash
+greenlight run -- npx -y @some/mcp-server
+```
+
+instead of
+
+```bash
+npx -y @some/mcp-server
+```
+
+Every message that passes through gets logged to `./sessions/`. Watch it:
+
+```bash
+greenlight tail                 # replay the most recent session
+greenlight tail -f              # follow a session that's still running
+greenlight tail path/to/log.jsonl
+```
+
+Trace output is colorized by status: green for a clean success, yellow
+for a slow-but-fine call, red for anything that actually failed --
+including MCP tool-level failures (`result.isError`), not just
+transport-level JSON-RPC errors, which are a different thing and easy to
+miss if you only check for the obvious one. See `notes/day1.md` for why
+that distinction mattered enough to write a whole note about it.
+
+## How it works
+
+`greenlight run` spawns your real server as a subprocess and sits
+between it and the real MCP client, relaying stdin/stdout on two
+threads. Every line is parsed as JSON-RPC, correlated by request id
+(so a response knows its own method name and latency), and written to a
+JSONL file. The one rule the whole thing depends on: nothing but the
+child process's actual bytes ever reaches Greenlight's own stdout --
+logging and UI output only ever go to stderr or to disk. A single stray
+print to stdout would corrupt the protocol stream the real client is
+parsing.
+
+## Status
+
+- [x] `greenlight run` -- transparent proxy, validated end-to-end against
+      a real MCP server (not a mock)
+- [x] `greenlight tail` -- live trace viewer, both static replay and
+      genuine live-follow (verified separately, not assumed)
+- [x] Windows PATH resolution for `npx`-style commands
+- [ ] Tested against a real npx-launched server (so far only validated
+      against a Python fixture server)
+- [ ] HTTP/SSE transport (stdio only for now -- covers the common local
+      MCP server case)
+- [ ] Published to PyPI
+
+## Notes
+
+[`notes/`](notes/) is a running engineering log, not a cleaned-up
+retrospective -- what broke, how it was found, why the fix is what it is.

greenlight_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "greenlight-mcp"
+version = "0.1.0"
+description = "See what your MCP server is actually doing -- a transparent stdio proxy and live trace viewer for the Model Context Protocol."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "debugging", "proxy", "cli"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+    "rich>=13.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/ai-ward/greenlight"
+Issues = "https://github.com/ai-ward/greenlight/issues"
+
+[project.optional-dependencies]
+dev = [
+    "mcp>=1.0",
+    "pytest>=8.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.scripts]
+greenlight = "greenlight.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

greenlight_mcp-0.1.0/setup.cfg

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

greenlight_mcp-0.1.0/src/greenlight/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

greenlight_mcp-0.1.0/src/greenlight/banner.py

@@ -0,0 +1,22 @@
+"""
+The banner. Purely cosmetic -- never called from run_proxy(), which has
+to keep stdout pure JSON-RPC and shouldn't spam stderr with art on every
+host-triggered startup. This only shows up where a human actually typed
+the command: bare `greenlight` and `greenlight tail`.
+"""
+from rich.console import Console
+
+_LINES = [
+    ("  .-----.", "white"),
+    ("  |  o  |", "bold red"),
+    ("  |  o  |", "bold yellow"),
+    ("  |  o  |", "bold green"),
+    ("  '-----'", "white"),
+]
+
+
+def print_banner(console: Console) -> None:
+    for text, style in _LINES:
+        console.print(text, style=style, highlight=False)
+    console.print("  greenlight", style="bold", highlight=False)
+    console.print()

greenlight_mcp-0.1.0/src/greenlight/cli.py

@@ -0,0 +1,91 @@
+"""
+Greenlight CLI entry point.
+"""
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+from typing import Optional, Sequence
+
+from rich.console import Console
+
+from greenlight.banner import print_banner
+from greenlight.proxy import SESSIONS_DIR, run_proxy
+from greenlight.render import latest_session, tail_file
+
+
+def _resolve(command: list[str]) -> list[str]:
+    """Resolve command[0] through PATH (and PATHEXT on Windows) before
+    handing it to subprocess. Without this, `greenlight run -- npx ...`
+    fails on Windows with a confusing FileNotFoundError, because
+    subprocess with shell=False doesn't apply PATHEXT resolution itself
+    the way a real shell would -- "npx" on Windows is actually npx.cmd."""
+    if not command:
+        return command
+    resolved = shutil.which(command[0])
+    return [resolved, *command[1:]] if resolved else command
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="greenlight",
+        description="See what your MCP server is actually doing.",
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=False)
+
+    run_p = subparsers.add_parser(
+        "run",
+        help="Run an MCP server through the proxy, recording every message.",
+    )
+    run_p.add_argument("--name", default=None, help="session name (defaults to the command's name)")
+    run_p.add_argument(
+        "command", nargs=argparse.REMAINDER,
+        help="the real MCP server command, e.g. -- npx -y @some/mcp-server",
+    )
+
+    tail_p = subparsers.add_parser(
+        "tail",
+        help="View a recorded session's trace -- green for ok, yellow for slow, red for failed.",
+    )
+    tail_p.add_argument(
+        "path", nargs="?", default=None,
+        help="session log to view (defaults to the most recent one in ./sessions)",
+    )
+    tail_p.add_argument(
+        "-f", "--follow", action="store_true",
+        help="keep watching for new messages, like `tail -f` (use this while a session is still running)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.cmd is None:
+        print_banner(Console())
+        parser.print_help()
+        return 0
+
+    if args.cmd == "run":
+        command = list(args.command)
+        if command and command[0] == "--":
+            command = command[1:]
+        if not command:
+            parser.error("no server command given -- e.g. `greenlight run -- npx -y @some/mcp-server`")
+        return run_proxy(_resolve(command), session_name=args.name)
+
+    if args.cmd == "tail":
+        path = Path(args.path) if args.path else latest_session(SESSIONS_DIR)
+        if path is None:
+            parser.error(f"no session logs found in {SESSIONS_DIR} -- run `greenlight run -- ...` first")
+        if not path.exists():
+            parser.error(f"no such file: {path}")
+        print_banner(Console())
+        tail_file(path, follow=args.follow)
+        return 0
+
+    parser.error(f"unknown command {args.cmd!r}")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

greenlight_mcp-0.1.0/src/greenlight/proxy.py

@@ -0,0 +1,175 @@
+"""
+The core of Greenlight: a transparent stdio proxy for MCP servers.
+
+Sits between a real MCP client (Claude Desktop, Claude Code, etc.) and a
+real MCP server. Every byte that would have flowed directly between them
+still does -- this only *also* copies each line into a structured log.
+
+The one rule that matters more than anything else in this file: nothing
+except the child process's own stdout bytes may ever reach our stdout.
+Any UI or logging written there would corrupt the JSON-RPC stream the
+real client is expecting to parse cleanly. Logging goes to a JSONL file
+on disk (stdout is sacred; stderr is not -- the stdio MCP transport never
+uses stderr for protocol traffic, so a status line there is safe).
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+SESSIONS_DIR = Path.cwd() / "sessions"
+
+
+@dataclass
+class _PendingRequest:
+    method: str
+    sent_at: float
+
+
+class ProxySession:
+    """Parses each relayed line as JSON-RPC and writes one structured
+    record per message to a JSONL log. Correlates responses back to the
+    request that caused them (by id) so latency and method name are
+    known even on the response side, where the raw JSON-RPC message
+    alone doesn't carry the method."""
+
+    def __init__(self, log_path: Path):
+        self.log_path = log_path
+        self._pending: dict[object, _PendingRequest] = {}
+        self._lock = threading.Lock()
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        self._log_file = open(log_path, "a", encoding="utf-8", buffering=1)
+
+    def record(self, direction: str, raw_line: str) -> None:
+        line = raw_line.strip()
+        if not line:
+            return
+        ts = time.time()
+        entry: dict = {"ts": ts, "direction": direction}
+
+        try:
+            msg = json.loads(line)
+        except json.JSONDecodeError:
+            # Not every line a server writes to stdout is guaranteed to be
+            # a clean JSON-RPC message in practice (stray prints, partial
+            # writes). Relay already happened upstream of this function --
+            # log it as unparsed rather than dropping it or crashing.
+            entry["parsed"] = False
+            entry["raw"] = line[:500]
+            self._write(entry)
+            return
+
+        entry["parsed"] = True
+        msg_id = msg.get("id")
+        method = msg.get("method")
+
+        if method is not None:
+            entry["type"] = "request" if msg_id is not None else "notification"
+            entry["method"] = method
+            if msg_id is not None:
+                with self._lock:
+                    self._pending[msg_id] = _PendingRequest(method=method, sent_at=ts)
+        else:
+            entry["type"] = "error" if "error" in msg else "result"
+            pending = None
+            if msg_id is not None:
+                with self._lock:
+                    pending = self._pending.pop(msg_id, None)
+            if pending is not None:
+                entry["method"] = pending.method
+                entry["latency_ms"] = round((ts - pending.sent_at) * 1000, 2)
+            if "error" in msg:
+                entry["error"] = msg["error"]
+            elif isinstance(msg.get("result"), dict) and msg["result"].get("isError"):
+                # MCP nests tool-execution failures inside a normal JSON-RPC
+                # "result" (isError: true), separate from transport-level
+                # JSON-RPC errors -- a failed tool call is NOT `"error" in msg`.
+                # Found by testing against a real server whose tool
+                # deliberately raises: it logged as an ordinary success
+                # until this check was added. This is exactly the kind of
+                # failure a trace viewer exists to surface, so it gets its
+                # own flag rather than being indistinguishable from a
+                # normal result.
+                entry["tool_error"] = True
+
+        self._write(entry)
+
+    def _write(self, entry: dict) -> None:
+        self._log_file.write(json.dumps(entry) + "\n")
+        self._log_file.flush()
+
+    def close(self) -> None:
+        self._log_file.close()
+
+
+def _pump(src, dst, on_line: Callable[[str], None]) -> None:
+    """Read lines from src, relay them byte-for-byte to dst immediately,
+    then hand off to on_line for logging. Relay happens first and always
+    -- a logging exception must never be able to break the proxied
+    stream. Runs in its own thread; one of these per direction."""
+    try:
+        for raw in iter(src.readline, b""):
+            try:
+                dst.write(raw)
+                dst.flush()
+            except (BrokenPipeError, OSError):
+                break
+            try:
+                on_line(raw.decode("utf-8", errors="replace"))
+            except Exception:
+                pass
+    finally:
+        try:
+            dst.flush()
+        except (BrokenPipeError, OSError):
+            pass
+
+
+def run_proxy(command: list[str], session_name: Optional[str] = None) -> int:
+    name = session_name or (Path(command[0]).stem if command else "session")
+    log_path = SESSIONS_DIR / f"{name}-{int(time.time())}-{uuid.uuid4().hex[:6]}.jsonl"
+    session = ProxySession(log_path)
+
+    print(f"greenlight: recording to {log_path}", file=sys.stderr)
+    print(f"greenlight: run `greenlight tail {log_path}` in another terminal to watch live",
+          file=sys.stderr)
+
+    proc = subprocess.Popen(
+        command,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=None,  # inherited -- the server's own error output isn't ours to hide
+        bufsize=0,    # no extra buffering beyond the pipe itself; latency matters here
+    )
+    assert proc.stdin is not None and proc.stdout is not None
+
+    t_in = threading.Thread(
+        target=_pump,
+        args=(sys.stdin.buffer, proc.stdin, lambda line: session.record("client->server", line)),
+        daemon=True,
+    )
+    t_out = threading.Thread(
+        target=_pump,
+        args=(proc.stdout, sys.stdout.buffer, lambda line: session.record("server->client", line)),
+        daemon=True,
+    )
+    t_in.start()
+    t_out.start()
+
+    try:
+        returncode = proc.wait()
+    except KeyboardInterrupt:
+        proc.terminate()
+        returncode = proc.wait()
+    finally:
+        t_out.join(timeout=2)
+        session.close()
+
+    return returncode

greenlight_mcp-0.1.0/src/greenlight/render.py

@@ -0,0 +1,82 @@
+"""
+Live trace viewer: renders a JSONL session log as a colorized, scrolling
+trace -- green for a clean success, yellow for a slow-but-fine call, red
+for anything that actually failed (transport-level or tool-level -- see
+proxy.py's ProxySession.record for why those are tracked separately).
+
+Prints incrementally, not as a redrawn table -- an unbounded trace is
+closer to `tail -f` / `kubectl logs -f` than a fixed dashboard, and
+that's the right model here: you want the scrollback, not just the
+current state.
+"""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+SLOW_MS = 500  # a successful call slower than this still gets flagged
+
+console = Console()
+
+
+def _format_entry(entry: dict) -> tuple[str, str]:
+    ts_struct = time.localtime(entry["ts"])
+    ms = int((entry["ts"] % 1) * 1000)
+    timestamp = f"{time.strftime('%H:%M:%S', ts_struct)}.{ms:03d}"
+    arrow = "->" if entry.get("direction") == "client->server" else "<-"
+
+    if not entry.get("parsed", True):
+        raw = entry.get("raw", "")
+        return f"{timestamp}  {arrow}  [unparsed] {raw[:60]}", "dim"
+
+    kind = entry.get("type", "?")
+    method = entry.get("method") or "?"
+
+    if kind in ("request", "notification"):
+        return f"{timestamp}  {arrow}  {method}", "white"
+
+    latency = entry.get("latency_ms")
+    latency_str = f"{latency:>8.2f}ms" if latency is not None else " " * 10
+
+    if entry.get("tool_error"):
+        return f"{timestamp}  {arrow}  {method:<24s} {latency_str}  FAILED (tool error)", "bold red"
+    if kind == "error":
+        message = entry.get("error", {}).get("message", "?")
+        return f"{timestamp}  {arrow}  {method:<24s} {latency_str}  FAILED: {message}", "bold red"
+    if latency is not None and latency > SLOW_MS:
+        return f"{timestamp}  {arrow}  {method:<24s} {latency_str}  ok (slow)", "yellow"
+    return f"{timestamp}  {arrow}  {method:<24s} {latency_str}  ok", "green"
+
+
+def tail_file(path: Path, follow: bool = False) -> None:
+    console.print(f"[bold]watching[/bold] {path}")
+    console.print(f"[dim]-> client to server   <- server to client[/dim]\n")
+
+    with open(path, "r", encoding="utf-8") as f:
+        while True:
+            line = f.readline()
+            if not line:
+                if not follow:
+                    break
+                time.sleep(0.1)
+                continue
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            text, style = _format_entry(entry)
+            console.print(text, style=style)
+
+
+def latest_session(sessions_dir: Path) -> Optional[Path]:
+    if not sessions_dir.exists():
+        return None
+    files = sorted(sessions_dir.glob("*.jsonl"), key=lambda p: p.stat().st_mtime)
+    return files[-1] if files else None

greenlight_mcp-0.1.0/src/greenlight_mcp.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: greenlight-mcp
+Version: 0.1.0
+Summary: See what your MCP server is actually doing -- a transparent stdio proxy and live trace viewer for the Model Context Protocol.
+License: MIT
+Project-URL: Homepage, https://github.com/ai-ward/greenlight
+Project-URL: Issues, https://github.com/ai-ward/greenlight/issues
+Keywords: mcp,model-context-protocol,debugging,proxy,cli
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: mcp>=1.0; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+```
+  .-----.
+  |  🔴  |
+  |  🟡  |
+  |  🟢  |
+  '-----'
+   greenlight
+```
+
+# greenlight
+
+See what your MCP server is actually doing.
+
+A transparent stdio proxy for the Model Context Protocol. Point it at
+your real server command instead of running that command directly, and
+it relays every byte exactly as before -- while recording every JSON-RPC
+message to a structured log you can watch live or replay.
+
+Right now, if an MCP integration isn't working, you're debugging blind:
+no visibility into what got sent, what came back, or why a call failed.
+Greenlight exists to fix that.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+(Not yet published to PyPI as `greenlight-mcp` -- install from source for now.)
+
+## Use it
+
+Wherever you'd normally configure a server command, wrap it:
+
+```bash
+greenlight run -- npx -y @some/mcp-server
+```
+
+instead of
+
+```bash
+npx -y @some/mcp-server
+```
+
+Every message that passes through gets logged to `./sessions/`. Watch it:
+
+```bash
+greenlight tail                 # replay the most recent session
+greenlight tail -f              # follow a session that's still running
+greenlight tail path/to/log.jsonl
+```
+
+Trace output is colorized by status: green for a clean success, yellow
+for a slow-but-fine call, red for anything that actually failed --
+including MCP tool-level failures (`result.isError`), not just
+transport-level JSON-RPC errors, which are a different thing and easy to
+miss if you only check for the obvious one. See `notes/day1.md` for why
+that distinction mattered enough to write a whole note about it.
+
+## How it works
+
+`greenlight run` spawns your real server as a subprocess and sits
+between it and the real MCP client, relaying stdin/stdout on two
+threads. Every line is parsed as JSON-RPC, correlated by request id
+(so a response knows its own method name and latency), and written to a
+JSONL file. The one rule the whole thing depends on: nothing but the
+child process's actual bytes ever reaches Greenlight's own stdout --
+logging and UI output only ever go to stderr or to disk. A single stray
+print to stdout would corrupt the protocol stream the real client is
+parsing.
+
+## Status
+
+- [x] `greenlight run` -- transparent proxy, validated end-to-end against
+      a real MCP server (not a mock)
+- [x] `greenlight tail` -- live trace viewer, both static replay and
+      genuine live-follow (verified separately, not assumed)
+- [x] Windows PATH resolution for `npx`-style commands
+- [ ] Tested against a real npx-launched server (so far only validated
+      against a Python fixture server)
+- [ ] HTTP/SSE transport (stdio only for now -- covers the common local
+      MCP server case)
+- [ ] Published to PyPI
+
+## Notes
+
+[`notes/`](notes/) is a running engineering log, not a cleaned-up
+retrospective -- what broke, how it was found, why the fix is what it is.

greenlight_mcp-0.1.0/src/greenlight_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/greenlight/__init__.py
+src/greenlight/banner.py
+src/greenlight/cli.py
+src/greenlight/proxy.py
+src/greenlight/render.py
+src/greenlight_mcp.egg-info/PKG-INFO
+src/greenlight_mcp.egg-info/SOURCES.txt
+src/greenlight_mcp.egg-info/dependency_links.txt
+src/greenlight_mcp.egg-info/entry_points.txt
+src/greenlight_mcp.egg-info/requires.txt
+src/greenlight_mcp.egg-info/top_level.txt
+tests/test_npx_server.py
+tests/test_proxy_e2e.py
+tests/test_tail_follow.py

greenlight_mcp-0.1.0/src/greenlight_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

greenlight_mcp-0.1.0/src/greenlight_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+greenlight = greenlight.cli:main

greenlight_mcp-0.1.0/src/greenlight_mcp.egg-info/requires.txt

@@ -0,0 +1,7 @@
+rich>=13.0
+
+[dev]
+mcp>=1.0
+pytest>=8.0
+build>=1.0
+twine>=5.0

greenlight_mcp-0.1.0/src/greenlight_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+greenlight

greenlight_mcp-0.1.0/tests/test_npx_server.py

@@ -0,0 +1,75 @@
+"""
+Validates greenlight against a real, third-party, npx-launched MCP
+server -- the official reference server, not something hand-picked to be
+easy. This is the realistic case: most local MCP servers are started via
+`npx`, and on Windows that specifically exercises the PATHEXT resolution
+fix in cli.py (`npx` is actually `npx.cmd`), which the fixture-server
+tests never touched because they invoke `python` directly.
+
+Usage:
+    .venv\\Scripts\\python.exe tests\\test_npx_server.py
+"""
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from mcp import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+ROOT = Path(__file__).resolve().parent.parent
+SESSIONS_DIR = ROOT / "sessions"
+PYTHON = sys.executable
+
+
+async def main() -> None:
+    before = set(SESSIONS_DIR.glob("*.jsonl")) if SESSIONS_DIR.exists() else set()
+
+    # The real-world shape: greenlight wraps `npx`, not a python script.
+    # cli.py's shutil.which() resolution is what makes this work at all
+    # on Windows -- subprocess.Popen(["npx", ...]) with shell=False fails
+    # outright otherwise, because Windows doesn't apply PATHEXT the way a
+    # real shell does.
+    params = StdioServerParameters(
+        command=PYTHON,
+        args=["-m", "greenlight.cli", "run", "--name", "npx-everything", "--",
+              "npx", "-y", "@modelcontextprotocol/server-everything", "stdio"],
+        cwd=str(ROOT),
+    )
+
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            print("initialize: ok (through greenlight, wrapping a real npx server)")
+
+            tools = await session.list_tools()
+            names = {t.name for t in tools.tools}
+            assert "echo" in names and "get-sum" in names, names
+            print(f"list_tools: ok ({len(names)} tools)")
+
+            echo_result = await session.call_tool("echo", {"message": "hello from greenlight"})
+            assert not echo_result.is_error, echo_result
+            print(f"call_tool(echo): ok -> {echo_result.content}")
+
+            sum_result = await session.call_tool("get-sum", {"a": 4, "b": 5})
+            assert not sum_result.is_error, sum_result
+            print(f"call_tool(get-sum): ok -> {sum_result.content}")
+
+    after = set(SESSIONS_DIR.glob("*.jsonl"))
+    new_logs = after - before
+    assert len(new_logs) == 1, f"expected exactly one new session log, got {new_logs}"
+    log_path = new_logs.pop()
+
+    entries = [json.loads(line) for line in log_path.read_text().splitlines() if line.strip()]
+    calls = [e for e in entries if e.get("method") == "tools/call" and e.get("direction") == "server->client"]
+    assert len(calls) == 2, f"expected 2 tools/call results logged, got {len(calls)}"
+    print(f"\nsession log: {log_path}")
+    print(f"logged {len(entries)} entries, {len(calls)} tool call results, "
+          f"none malformed/unparsed: {all(e.get('parsed', True) for e in entries)}")
+
+    print("\nALL CHECKS PASSED -- greenlight works against a real npx-launched "
+          "MCP server on Windows, not just the Python fixture.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

greenlight_mcp-0.1.0/tests/test_proxy_e2e.py

@@ -0,0 +1,93 @@
+"""
+End-to-end validation: drive a real MCP client session THROUGH greenlight
+against a real MCP server, then check both that the protocol worked
+normally (the proxy is transparent) and that the session log correctly
+recorded what happened.
+
+This is deliberately not a unit test with mocks -- the whole point of
+Greenlight is to sit in a real MCP stdio stream without breaking it, so
+the only test that actually proves that is a real session.
+
+Usage:
+    .venv\\Scripts\\python.exe tests\\test_proxy_e2e.py
+"""
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+from mcp import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+ROOT = Path(__file__).resolve().parent.parent
+SESSIONS_DIR = ROOT / "sessions"
+PYTHON = sys.executable
+
+
+async def main() -> None:
+    before = set(SESSIONS_DIR.glob("*.jsonl")) if SESSIONS_DIR.exists() else set()
+
+    # This is the exact shape of command a real MCP host config would use:
+    # instead of running the server directly, run it through `greenlight run`.
+    params = StdioServerParameters(
+        command=PYTHON,
+        args=["-m", "greenlight.cli", "run", "--name", "fixture-e2e", "--",
+              PYTHON, str(ROOT / "tests" / "fixture_server.py")],
+        cwd=str(ROOT),
+    )
+
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            print("initialize: ok")
+
+            tools = await session.list_tools()
+            names = sorted(t.name for t in tools.tools)
+            assert names == ["add", "boom", "slow_echo"], names
+            print(f"list_tools: ok ({names})")
+
+            add_result = await session.call_tool("add", {"a": 2, "b": 3})
+            assert not add_result.is_error, add_result
+            print(f"call_tool(add): ok -> {add_result.content}")
+
+            echo_result = await session.call_tool("slow_echo", {"text": "hi", "delay_ms": 150})
+            assert not echo_result.is_error, echo_result
+            print(f"call_tool(slow_echo): ok -> {echo_result.content}")
+
+            boom_result = await session.call_tool("boom", {})
+            assert boom_result.is_error, "expected boom() to report as an error"
+            print(f"call_tool(boom): ok, correctly reported as error")
+
+    after = set(SESSIONS_DIR.glob("*.jsonl"))
+    new_logs = after - before
+    assert len(new_logs) == 1, f"expected exactly one new session log, got {new_logs}"
+    log_path = new_logs.pop()
+    print(f"\nsession log: {log_path}")
+
+    entries = [json.loads(line) for line in log_path.read_text().splitlines() if line.strip()]
+    print(f"logged {len(entries)} entries")
+
+    methods_seen = {e.get("method") for e in entries if e.get("method")}
+    assert "tools/call" in methods_seen, methods_seen
+    print(f"methods logged: {sorted(m for m in methods_seen if m)}")
+
+    slow_calls = [e for e in entries if e.get("type") == "result" and e.get("latency_ms", 0) > 100]
+    assert slow_calls, "expected at least one result with latency_ms > 100 (the slow_echo call)"
+    print(f"latency tracking: ok (slow_echo measured at {slow_calls[0]['latency_ms']}ms)")
+
+    # boom() fails at the tool level, not the transport level -- MCP nests
+    # that inside a normal JSON-RPC "result" (isError: true), so it must
+    # NOT show up as type == "error" (that's for transport-level failures).
+    # It must show up as tool_error instead.
+    transport_errors = [e for e in entries if e.get("type") == "error"]
+    tool_errors = [e for e in entries if e.get("tool_error")]
+    assert not transport_errors, f"expected no transport-level errors, got {transport_errors}"
+    assert len(tool_errors) == 1, f"expected exactly one tool_error (from boom()), got {tool_errors}"
+    print(f"tool-error detection: ok (boom() correctly flagged as tool_error, "
+          f"not confused with a transport error)")
+
+    print("\nALL CHECKS PASSED -- proxy is transparent and the log is accurate.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

greenlight_mcp-0.1.0/tests/test_tail_follow.py

@@ -0,0 +1,74 @@
+"""
+Verifies tail_file(follow=True) actually picks up new lines as they're
+written, not just replays what already existed when it started. Runs
+the real proxy against the real fixture server, starts following the log
+partway through the session, and checks that later calls show up.
+"""
+import asyncio
+import sys
+import threading
+import time
+from io import StringIO
+from pathlib import Path
+
+from mcp import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+from rich.console import Console
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(ROOT / "src"))
+
+from greenlight.render import tail_file  # noqa: E402
+import greenlight.render as render_module  # noqa: E402
+
+PYTHON = sys.executable
+
+
+async def main() -> None:
+    params = StdioServerParameters(
+        command=PYTHON,
+        args=["-m", "greenlight.cli", "run", "--name", "follow-test", "--",
+              PYTHON, str(ROOT / "tests" / "fixture_server.py")],
+        cwd=str(ROOT),
+    )
+
+    captured = StringIO()
+    render_module.console = Console(file=captured, force_terminal=False)
+
+    follow_thread = None
+    log_path_holder: dict = {}
+
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            await session.call_tool("add", {"a": 1, "b": 1})
+
+            sessions_dir = ROOT / "sessions"
+            candidates = sorted(sessions_dir.glob("follow-test-*.jsonl"), key=lambda p: p.stat().st_mtime)
+            log_path = candidates[-1]
+            log_path_holder["path"] = log_path
+            print(f"following {log_path} while the session is still open")
+
+            follow_thread = threading.Thread(target=tail_file, args=(log_path,), kwargs={"follow": True}, daemon=True)
+            follow_thread.start()
+            time.sleep(0.3)
+
+            before = captured.getvalue()
+            assert "add" not in before or before.count("tools/call") >= 1, "sanity check on initial capture"
+
+            # this call happens AFTER tail_file(follow=True) is already running
+            await session.call_tool("slow_echo", {"text": "live", "delay_ms": 50})
+            time.sleep(0.5)
+
+    output = captured.getvalue()
+    call_count = output.count("tools/call")
+    print(f"\ncaptured {call_count} tools/call lines while following live")
+    assert call_count >= 4, (
+        f"expected at least 4 tools/call lines (2 calls x request+response) "
+        f"captured DURING live follow, got {call_count}\n---\n{output}"
+    )
+    print("PASS: tail -f picks up new messages as they're written, not just at startup")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())