fix(cli): stop serve --mcp from confusing humans — hide it + explain on a TTY (#867)

`codegraph serve --mcp` is the stdio MCP server an AI agent launches for itself
(the installer wires it into every agent's MCP config), not a command a human
runs. Run by hand in a terminal it just hung waiting for JSON-RPC, looking
broken.

- Hide `serve` from `--help` (commander `{ hidden: true }`); it stays fully
  invocable, so agents are unaffected.
- When stdin is an interactive TTY (a person — never the agent's pipe or the
  detached daemon), print what it is and point to `codegraph status` /
  `codegraph daemon`, then exit instead of hanging.
- README: drop `serve --mcp` from the CLI Reference and stop the troubleshooting
  section from telling users to run it; keep the accurate "your agent launches
  it" note.

Verified: agent path intact (22 MCP handshake/daemon tests pass), `serve` absent
from --help, and the TTY path prints the message and exits cleanly.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
2026-06-13 15:18:55 -05:00
committed by GitHub
co-authored by Claude Opus 4.8
parent f7441f2124
commit 64ff7597d0
4 changed files with 31 additions and 3 deletions
+7
View File
@@ -48,6 +48,13 @@ describe('codegraph version affordances', () => {
expect(out).toContain('Commands:');
});
it('hides the internal `serve` command from --help', () => {
// `serve --mcp` is the stdio entry point an AI agent launches for itself,
// not a human command — it must not appear in the listing. (It stays fully
// invocable; the mcp-initialize suite covers that the agent path works.)
expect(run(['--help'])).not.toMatch(/^\s+serve\b/m);
});
it('a trailing `-v` is still the subcommand\'s --verbose, not the version intercept', () => {
// A fresh temp dir outside any indexed project: `index -v` parses `-v` as
// the index command's --verbose, then short-circuits at "not initialized"