From fafa480db857d08ef132e47f138d4e8656af806a Mon Sep 17 00:00:00 2001
From: Ashmit Biswas <ashmitbbiswas@gmail.com>
Date: Sun, 31 May 2026 07:10:07 +0530
Subject: [PATCH] fix(mcp): canopy-mcp --help prints usage instead of crashing
 on empty stdin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Running `canopy-mcp --help` from a shell used to fall through to
`mcp.run(transport="stdio")`, which read EOF from a TTY stdin and crashed
with a Pydantic JSON validation error — the first thing a fresh
pipx-installer would see. Add explicit --help / -h handling that prints
usage text and exits, mirroring the existing --version branch.

Bump to 3.1.1, add changelog entry.
---
 CHANGELOG.md             |  8 ++++++++
 src/canopy/__init__.py   |  2 +-
 src/canopy/mcp/server.py | 16 ++++++++++++++++
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a1f11d0..dccd429 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,14 @@ Tracks the Python side (CLI + MCP server). The VSCode extension has its own [vsc
 
 Versions follow semver. Pre-1.0 — minor bumps may add features or break behavior; the README is the source-of-truth contract.
 
+## 3.1.1 — 2026-05-31
+
+### Fixed
+- `canopy-mcp --help` / `-h` now prints usage and exits instead of starting the
+  stdio server and crashing on an empty stdin read. The MCP entry point is not
+  meant to be invoked interactively; the help text says so and points at
+  `canopy setup-agent`.
+
 ## 3.1.0 — 2026-05-30 (Plan 2 — Feature Resume)
 
 ### Added
diff --git a/src/canopy/__init__.py b/src/canopy/__init__.py
index e746bfd..5764033 100644
--- a/src/canopy/__init__.py
+++ b/src/canopy/__init__.py
@@ -1,2 +1,2 @@
 """Canopy — workspace-first development orchestrator."""
-__version__ = "3.1.0"
+__version__ = "3.1.1"
diff --git a/src/canopy/mcp/server.py b/src/canopy/mcp/server.py
index f128c32..c9b6bf1 100644
--- a/src/canopy/mcp/server.py
+++ b/src/canopy/mcp/server.py
@@ -1790,6 +1790,22 @@ def main():
         from .. import __version__
         print(f"canopy-mcp {__version__}")
         return
+    if len(sys.argv) > 1 and sys.argv[1] in ("--help", "-h"):
+        print(
+            "canopy-mcp — Canopy MCP server (stdio JSON-RPC)\n"
+            "\n"
+            "This is a Model Context Protocol server. It is not run interactively;\n"
+            "your MCP-aware client (Claude Code, Claude Desktop, etc.) launches it\n"
+            "and communicates with it over stdio.\n"
+            "\n"
+            "To register canopy with Claude Code, run:\n"
+            "    canopy setup-agent\n"
+            "\n"
+            "Options:\n"
+            "  -V, --version    Print version and exit\n"
+            "  -h, --help       Print this message and exit"
+        )
+        return
     mcp.run(transport="stdio")