Skip to content

Add JSON output documentation and tool call examples to CLI help#141

Open
jancurn wants to merge 17 commits intomainfrom
claude/document-json-help-output-JjCWF
Open

Add JSON output documentation and tool call examples to CLI help#141
jancurn wants to merge 17 commits intomainfrom
claude/document-json-help-output-JjCWF

Conversation

@jancurn
Copy link
Copy Markdown
Member

@jancurn jancurn commented Apr 6, 2026

Summary

This PR enhances the CLI help system by adding comprehensive documentation for --json output formats across all commands and providing practical usage examples for tool invocation.

Key Changes

  • JSON output documentation: Added .addHelpText() calls to 30+ commands documenting the exact shape of JSON objects returned when using the --json flag. This includes:

    • Global commands: connect, close, oauth-login, oauth-delete, cleanup, grep
    • Session commands: help, tools, tools-list, tools-get, tools-call, tasks-*, resources-*, prompts-*, log-level, ping
    • Each help text specifies the MCP protocol object structure (e.g., MCP InitializeResult, MCP Tool object, etc.)

  • Tool call examples: Implemented formatToolCallExample() function that generates practical usage examples for tools:

    • Shows required parameters first, then fills optional parameters up to 3 total
    • Uses default values from schema when available
    • Falls back to enum first values or reasonable placeholders ("something", 1, true, etc.)
    • Respects schema constraints like minimum for integers
    • Integrated into tools-get command to display example invocation

  • Comprehensive test coverage: Added 5 test cases for formatToolCallExample() covering:

    • Required and optional parameter handling
    • Default value usage
    • Tools with no parameters
    • Enum value selection
    • Session name placeholder fallback

Implementation Details

The exampleValue() helper function intelligently generates placeholder values by checking in order:

  1. Schema default property
  2. Schema enum array (uses first value)
  3. Type-based defaults (string → "something", number → 1, etc.)
  4. Union type handling (e.g., ['string', 'null'])

The formatToolCallExample() function respects the MCP tool schema structure and generates command-line syntax matching the existing tools-call command format with key:=value argument pairs.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc

claude and others added 3 commits April 6, 2026 09:04
@claude
Add --json output docs to help text and tools-call example to tools-get
d24fb7e 
Document the JSON output shape (MCP object types) in --help for all commands
that support --json, so AI agents know what to expect when scripting.

tools-get now shows an example tools-call command with placeholder arguments
derived from the tool's schema (required params first, filling optional up to 3).

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@claude
Fix build:readme sed -i incompatibility on macOS
1eaf4ee 
macOS sed requires a backup extension argument with -i, unlike GNU sed.
Use a temp file + mv instead for cross-platform compatibility.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@jancurn
Writing
1b6dcbe
@jancurn jancurn force-pushed the claude/document-json-help-output-JjCWF branch from 8c99c5c to 15e01cb Compare April 6, 2026 16:53
claude and others added 5 commits April 7, 2026 11:44
@claude
Add --json output docs to help text and tools-call example to tools-get
ef1a4d5 
Document the JSON output shape (MCP object types) in --help for all commands
that support --json, so AI agents know what to expect when scripting.

tools-get now shows an example tools-call command with placeholder arguments
derived from the tool's schema (required params first, filling optional up to 3).

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@claude
Fix build:readme sed -i incompatibility on macOS
e3b97df 
macOS sed requires a backup extension argument with -i, unlike GNU sed.
Use a temp file + mv instead for cross-platform compatibility.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@jancurn @claude
Writing
e21ba29
@claude
Show task support hints in tools-get and tools-call example
7760c67 
Extract formatToolHints() combining annotations + task support, used by
both formatToolLine and formatToolDetail. tools-get now shows task:required
or task:optional in the hints bracket. The tools-call example includes
--task or [--task] accordingly.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@claude
Fix README help block and move changelog entries after v0.2.4 release
47a3c5d 
The v0.2.4 release emptied the README help code block and moved all
changelog entries to the release section. Regenerate the help block
and move unreleased entries to the new [Unreleased] section.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@jancurn jancurn force-pushed the claude/document-json-help-output-JjCWF branch from 15e01cb to 47a3c5d Compare April 7, 2026 11:47
jancurn and others added 9 commits April 7, 2026 14:33
@jancurn
Merge branch 'claude/document-json-help-output-JjCWF' of https://gith…
2494d36 
…ub.com/apify/mcpc into claude/document-json-help-output-JjCWF
@jancurn
Writing
963825a
@claude
Fix --help routing for session sub-commands
facdbb0 
- mcpc @session cmd --help now shows command-specific help instead of
  the top-level help (was intercepted too early in main())
- mcpc @session --help now shows session command list
- Capitalized "Display help" on all sub-commands (was lowercase default)
- Added bold styling to Usage: and other titles in session command help
- mcpc help <cmd> now uses the same styled session program

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@jancurn
Writing
98dc01b
@claude
Improve help text: tools-call args docs, grep consistency, backtick f…
9bb703f 
…ormatting

- tools-call help now shows how to pass arguments (key:=value, inline JSON,
  stdin pipe) with concrete examples and auto-parsing notes
- Session grep help now includes type filters, examples, and --json output,
  matching the top-level grep help
- All JSON output help text uses Markdown backtick formatting for type names
  and shapes (e.g. Array of `Tool` objects: `[{ name, ... }]`)
- Dropped "MCP" prefix from type names (obvious from context)
- Extracted jsonHelp() helper to keep formatting consistent

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@jancurn
Improvements
69e0c18
@claude
Fix extra blank line before JSON output section in multi-section help…
fe83827 
… text

The jsonHelp() helper starts with \n, so when preceded by a blank line
in the template literal, it produced a double blank line. Removed the
redundant blank lines in tools-call, grep (both), connect, and clean.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@claude
Fix session grep usage to show <pattern> before [options]
9c59718 
Match the top-level grep usage ordering by adding explicit .usage()
so both show "grep <pattern> [options]" consistently.

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
@claude
Add MCP schema links to JSON output help text
e03e374 
For commands that return MCP protocol types, add a "Schema:" link to the
respective type definition on the MCP specification page. This helps AI
agents look up the full type definition when needed.

Links added for: InitializeResult, Tool, CallToolResult, Resource,
ReadResourceResult, ResourceTemplate, Prompt, GetPromptResult.
No links for mcpc-specific objects (ping, close, login, etc.) or
experimental types (Task).

https://claude.ai/code/session_01JCmVVCvBbxPUrxy3BcgjCc
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@jancurn @apify-service-account @claude