From 260d291b0f5a2125009435a91c053646141356b8 Mon Sep 17 00:00:00 2001
From: Chris Hendrickson <chris@artificery.dev>
Date: Thu, 23 Apr 2026 15:35:44 -0400
Subject: [PATCH] Compile CLI to .project/toolchain/bin/dew for MCP stdio use

melos run pollutes stdout, breaking the MCP JSON-RPC channel.
The compiled binary has clean stdio and can be pointed at directly
by MCP clients.

- Add melos run compile script (output to .project/toolchain/bin/dew)
- Ignore .project/toolchain/ in .gitignore
- Update mcp.md with compile + client config instructions
- Remove workspace-root bin/ directory

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .gitignore           |  3 +++
 docs/features/mcp.md | 43 ++++++++++++++++++++++++++++++++++++++++++-
 pubspec.yaml         | 16 +++++++++++++---
 3 files changed, 58 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 3a85790..f80ea9b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
 # https://dart.dev/guides/libraries/private-files
 # Created by `dart pub`
 .dart_tool/
+
+# Compiled toolchain binaries
+.project/toolchain/
diff --git a/docs/features/mcp.md b/docs/features/mcp.md
index 2d64e16..e6171b8 100644
--- a/docs/features/mcp.md
+++ b/docs/features/mcp.md
@@ -7,7 +7,7 @@ The Dew Model Context Protocol (MCP) Server is a feature that allows AI agents t
 The MCP feature is split across two packages to keep concerns separate:
 
 - **`packages/core`** defines the `McpToolProvider` interface. Any feature package that wants to expose tools to AI agents implements this interface — without needing to depend on the MCP server itself.
-- **`packages/mcp`** implements the actual server. It collects all registered `McpToolProvider` implementations and serves them over the configured host and port. Only the `cli` package depends on `packages/mcp`; feature packages like `kanban` remain decoupled from the transport layer.
+- **`packages/mcp`** implements the actual server. It collects all registered `McpToolProvider` implementations and serves them over stdio using the [dart\_mcp](https://pub.dev/packages/dart_mcp) package. Only the `cli` package depends on `packages/mcp`; feature packages like `kanban` remain decoupled from the transport layer.
 
 ## Configuration
 
@@ -21,3 +21,44 @@ dew:
 ```
 
 See the [Configuration documentation](../config.md) for full details.
+
+## Running the server
+
+The MCP server uses **stdio transport** — the MCP client launches it as a child process and communicates over stdin/stdout. Because of this, the process must have clean stdout (no decorative output). `melos run` pollutes stdout with its own log lines, which corrupts the JSON-RPC channel.
+
+### Step 1 — Compile to a native binary
+
+```text
+melos run compile
+```
+
+This produces `.project/toolchain/bin/dew` (or `.project/toolchain/bin/dew.exe` on Windows).
+
+### Step 2 — Configure your MCP client
+
+Point your MCP client at the compiled binary. For example, in VS Code's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "dew": {
+      "command": "/absolute/path/to/dew/.project/toolchain/bin/dew",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+The server logs its startup message to **stderr** so it never interferes with the JSON-RPC channel on stdout.
+
+## Available tools
+
+The following tools are registered by the `kanban` package:
+
+| Tool                      | Description                                              |
+| ------------------------- | -------------------------------------------------------- |
+| `kanban_create_ticket`    | Create a new kanban ticket                               |
+| `kanban_list_tickets`     | List tickets, optionally filtered by column or type      |
+| `kanban_get_ticket`       | Get a ticket by ID                                       |
+| `kanban_update_ticket`    | Update one or more fields on an existing ticket          |
+| `kanban_delete_ticket`    | Delete a ticket by ID                                    |
diff --git a/pubspec.yaml b/pubspec.yaml
index 083efb5..6870225 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -30,7 +30,17 @@ melos:
       run: dart format .
     dew:
       description: >-
-        Run the Dew CLI. Pass subcommands and args directly
-        (e.g. melos run dew kanban). Use 'help <command>' for usage
-        (e.g. melos run dew help kanban).
+        Run the Dew CLI via 'dart run' (for development). Pass subcommands and
+        args directly (e.g. melos run dew kanban). Use 'help <command>' for
+        usage (e.g. melos run dew help kanban).
+        NOTE: 'mcp serve' must be run via the compiled binary (see compile
+        script) because melos pollutes stdout, which breaks the stdio MCP
+        transport.
       run: dart run packages/cli/bin/dew.dart
+    compile:
+      description: >-
+        Compile the Dew CLI to a native binary at .project/toolchain/bin/dew
+        (.project/toolchain/bin/dew.exe on Windows). Use the compiled binary to
+        run 'dew mcp serve' from your MCP client config — this keeps stdout
+        clean for the JSON-RPC channel.
+      run: dart compile exe packages/cli/bin/dew.dart -o .project/toolchain/bin/dew