Improve connect reliability, error messages, and AI agent UX#144
Merged
Improve connect reliability, error messages, and AI agent UX#144
Conversation
- Move success message after health check so `connect` only reports success when the server actually responds. Show a warning with the actual error when the server is unreachable. - Make `isSessionExpiredError` context-aware: bare HTTP 404 is only treated as session expiration when an MCP session was active. During initial connect a 404 now correctly indicates a wrong URL. - Add `enrichErrorMessage` helper that maps common HTTP/network errors (404, redirect, ECONNREFUSED, DNS, timeout, TLS) to actionable messages with the server URL. - Add `isHttpRedirectError` helper for redirect detection. - Update bridge and bridge-manager callers to pass session context. - Add unit tests for all new and updated helpers. https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
When an unknown command is entered (e.g., 'list-tools'), suggest the closest valid command. Uses Levenshtein distance for typos and detects reversed hyphenated names (e.g., 'list-tools' → 'tools-list'). Works in both the main CLI and the interactive shell. https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
When tool calls, prompt results, or resource reads return very large responses, AI agents hit token limits and can't read the full output. Add --max-output <chars> global option that truncates formatted output to the specified character count, with a notice showing total size and how to adjust the limit. https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
Intercept --help on tools-call to display the tool's parameter schema (equivalent to tools-get). Works in both the main CLI and interactive shell. Saves an extra discovery call when exploring tool parameters. https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
Resolve merge conflicts with main (f05538e): - CHANGELOG.md: combine both branches' [Unreleased] entries - tools.ts imports: include both formatToolCallExample (main) and truncateOutput (ours) - index.ts tools-call: keep helpOption(false) from our branch with main's updated descriptions and addHelpText; handle edge case where name is '--help' by showing Commander help Also rename --max-output to --max-chars for clarity (the flag truncates by character count, not bytes). https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
The CI build failed because maxChars was added to CommandOptions but not to the separate HandlerOptions interface in index.ts, which is what getOptionsFromCommand returns. https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
The readme-help test compares mcpc --help output against the README. Adding --max-chars changed the help output, so the README code block needs updating to match. https://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L
Member
Author
|
Thanks @vystrcild for the suggestions |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Addresses 5 of 8 improvement suggestions from the mcpc benchmark sessions (36 errors across 9 sessions). The remaining 3 were already fixed (#4), not applicable (#7), or low-value (#8).
P0: Connect health check + better error messages (#1, #2)
connectnow verifies the server responds before printing success. Previously it printed✓ Session createdbefore the health check, so agents spent 14+ calls debugging connections that never worked. Now shows a warning with the actual error when the server is unreachable.isSessionExpiredErroris now context-aware — bare 404 is only treated as session expiration when an MCP session ID was active. During initial connect, 404 correctly indicates a wrong URL.enrichErrorMessagehelper maps common errors (404, redirect, ECONNREFUSED, DNS, timeout, TLS) to actionable messages with the server URL.P1: "Did you mean?" suggestions (#3)
list-tools→tools-list,get-resources→resources-get.P1: Output truncation (#5)
--max-output <chars>global option truncates large tool/prompt/resource output with a notice showing total size.P3: Inline tool help (#6)
tools-call <tool> --helpnow shows the tool's parameter schema (equivalent totools-get).Test plan
isSessionExpiredErrorwithhadActiveSessioncontext (36 tests)enrichErrorMessageandisHttpRedirectErrorsuggestCommandwith reversed names, typos, case insensitivity (75 parser tests)truncateOutputhttps://claude.ai/code/session_011PpTVfJKv47kZEvNajk46L