feat(mcp): add embedded stdio server, npx distribution, and cleaner error UX

Implement the HelpScout MCP surface directly in `hs` via `hs mcp -t stdio`, and map operational inbox leaf commands to MCP tools.

MCP server and tooling:
- add `hs mcp` command with stdio transport and output-mode control
- add JSON-RPC handlers for `initialize`, `ping`, `tools/list`, and `tools/call`
- discover tools dynamically from the inbox command tree (excluding `auth`, `config`, `permissions`)
- build per-tool JSON schemas from Cobra positional args and flags
- execute tool calls by invoking the same `hs` binary for full command parity
- default tool output to json-clean, with `json_full` override support
- normalize stdio framing for Inspector/client compatibility

CLI UX and auth improvements:
- suppress usage on runtime failures; show usage only for parse/shape errors
- centralize `Execute()` error rendering with explicit `Error:` output
- update unauthenticated guidance to env-first with MCP hint and `npx` fallback

Distribution and docs:
- add npm wrapper package `@operator-kit/hs` with binary downloader/launcher
- extend release workflow to publish npm package when `NPM_TOKEN` is set
- set GoReleaser releases to non-draft for public npm binary fetches
- document MCP usage, coverage model, and client configuration in `README.md`

Tests:
- add MCP catalog, execution, server, and error-output tests

Author: rmorse

.github/workflows/release.yml

@@ -30,3 +30,20 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           HOMEBREW_TAP_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+
+      - name: Setup Node
+        if: ${{ secrets.NPM_TOKEN != '' }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Publish npm package
+        if: ${{ secrets.NPM_TOKEN != '' }}
+        working-directory: npm
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          npm version "$VERSION" --no-git-tag-version
+          npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.goreleaser.yml

@@ -31,7 +31,7 @@ checksum:
   name_template: checksums.txt
 
 release:
-  draft: true
+  draft: false
 
 brews:
   - repository:

README.md

@@ -26,6 +26,9 @@ curl -sSL https://raw.githubusercontent.com/operator-kit/hs-cli/main/install.sh
 
 # From source (requires Go)
 go install github.com/operator-kit/hs-cli/cmd/hs@latest
+
+# MCP-first install (no manual binary setup)
+npx -y @operator-kit/hs mcp -t stdio
 ```
 
 ### Build from source
@@ -106,6 +109,70 @@ hs inbox auth logout
 
 The `--format` flag can also be set permanently via the `format` key in the config file, or the `HS_FORMAT` environment variable.
 
+## MCP Server
+
+hs-cli ships an embedded MCP server, exposed as:
+
+```bash
+hs mcp -t stdio
+```
+
+### Coverage model
+
+- One MCP tool per operational `hs inbox ...` leaf command.
+- Tool names are namespaced with prefixes like `helpscout_inbox_conversations_list`.
+- `inbox auth`, `inbox config`, and `inbox permissions` are intentionally excluded.
+- Existing command permissions (`HS_INBOX_PERMISSIONS`) still apply.
+- Existing redaction controls (`pii_mode`, `--unredacted`, `pii_allow_unredacted`) still apply.
+
+### Output contract
+
+- Default MCP tool output mode is clean JSON (`--format json`).
+- Per tool call, set `output_mode: "json_full"` for raw payload shape.
+- Server-wide default can be changed with:
+
+```bash
+hs mcp -t stdio --default-output-mode json_full
+```
+
+### MCP client config examples
+
+Binary install:
+
+```json
+{
+  "mcpServers": {
+    "helpscout": {
+      "command": "hs",
+      "args": ["mcp", "-t", "stdio"],
+      "env": {
+        "HS_CLIENT_ID": "your-client-id",
+        "HS_CLIENT_SECRET": "your-client-secret",
+        "HS_INBOX_PERMISSIONS": "*:read"
+      }
+    }
+  }
+}
+```
+
+npx wrapper:
+
+```json
+{
+  "mcpServers": {
+    "helpscout": {
+      "command": "npx",
+      "args": ["-y", "@operator-kit/hs", "mcp", "-t", "stdio"],
+      "env": {
+        "HS_CLIENT_ID": "your-client-id",
+        "HS_CLIENT_SECRET": "your-client-secret",
+        "HS_INBOX_PERMISSIONS": "*:read"
+      }
+    }
+  }
+}
+```
+
 ## PII Redaction Pipeline
 
 hs-cli includes a production-focused PII redaction system designed for shared terminals, MCP/LLM workflows, and incident-safe exports.
@@ -179,6 +246,16 @@ hs inbox config set --pii-mode off --pii-allow-unredacted=false
 
 Inbox API commands are namespaced under `hs inbox ...`.
 
+### MCP
+
+```bash
+# Start MCP server over stdio
+hs mcp -t stdio
+
+# Use raw json-full output as the MCP default
+hs mcp -t stdio --default-output-mode json_full
+```
+
 ### Config
 
 ```bash
@@ -1135,6 +1212,10 @@ internal/
     store.go                    OS keyring storage
   cmd/
     root.go                     Root command, global flags, PersistentPreRunE
+    mcp.go                      MCP command entrypoint
+    mcp_server.go               Stdio MCP server + JSON-RPC handlers
+    mcp_catalog.go              Dynamic tool catalog from inbox command tree
+    mcp_execute.go              MCP args -> CLI argv execution bridge
     json_clean.go               Per-resource JSON cleanup (json vs json-full)
     auth.go                     login / status / logout
     config.go                   config set / get / path
@@ -1162,6 +1243,10 @@ internal/
     check.go                    GitHub release check with 24h cache
     update.go                   Download, verify, replace binary
   types/                        API response/request structs
+npm/
+  package.json                 npx wrapper package (@operator-kit/hs)
+  bin/install.js               platform binary downloader
+  bin/hs.js                    binary launcher
 ```
 
 ### Build

internal/cmd/attachments.go

@@ -118,9 +118,9 @@ func newConversationAttachmentsCmd() *cobra.Command {
 				dataLen = len(v)
 			}
 			rows := []map[string]string{{
-				"id":       args[1],
-				"filename": asString(payload["filename"]),
-				"mime":     asString(payload["mimeType"]),
+				"id":         args[1],
+				"filename":   asString(payload["filename"]),
+				"mime":       asString(payload["mimeType"]),
 				"data_bytes": strconv.Itoa(dataLen),
 			}}
 			return output.Print(getFormat(), []string{"id", "filename", "mime", "data_bytes"}, rows)

internal/cmd/error_output_test.go

@@ -0,0 +1,89 @@
+package cmd
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestShouldShowUsageForError_UnknownCommand(t *testing.T) {
+	err := errors.New(`unknown command "nope" for "hs inbox"`)
+	assert.True(t, shouldShowUsageForError(err))
+}
+
+func TestExecute_UnknownFlag_PrintsUsage(t *testing.T) {
+	_, buf := setupE2E(t)
+
+	rootCmd.SetArgs([]string{"inbox", "config", "get", "--wat"})
+	err := Execute()
+	require.Error(t, err)
+
+	out := buf.String()
+	assert.Contains(t, out, "Error:")
+	assert.Contains(t, out, "unknown flag")
+	assert.Contains(t, out, "Usage:")
+}
+
+func TestExecute_ArgCountMismatch_PrintsUsage(t *testing.T) {
+	_, buf := setupE2E(t)
+
+	rootCmd.SetArgs([]string{"inbox", "config", "get", "a", "b"})
+	err := Execute()
+	require.Error(t, err)
+
+	out := buf.String()
+	assert.Contains(t, out, "Error:")
+	assert.Contains(t, out, "accepts at most 1 arg(s), received 2")
+	assert.Contains(t, out, "Usage:")
+}
+
+func TestExecute_MissingRequiredFlag_PrintsUsage(t *testing.T) {
+	_, buf := setupE2E(t)
+	t.Setenv("HS_CLIENT_ID", "test-id")
+	t.Setenv("HS_CLIENT_SECRET", "test-secret")
+
+	rootCmd.SetArgs([]string{"inbox", "saved-replies", "create"})
+	err := Execute()
+	require.Error(t, err)
+
+	out := buf.String()
+	assert.Contains(t, out, "Error:")
+	assert.Contains(t, out, "required flag")
+	assert.Contains(t, out, "Usage:")
+}
+
+func TestExecute_RuntimeAuthError_DoesNotPrintUsage(t *testing.T) {
+	_, buf := setupE2E(t)
+	t.Setenv("HS_CLIENT_ID", "")
+	t.Setenv("HS_CLIENT_SECRET", "")
+	apiClient = nil
+
+	rootCmd.SetArgs([]string{"inbox", "customers", "list"})
+	err := Execute()
+	require.Error(t, err)
+
+	out := buf.String()
+	assert.Contains(t, out, "Error:")
+	assert.Contains(t, out, "not authenticated")
+	assert.Contains(t, out, "HS_CLIENT_ID")
+	assert.Contains(t, out, "HS_CLIENT_SECRET")
+	assert.Contains(t, out, "MCP server env")
+	assert.Contains(t, out, "hs inbox auth login")
+	assert.Contains(t, out, "npx -y @operator-kit/hs inbox auth login")
+	assert.NotContains(t, out, "Usage:")
+}
+
+func TestExecute_RuntimeError_DoesNotPrintUsage(t *testing.T) {
+	_, buf := setupE2E(t)
+
+	rootCmd.SetArgs([]string{"inbox", "config", "set", "--pii-mode", "invalid"})
+	err := Execute()
+	require.Error(t, err)
+
+	out := buf.String()
+	assert.Contains(t, out, "Error:")
+	assert.Contains(t, err.Error(), "invalid --pii-mode")
+	assert.NotContains(t, buf.String(), "Usage:")
+}

internal/cmd/json_clean_test.go

@@ -38,16 +38,16 @@ func TestCleanConversation(t *testing.T) {
 	// Dropped
 	assert.Nil(t, result["_links"])
 	assert.Nil(t, result["_embedded"])
-	assert.Nil(t, result["state"])             // "published" dropped
-	assert.Nil(t, result["closedBy"])          // sentinel 0
-	assert.Nil(t, result["closedByUser"])      // sentinel
-	assert.Nil(t, result["createdBy"])         // duplicate
-	assert.Nil(t, result["primaryCustomer"])   // replaced by "customer"
-	assert.Nil(t, result["userUpdatedAt"])     // renamed
-	assert.Nil(t, result["tags"])              // empty
-	assert.Nil(t, result["customFields"])      // empty
-	assert.Nil(t, result["cc"])                // empty
-	assert.Nil(t, result["bcc"])               // empty
+	assert.Nil(t, result["state"])           // "published" dropped
+	assert.Nil(t, result["closedBy"])        // sentinel 0
+	assert.Nil(t, result["closedByUser"])    // sentinel
+	assert.Nil(t, result["createdBy"])       // duplicate
+	assert.Nil(t, result["primaryCustomer"]) // replaced by "customer"
+	assert.Nil(t, result["userUpdatedAt"])   // renamed
+	assert.Nil(t, result["tags"])            // empty
+	assert.Nil(t, result["customFields"])    // empty
+	assert.Nil(t, result["cc"])              // empty
+	assert.Nil(t, result["bcc"])             // empty
 
 	// Transformed
 	assert.Equal(t, "Alice Smith (alice@test.com)", result["customer"])
@@ -90,12 +90,12 @@ func TestCleanConversationWithEmbeddedThreads(t *testing.T) {
 
 	thread := threads[0]
 	assert.Equal(t, "customer", thread["type"])
-	assert.Equal(t, "Hello", thread["body"])                        // HTML→md
-	assert.Equal(t, "Alice S (alice@test.com)", thread["from"])     // flattened
+	assert.Equal(t, "Hello", thread["body"])                    // HTML→md
+	assert.Equal(t, "Alice S (alice@test.com)", thread["from"]) // flattened
 	assert.Nil(t, thread["_links"])
-	assert.Nil(t, thread["customer"])  // duplicate dropped
-	assert.Nil(t, thread["state"])     // "published" dropped
-	assert.Nil(t, thread["action"])    // default dropped
+	assert.Nil(t, thread["customer"]) // duplicate dropped
+	assert.Nil(t, thread["state"])    // "published" dropped
+	assert.Nil(t, thread["action"])   // default dropped
 }
 
 func TestCleanThread(t *testing.T) {
@@ -231,14 +231,14 @@ func TestCleanCustomer(t *testing.T) {
 
 	assert.Nil(t, result["_links"])
 	assert.Nil(t, result["_embedded"])
-	assert.Nil(t, result["background"])   // empty string
-	assert.Nil(t, result["gender"])       // "Unknown"
-	assert.Nil(t, result["draft"])        // false
-	assert.Nil(t, result["photoType"])    // "default"
-	assert.Nil(t, result["photoUrl"])     // dropped
-	assert.Nil(t, result["phones"])       // empty array hoisted then dropped
-	assert.Nil(t, result["chats"])        // empty
-	assert.Nil(t, result["websites"])     // empty
+	assert.Nil(t, result["background"])      // empty string
+	assert.Nil(t, result["gender"])          // "Unknown"
+	assert.Nil(t, result["draft"])           // false
+	assert.Nil(t, result["photoType"])       // "default"
+	assert.Nil(t, result["photoUrl"])        // dropped
+	assert.Nil(t, result["phones"])          // empty array hoisted then dropped
+	assert.Nil(t, result["chats"])           // empty
+	assert.Nil(t, result["websites"])        // empty
 	assert.Nil(t, result["social_profiles"]) // empty
 
 	// Hoisted from _embedded

internal/cmd/mcp.go

@@ -0,0 +1,55 @@
+package cmd
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+)
+
+const (
+	mcpOutputJSON     = "json"
+	mcpOutputJSONFull = "json_full"
+)
+
+func init() {
+	rootCmd.AddCommand(newMCPCmd())
+}
+
+func newMCPCmd() *cobra.Command {
+	var transport string
+	var defaultOutputMode string
+
+	cmd := &cobra.Command{
+		Use:   "mcp",
+		Short: "Start MCP server for HelpScout Inbox tools",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if transport != "stdio" {
+				return fmt.Errorf("unsupported transport: %s (only stdio is supported)", transport)
+			}
+
+			defaultOutputMode = strings.ToLower(strings.TrimSpace(defaultOutputMode))
+			if defaultOutputMode == "json-full" {
+				defaultOutputMode = mcpOutputJSONFull
+			}
+
+			if !isValidMCPOutputMode(defaultOutputMode) {
+				return fmt.Errorf("invalid --default-output-mode: %q (expected json|json_full)", defaultOutputMode)
+			}
+
+			server, err := newMCPServer(defaultOutputMode, cfgPath, debug)
+			if err != nil {
+				return err
+			}
+			return server.serve(cmd.Context())
+		},
+	}
+
+	cmd.Flags().StringVarP(&transport, "transport", "t", "stdio", "MCP transport (stdio)")
+	cmd.Flags().StringVar(&defaultOutputMode, "default-output-mode", mcpOutputJSON, "default output mode for tool calls: json|json_full")
+	return cmd
+}
+
+func isValidMCPOutputMode(mode string) bool {
+	return mode == mcpOutputJSON || mode == mcpOutputJSONFull
+}