1492c80fc5
## Summary - Improve tool call error messages across 4 libraries (arcade-core, arcade-tdk, arcade-mcp-server, arcade-serve) so agents can self-correct and Datadog can facet on structured fields - Guard empty error messages, enrich input validation errors with field-level detail, fix `@tool` decorator fallback formatting, surface `additional_prompt_content` in MCP responses, and add structured log extras for Datadog - Addresses the 3 worst error patterns: generic "Error in tool input deserialization", bare `KeyError` values, and empty `FatalToolError` messages **Linear:** TOO-627 **Plan:** `docs/plans/2026-04-08-improve-error-messages-handoff.md` ## Tasks - [ ] Task 1: Guard empty error messages (arcade-core) - [ ] Task 2: Enrich input validation error messages (arcade-core) - [ ] Task 3: Improve `@tool` decorator error fallback (arcade-tdk) - [ ] Task 4: Fix MCP agent-facing error response (arcade-mcp-server) - [ ] Task 5: Add structured log extras in BaseWorker (arcade-serve) - [ ] Task 6: Add structured log extras in MCP server (arcade-mcp-server) ## Test plan - [ ] Each task has dedicated unit tests verifying the new behavior - [ ] `make test` passes after all tasks - [ ] `make check` (ruff + mypy) passes - [ ] Verify the 3 worst error patterns now produce actionable messages 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Medium Risk** > Touches cross-library error formatting and logging behavior used in production tool execution paths; while mostly additive/guardrails, it changes agent-visible messages and Datadog log facets, which could impact client expectations and alerting. > > **Overview** > Improves tool-call error handling across core/runtime, MCP transport, worker transport, and the TDK to make agent-visible failures more actionable while *reducing sensitive-data leakage*. > > In `arcade-core`, empty error messages now get placeholders, `ToolOutputFactory.fail*` defaults blank messages, and input validation errors are rewritten as field-level summaries that intentionally omit rejected values (avoiding Pydantic echo of secrets). The `@tool` fallback in `arcade-tdk` no longer surfaces `str(exception)` to agents; it returns exception *type-only* in `message` while preserving full detail in `developer_message`. > > Adds a shared `build_tool_error_log_extra` helper and updates `arcade-serve` + `arcade-mcp-server` to emit consistent structured WARNING logs (`error_*`, `tool_name`, optional toolkit/version) for Datadog, while MCP error responses now append `additional_prompt_content` and force `structuredContent=None` on failures per spec. Includes extensive new tests and bumps package versions (`arcade-core` 4.6.2, `arcade-tdk` 3.6.1, `arcade-mcp-server` 1.19.3, `arcade-serve` 3.2.3). > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit e5c7ebcaf56176cfbd8e6d1f2b6295352abd0ec0. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| arcade_mcp_server | ||
| Makefile | ||
| pyproject.toml | ||
| README.md | ||
Arcade MCP Server
Arcade MCP (Model Context Protocol) Server enables AI assistants and development tools to interact with your Arcade tools through a standardized protocol. Build, deploy, and integrate MCP servers seamlessly across different AI platforms.
Quick Links
- Quickstart Guide - Get up and running in minutes
- Walkthrough - Learn by example
- API Reference - MCPApp API documentation
Features
- 🚀 FastAPI-like Interface - Simple, intuitive API with
MCPApp - 🔧 Tool Discovery - Automatic discovery of tools in your project
- 🔌 Multiple Transports - Support for stdio and HTTP/SSE
- 🤖 Multi-Client Support - Works with Claude, Cursor, and more
- 📦 Package Integration - Load installed Arcade packages
- 🔐 Built-in Security - Environment-based configuration and secrets
- 🔄 Hot Reload - Development mode with automatic reloading
- 📊 Production Ready - Deploy with Docker, systemd, PM2, or cloud platforms
Getting Started
Installation
pip install arcade-mcp-server
Create Your First Server
from arcade_mcp_server import MCPApp
from typing import Annotated
app = MCPApp(name="my-tools", version="1.0.0")
@app.tool
def greet(name: Annotated[str, "Name to greet"]) -> str:
"""Greet someone by name."""
return f"Hello, {name}!"
if __name__ == "__main__":
app.run()
Run Your Server
# For development
python my_tools.py
# For Claude Desktop
python -m arcade_mcp_server stdio
# For HTTP clients
python -m arcade_mcp_server --host 0.0.0.0 --port 8080
Community
Analytics & Privacy
Arcade MCP Server collects anonymous usage data to help us improve the service and debug issues. We track "MCP server start" events to understand server usage patterns and reliability.
What We Track
When the server starts, we collect the following information:
- Server configuration: transport type (
httporstdio), host, port - Server metadata: tool count, server version
- Runtime environment: Python version, OS type and release
- Timing: device timestamp
- Errors: error messages (if startup fails)
Privacy
- For anonymous users: Events are tracked with an anonymous ID and no user profile is created
- For authenticated users: Events are linked to your account to help us provide better support
- No sensitive data (credentials, tool inputs/outputs, or personal information) is ever collected
Opt Out
To disable usage tracking, set the environment variable ARCADE_USAGE_TRACKING to 0.
License
Arcade MCP Server is open source software licensed under the MIT license.