From 4c07e9500c0889b4dfd56271176e1b07de154d0e Mon Sep 17 00:00:00 2001 From: Simon KP Date: Thu, 26 Mar 2026 00:07:04 +1100 Subject: [PATCH 1/2] chore: deprecate kh serve --mcp in favor of remote HTTP MCP endpoint Mark the serve command as deprecated via cobra's Deprecated field. Users see a warning pointing to: claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp Updated quickstart and serve docs to lead with the remote endpoint. The command still works but prints a deprecation notice. --- README.md | 8 ++++++-- cmd/serve/serve.go | 3 ++- docs/kh_serve.md | 7 ++++++- docs/quickstart.md | 12 ++++++++---- 4 files changed, 22 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0d6f2ac..3ac08ca 100644 --- a/README.md +++ b/README.md @@ -38,11 +38,15 @@ kh protocol list # Browse available protocols ## MCP Server Mode +The recommended way to connect AI assistants to KeeperHub is the remote HTTP endpoint: + ``` -kh serve --mcp +claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp ``` -Starts an MCP server that exposes KeeperHub actions as tools to AI assistants such as Claude Desktop. See [docs/quickstart.md](docs/quickstart.md) for setup instructions. +No local server process required. See [docs/quickstart.md](docs/quickstart.md) for full setup instructions. + +The legacy `kh serve --mcp` stdio mode is still available but deprecated. ## Documentation diff --git a/cmd/serve/serve.go b/cmd/serve/serve.go index 3fb531a..85c4c33 100644 --- a/cmd/serve/serve.go +++ b/cmd/serve/serve.go @@ -24,7 +24,8 @@ All diagnostic output (warnings, errors) is written to stderr. Only valid JSON-RPC 2.0 messages appear on stdout.`, Example: ` # Start an MCP stdio server (for use with Claude, Cursor, etc.) kh serve --mcp`, - Args: cobra.NoArgs, + Deprecated: "Use the remote MCP endpoint instead: claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp", + Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error { isMCP, err := cmd.Flags().GetBool("mcp") if err != nil { diff --git a/docs/kh_serve.md b/docs/kh_serve.md index 5f8444e..ef17364 100644 --- a/docs/kh_serve.md +++ b/docs/kh_serve.md @@ -2,6 +2,12 @@ Start a server +**Deprecated:** Use the remote MCP endpoint instead: + +``` +claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp +``` + ### Synopsis Start a KeeperHub server process. @@ -44,4 +50,3 @@ kh serve [flags] ### SEE ALSO * [kh](kh.md) - KeeperHub CLI - diff --git a/docs/quickstart.md b/docs/quickstart.md index 67741be..511c9d0 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -58,20 +58,24 @@ kh protocol list ## MCP Server Mode -The CLI can act as an [MCP](https://modelcontextprotocol.io) server, exposing KeeperHub actions as tools to AI assistants. +KeeperHub exposes its actions as tools to AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io). -**Start the MCP server:** +**Recommended: remote HTTP endpoint (no local server required):** ``` -kh serve --mcp +claude mcp add --transport http keeperhub https://app.keeperhub.com/mcp ``` **Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json -{ "mcpServers": { "keeperhub": { "command": "kh", "args": ["serve", "--mcp"] } } } +{ "mcpServers": { "keeperhub": { "type": "http", "url": "https://app.keeperhub.com/mcp" } } } ``` Restart Claude Desktop. KeeperHub tools will appear in the tool list. +**Legacy: local stdio server (deprecated):** + +`kh serve --mcp` starts a local MCP stdio server. This mode is deprecated. Prefer the remote HTTP endpoint above. + ## Next Steps - [concepts.md](concepts.md) -- authentication, output formats, configuration From 569df5991a5d412faecbffc01db1dfedd5e9f674 Mon Sep 17 00:00:00 2001 From: Simon KP Date: Thu, 26 Mar 2026 00:17:02 +1100 Subject: [PATCH 2/2] test: remove serve from help output assertions (deprecated commands are hidden) --- cmd/root_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmd/root_test.go b/cmd/root_test.go index a7c11b2..64d4a00 100644 --- a/cmd/root_test.go +++ b/cmd/root_test.go @@ -154,7 +154,7 @@ func TestRootCmdHelpIncludesAllCommands(t *testing.T) { "workflow", "run", "execute", "project", "tag", "org", "action", "protocol", "wallet", "template", "billing", "doctor", - "version", "auth", "config", "serve", "completion", "update", + "version", "auth", "config", "completion", "update", } for _, cmdName := range expectedCommands { assert.True(t, strings.Contains(helpOutput, cmdName),