feat(mcp): hscli mcp serve — Model Context Protocol server

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.10.0] - 2026-06-05
+
+### Added
+
+- **MCP server — `hscli mcp serve`.** Run hscli as a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio so AI agents (Claude Desktop, Claude Code, …) drive Help Scout through native tools. One tool per command, generated from the command manifest so it stays in sync.
+  - **Reads by default, writes opt-in.** Only read-only tools are exposed unless started with `--allow-writes`; mutating tools carry MCP `destructiveHint`/`readOnlyHint` annotations so clients can confirm dangerous calls.
+  - Each tool call runs the CLI as a child process (keeping the stdio protocol channel clean) and returns the command's JSON as `structuredContent`. The `api` escape hatch, streaming `conv watch`, and bundled oclif plugin commands are not exposed.
+  - Reuses the existing OS-keychain OAuth token and Docs API key — the server runs as you.
+- New MCP guide with Claude Desktop / Claude Code configuration.
+
 ## [0.9.0] - 2026-06-04
 
 ### Added

README.md

@@ -51,6 +51,9 @@ hscli backup --out ~/hs-backup            # Full account backup (incremental on
 # Docs knowledge base (separate per-user API key: `hscli docs auth` or HSCLI_DOCS_API_KEY)
 hscli docs auth                           # Store your Docs API key in the keychain
 hscli docs article search "refund"        # Search the knowledge base
+
+# Run as an MCP server so AI agents call hscli as native tools (read-only by default)
+hscli mcp serve                           # add --allow-writes to expose mutations
 ```
 
 For CI/CD, use the non-interactive client-credentials flow:
@@ -79,6 +82,7 @@ HSCLI_APP_ID=... HSCLI_APP_SECRET=... hscli auth login --client-credentials
 | `hscli alias`    | `set`, `list`, `unset` — custom command shortcuts                                                                                                                                         |
 | `hscli backup`   | Full account dump with incremental refresh, resume, deletion detection, attachments                                                                                                       |
 | `hscli api`      | Raw API escape hatch: `hscli api GET /v2/conversations` (locked to `api.helpscout.net`)                                                                                                   |
+| `hscli mcp`      | `serve` — run hscli as an MCP server so AI agents call commands as tools (read-only by default; `--allow-writes` to enable mutations)                                                     |
 | `hscli doctor`   | Diagnostic checks                                                                                                                                                                         |
 | `hscli version`  | Version info                                                                                                                                                                              |
 

docs/commands.md

@@ -5,7 +5,7 @@ description: Full command reference for the hscli command-line interface.
 
 <!-- AUTO-GENERATED from the oclif manifest by scripts/gen-commands.mjs — do not edit by hand. -->
 
-Reference for `hscli` v0.9.0 (88 commands). Every command also accepts the global flags `--output table|json|yaml|csv`, `--jq`, `--fields`, `--profile`, `--no-color`, `--verbose`, `--no-retry`, and `--timeout`.
+Reference for `hscli` v0.10.0 (89 commands). Every command also accepts the global flags `--output table|json|yaml|csv`, `--jq`, `--fields`, `--profile`, `--no-color`, `--verbose`, `--no-retry`, and `--timeout`.
 
 ## Top-level
 
@@ -1258,6 +1258,25 @@ hscli mailbox list
 hscli mailbox list --limit 50
 ```
 
+## hscli mcp
+
+### `hscli mcp serve`
+
+Run hscli as a Model Context Protocol (MCP) server over stdio
+
+```
+hscli mcp serve [flags]
+```
+
+- `--allow-writes` — Expose mutating tools (create/update/delete/bulk). Off by default — read-only.
+
+Examples:
+
+```bash
+hscli mcp serve
+hscli mcp serve --allow-writes
+```
+
 ## hscli profile
 
 ### `hscli profile current`