arcade-mcp

Provides a @app.tool decorator API (modeled on FastAPI's @app.get pattern) for registering Python functions as MCP tools without boilerplate. The MCPApp class in arcade_mcp_server/mcp_app.py introspects function signatures, auto-generates JSON schemas from type hints, and registers tools into a ToolCatalog for MCP protocol exposure. Supports async functions, dependency injection via context parameters, and automatic schema validation.

Implements dual transport layer supporting both stdio (for desktop clients like Claude Desktop, Cursor) and HTTP with Server-Sent Events (for web-based clients). The StdioTransport and HTTPSessionManager classes handle protocol framing, message serialization, and bidirectional communication. Allows single MCP server to serve both local IDE integrations and remote web clients without code changes.

Provides built-in usage tracking capturing tool invocations, execution time, errors, and resource consumption. Metrics are collected automatically via middleware and can be exported to monitoring systems (Prometheus, CloudWatch, etc.). Supports custom metrics and event tagging for detailed analysis. Data is aggregated per tool, user, and session.

Implements MCP resources and prompts as first-class abstractions. Resources are static or dynamic data (files, API responses, database records) exposed via MCP. Prompts are reusable instruction templates with parameters. Framework provides decorators (@app.resource, @app.prompt) for registration and automatic schema generation. Clients can discover and invoke resources/prompts alongside tools.

Provides structured error handling with custom exception types (ToolExecutionError, AuthenticationError, ValidationError) that are automatically serialized to MCP error responses. Tools can raise exceptions with user-friendly messages and error codes; framework catches and formats for client consumption. Supports error context (stack traces, debugging info) in development mode.

Implements MCPSettings class (arcade_mcp_server/settings.py) using Pydantic for configuration management. Settings are loaded from environment variables, .env files, or config files with type validation and defaults. Supports environment-specific overrides (dev, staging, prod) and secrets resolution. Configuration is immutable after initialization, preventing runtime changes.

Provides Docker support via Dockerfile templates and cloud deployment via 'arcade deploy' command. Framework generates optimized Docker images with minimal layers, caches dependencies, and supports multi-stage builds. Deployment to Arcade Cloud is one-command (arcade deploy) with automatic scaling, monitoring, and HTTPS. Supports environment variable injection and secrets management in cloud.

Provides a modular toolkit system where pre-built tool collections (e.g., GitHub, Slack, Google Workspace, Stripe) are packaged as importable Python modules. Each toolkit registers its tools via the ToolCatalog, with built-in authentication handlers (OAuth2, API keys) and secrets management. Developers import toolkits and optionally customize or extend them without reimplementing integrations.

Implements a pluggable authentication layer supporting OAuth2, API keys, and custom auth schemes. The ToolAuthorization and authentication provider classes abstract credential handling, allowing tools to request secrets at runtime via context injection. Secrets are resolved from environment variables, secure vaults, or Arcade Cloud, with automatic token refresh for OAuth2 flows.

The arcade CLI (arcade new, arcade mcp, arcade deploy) provides project generation, local server execution, and cloud deployment. 'arcade new' creates a minimal MCP server template with pyproject.toml, tool stubs, and configuration. 'arcade mcp' runs the server locally with hot-reload. 'arcade deploy' packages and deploys to Arcade Cloud with automatic scaling and monitoring. CLI integrates with arcade login for authentication.

The ToolCatalog class (arcade_core/catalog.py) maintains a registry of all available tools with their JSON schemas, input/output types, and metadata. Tools are registered via decorators or programmatically; catalog provides discovery APIs (list_tools, get_tool) and validates tool invocations against schemas. Supports tool versioning, deprecation markers, and categorization for organization.

Provides configuration and integration patterns for connecting MCP servers to desktop IDEs. Claude Desktop integration uses stdio transport and config file (claude_desktop_config.json). Cursor and VS Code integrations use similar patterns with IDE-specific configuration. Framework handles transport setup; developers configure client connection details (server path, arguments) and Arcade handles protocol negotiation.

Implements a middleware system (similar to FastAPI/Express) allowing request/response interception and transformation. Middleware can log tool invocations, enforce rate limits, transform inputs/outputs, or inject context. Middleware is registered via decorator or programmatically and executes in order before/after tool execution. Supports async middleware for non-blocking operations.

Provides session context management allowing tools to maintain state across multiple invocations. Sessions are identified by session ID and can store arbitrary data (user context, conversation history, tool state). Tools access session data via context injection; framework handles session lifecycle (creation, persistence, cleanup). Supports in-memory and persistent backends.

Implements a notification system allowing tools to emit events (progress updates, alerts, notifications) that are streamed to clients. Uses Server-Sent Events (SSE) for HTTP transport and custom message framing for stdio. Tools emit notifications via context API; framework handles delivery and client subscription. Supports event filtering and prioritization.