MCP Test MCP

--- story_id: "0023" title: "Optional verbose mode for cleaner tool responses" created: "2025-10-13" status: "backlog" dependencies: [] estimated_complexity: "low" tags: ["ux", "usability", "phase2"] --- # Story 0023: Optional verbose mode for cleaner tool responses ## Description Add optional `verbose` parameter to all tools to reduce response verbosity when users only need core results without extensive metadata, timing information, and statistics. This improves readability for simple queries while maintaining full debugging capabilities when needed. ## User Feedback Context From Claude Desktop user testing: > "While the metadata is great for debugging, the responses were quite large. An optional verbose=false parameter could streamline output when you just need the core result." ## Acceptance Criteria - [ ] Add optional `verbose: bool = True` parameter to all tool functions - [ ] When `verbose=False`, responses include only essential data: - Core result/data - Success/error status - Error messages (if applicable) - [ ] When `verbose=True` (default), maintain current behavior: - All metadata - Timing information - Connection statistics - Request details - [ ] Alternative: Environment variable `MCP_TEST_VERBOSE=false` for global control - [ ] Update all tool implementations: - Connection tools (connect, disconnect, status) - Tool testing tools (list_tools, call_tool) - Resource tools (list_resources, read_resource) - Prompt tools (list_prompts, get_prompt, execute_prompt_with_llm) - Utility tools (health_check, ping, echo, add) - [ ] Update documentation with verbose mode examples - [ ] Unit tests for both verbose modes ## Technical Notes **Example implementation:** ```python @mcp.tool() async def connect_to_server( url: str, verbose: bool = True, ctx: Context ) -> dict[str, Any]: """Connect to an MCP server.""" # ... existing logic ... if verbose: return { "success": True, "connection": state.model_dump(mode="json"), "message": f"Successfully connected to {url}", "metadata": { "request_time_ms": round(elapsed_ms, 2), "transport": state.transport, "server_url": state.server_url, }, } else: return { "success": True, "message": f"Connected to {url}", "server_name": state.server_info.get("name") if state.server_info else None, } ``` **Environment variable approach:** ```python verbose_default = os.environ.get("MCP_TEST_VERBOSE", "true").lower() != "false" ``` ## Design Decisions to Consider 1. **Parameter vs Environment Variable**: - Parameter: More flexible, per-call control - Environment: Set once, affects all calls consistently - **Recommendation**: Support both (env var sets default, parameter overrides) 2. **Default Value**: - `verbose=True`: Maintains backward compatibility, no breaking changes - Good for debugging and development 3. **What to Include in Non-Verbose Mode**: - Always include: `success`, core data/result, error messages - Omit: detailed metadata, timing stats, connection statistics ## AI Directives **IMPORTANT**: Mark checklist items as complete `[x]` as you finish them. Update the `status` field in frontmatter when moving between stages. Consider backward compatibility - existing users expect current response format. Verbose mode should be opt-out, not opt-in.