Improve error messages with fix instructions (#713)
Improve user-facing error messages to provide actionable fix
instructions, enhancing developer experience and reducing support
queries.
---
Linear Issue:
[TOO-199](https://linear.app/arcadedev/issue/TOO-199/audit-error-messages-for-actionable-fix-instructions)
<a
href="https://cursor.com/background-agent?bcId=bc-e764f9a0-3581-4ced-b34a-2c48f3df1021"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-cursor-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-cursor-light.svg"><img alt="Open in
Cursor"
src="https://cursor.com/open-in-cursor.svg"></picture></a> <a
href="https://cursor.com/agents?id=bc-e764f9a0-3581-4ced-b34a-2c48f3df1021"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/open-in-web-dark.svg"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/open-in-web-light.svg"><img alt="Open in Web"
src="https://cursor.com/open-in-web.svg"></picture></a>
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Enhances MCP server/session error responses with clear, actionable
guidance across JSON-RPC, tools, and resources; updates tests to assert
new messages.
>
> - **Server (`arcade_mcp_server/server.py`)**
> - **Actionable JSON-RPC errors**: Rich messages for `Invalid request`,
`Not initialized`, `Method not found`, and internal errors with
troubleshooting steps.
> - **Tools**:
> - `tools/list`/`tools/call`: Improved internal error messages;
user-facing guidance on failures.
> - Unknown tool: returns detailed fix instructions.
> - Transport restrictions: explicit "Unsupported transport" guidance
for HTTP vs `stdio` with docs link.
> - Auth flow: messages for missing API key, pending authorization (with
`authorization_url`), and authorization errors; includes next steps.
> - Secrets: clear "Missing secret(s)" with `.env`/env-var setup
instructions.
> - **Resources/Prompts**:
> - `resources/list`, `resources/templates/list`, `resources/read`,
`prompts/list`, `prompts/get`: Detailed failure and not-found messages
with guidance.
> - **Session (`arcade_mcp_server/session.py`)**
> - Enhanced internal error response formatting with troubleshooting
steps.
> - **Tests (`libs/tests/arcade_mcp_server/test_server.py`)**
> - Updated assertions to match new, descriptive messages (e.g.,
"Authorization required", "Missing Arcade API key", "Unsupported
transport").
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
97a6db4ec80a1ea9597f3364b6325d47948c94e0. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Eric Gustin <34000337+EricGustin@users.noreply.github.com>
0fc9e21308
