Merge pull request #80 from keycardai/kamil/detail-token-exchange-errors

feat(keycardai-oauth): detailed error reporting

Author: kamil-keycard

packages/mcp-fastmcp/examples/delegated_access/main.py

@@ -116,8 +116,8 @@ async def list_github_repos(ctx: Context, per_page: int = 5) -> dict:
     if access_context.has_resource_error("https://api.github.com"):
         resource_errors = access_context.get_resource_errors("https://api.github.com")
         return {
-            "error": "Token exchange failed for GitHub API",
-            "resource_errors": resource_errors,
+            "message": "Token exchange failed for GitHub API",
+            "details": resource_errors,
         }
 
     # Check for global errors (e.g., no auth token available)

packages/mcp-fastmcp/pyproject.toml

@@ -10,7 +10,7 @@ dependencies = [
     "pydantic>=2.11.7",
     "pydantic-settings>=2.7.1",
     "httpx>=0.27.2",
-    "keycardai-oauth>=0.6.0",
+    "keycardai-oauth>=0.7.0",
     "fastmcp>=2.14.0,<3.0.0",
     "keycardai-mcp>=0.15.0",
 ]

packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/provider.py

@@ -196,7 +196,7 @@ def has_errors(self) -> bool:
 
     def get_errors(self) -> dict[str, Any] | None:
         """Get global errors if any."""
-        return {"resource_errors": self._resource_errors.copy(), "error": self._error}
+        return {"resources": self._resource_errors.copy(), "error": self._error}
 
     def get_error(self) -> dict[str, str] | None:
         """Get global error if any."""
@@ -689,14 +689,14 @@ async def wrapper(*args, **kwargs) -> Any:
                     if not _user_token:
                         logger.warning(f"No authentication token available for {func.__name__}")
                         _set_error({
-                            "error": "No authentication token available. Please ensure you're properly authenticated.",
+                            "message": "No authentication token available. Please ensure you're properly authenticated.",
                         }, None, _access_context, _ctx)
                         return await _call_func(is_async_func, func, *args, **kwargs)
                     logger.introspect(f"User token retrieved: {get_token_debug_info(_user_token.token)}")
                 except Exception as e:
                     logger.error("Failed to get access token")
                     _set_error({
-                        "error": "Failed to get access token from context. Ensure the Context parameter is properly annotated.",
+                        "message": "Failed to get access token from context. Ensure the Context parameter is properly annotated.",
                         "raw_error": str(e),
                     }, None, _access_context, _ctx)
                     return await _call_func(is_async_func, func, *args, **kwargs)
@@ -734,10 +734,16 @@ async def wrapper(*args, **kwargs) -> Any:
                         logger.introspect(f"Token details for {resource}: {get_token_debug_info(_token_response.access_token)}")
                     except Exception as e:
                         logger.error(f"Token exchange failed for {resource}")
-                        _set_error({
-                            "error": f"Token exchange failed for {resource}: {e}",
-                            "raw_error": str(e),
-                        }, resource, _access_context, _ctx)
+                        _error_dict: dict[str, str] = {
+                            "message": f"Token exchange failed for {resource}",
+                        }
+                        if hasattr(e, "error"):
+                            _error_dict["code"] = e.error
+                        if hasattr(e, "error_description") and e.error_description:
+                            _error_dict["description"] = e.error_description
+                        if not hasattr(e, "error"):
+                            _error_dict["raw_error"] = str(e)
+                        _set_error(_error_dict, resource, _access_context, _ctx)
                         return await _call_func(is_async_func, func, *args, **kwargs)
 
                 logger.debug(f"All token exchanges completed. Setting access context with {len(_access_tokens)} token(s)")

packages/mcp-fastmcp/src/keycardai/mcp/integrations/fastmcp/testing/test_utils.py

@@ -49,8 +49,8 @@ def mock_access_context(
         if has_errors:
             # Return proper error structure matching AccessContext.get_errors()
             mock_access_context_instance.get_errors.return_value = {
-                "resource_errors": {},
-                "error": {"error": error_message}
+                "resources": {},
+                "error": {"message": error_message}
             }
             mock_access_context_instance.access.side_effect = Exception(error_message)
         else:
@@ -66,8 +66,8 @@ def mock_access_method(resource_url):
                         # Resource not granted - set error state and raise exception
                         mock_access_context_instance.has_errors.return_value = True
                         mock_access_context_instance.get_errors.return_value = {
-                            "resource_errors": {
-                                resource_url: {"error": f"Resource not granted: {resource_url}"}
+                            "resources": {
+                                resource_url: {"message": f"Resource not granted: {resource_url}"}
                             },
                             "error": None
                         }
@@ -82,7 +82,7 @@ def mock_access_method(resource_url):
 
             mock_access_context_instance.access = mock_access_method
             mock_access_context_instance.get_errors.return_value = {
-                "resource_errors": {},
+                "resources": {},
                 "error": None
             }
 

packages/mcp-fastmcp/tests/integration/test_grant_decorator.py

@@ -35,12 +35,12 @@ def check_access_context_for_errors(ctx: Context, resource: str = None):
     # Check for global error first
     if access_ctx.has_error():
         error = access_ctx.get_error()
-        return {"error": error["error"], "isError": True}
+        return {"error": error["message"], "isError": True}
 
     # Check for resource-specific error if resource specified
     if resource and access_ctx.has_resource_error(resource):
         error = access_ctx.get_resource_error(resource)
-        return {"error": error["error"], "isError": True}
+        return {"error": error["message"], "isError": True}
 
     return None
 
@@ -97,7 +97,7 @@ def test_function(ctx: Context, user_id: str):
             access_ctx = ctx.get_state("keycardai")
             if access_ctx.has_error():
                 error = access_ctx.get_error()
-                return {"error": error["error"], "isError": True}
+                return {"error": error["message"], "isError": True}
             return f"Hello {user_id}"
 
         mock_context = create_mock_context()
@@ -130,14 +130,14 @@ def test_function(ctx: Context, user_id: str):
             access_ctx = ctx.get_state("keycardai")
             if access_ctx.has_resource_error("https://api.example.com"):
                 error = access_ctx.get_resource_errors("https://api.example.com")
-                return {"error": error["error"], "isError": True}
+                return {"error": error["message"], "isError": True}
             return {"error": "No error", "isError": False, "access_ctx": access_ctx}
 
         mock_context = create_mock_context()
 
         result = await test_function(mock_context, "user123")
 
-        assert result["error"] == "Token exchange failed for https://api.example.com: Exchange failed"
+        assert result["error"] == "Token exchange failed for https://api.example.com"
         assert result["isError"] is True
 
     @pytest.mark.asyncio
@@ -279,19 +279,19 @@ def test_access_context_error_states(self):
         access_context = AccessContext()
 
         # Test global error
-        access_context.set_error({"error": "Global failure"})
+        access_context.set_error({"message": "Global failure"})
         assert access_context.has_error()
         assert access_context.get_status() == "error"
-        assert access_context.get_error()["error"] == "Global failure"
+        assert access_context.get_error()["message"] == "Global failure"
 
         # Test resource error
         access_context = AccessContext()
         access_context.set_resource_error("https://api1.com", {
-            "error": "Resource failed",
+            "message": "Resource failed",
         })
         assert access_context.has_resource_error("https://api1.com")
         assert access_context.get_status() == "partial_error"
-        assert access_context.get_resource_errors("https://api1.com")["error"] == "Resource failed"
+        assert access_context.get_resource_errors("https://api1.com")["message"] == "Resource failed"
 
     def test_access_context_partial_success(self):
         """Test AccessContext with partial success scenario."""
@@ -304,7 +304,7 @@ def test_access_context_partial_success(self):
         access_context = AccessContext()
         access_context.set_token("https://api1.com", token_response)
         access_context.set_resource_error("https://api2.com", {
-            "error": "Failed to get token",
+            "message": "Failed to get token",
         })
 
         # Check status

packages/mcp/README.md

@@ -621,7 +621,7 @@ def multi_resource_tool(access_ctx: AccessContext, ctx: Context):
     # Handle failed resources
     for resource in access_ctx.get_failed_resources():
         error = access_ctx.get_resource_errors(resource)
-        results[resource] = {"error": error["error"]}
+        results[resource] = {"error": error["message"]}
 
     return results
 ```

packages/mcp/examples/delegated_access/main.py

@@ -117,8 +117,8 @@ async def list_github_repos(access_ctx: AccessContext, ctx: Context, per_page: i
     if access_ctx.has_resource_error("https://api.github.com"):
         resource_errors = access_ctx.get_resource_errors("https://api.github.com")
         return {
-            "error": "Token exchange failed for GitHub API",
-            "resource_errors": resource_errors,
+            "message": "Token exchange failed for GitHub API",
+            "details": resource_errors,
         }
 
     # Check for global errors (e.g., no auth token available)

packages/mcp/pyproject.toml

@@ -7,7 +7,7 @@ requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "Keycard", email = "support@keycard.ai" }]
 dependencies = [
-    "keycardai-oauth>=0.6.0",
+    "keycardai-oauth>=0.7.0",
     "mcp>=1.13.1",
     "pydantic>=2.11.7",
     "httpx>=0.27.2",

packages/mcp/src/keycardai/mcp/server/auth/provider.py

@@ -91,7 +91,7 @@ def has_errors(self) -> bool:
 
     def get_errors(self) -> dict[str, Any] | None:
         """Get global errors if any."""
-        return {"resource_errors": self._resource_errors.copy(), "error": self._error}
+        return {"resources": self._resource_errors.copy(), "error": self._error}
 
     def get_error(self) -> dict[str, str] | None:
         """Get global error if any."""
@@ -467,7 +467,7 @@ def my_tool(access_ctx: AccessContext, ctx: Context, user_id: str):
             @provider.grant("https://api.example.com")
             async def my_async_tool(access_ctx: AccessContext, ctx: Context, user_id: str):
                 if access_ctx.has_errors():
-                    return {"error": "Token exchange failed"}
+                    return {"message": "Token exchange failed"}
                 token = access_ctx.access("https://api.example.com").access_token
                 # Async API call
                 return f"Async data for {user_id}"
@@ -606,37 +606,37 @@ async def wrapper(*args, **kwargs) -> Any:
                     _keycardai_auth_info = _extract_auth_info_from_context(*args, **kwargs)
                     if not _keycardai_auth_info:
                         _set_error({
-                            "error": "No request authentication information available. Ensure the provider is correctly configured.",
+                            "message": "No request authentication information available. Ensure the provider is correctly configured.",
                         }, None, _access_ctx)
                         return await _call_func(_is_async_func, func, *args, **kwargs)
 
                     if not _keycardai_auth_info["access_token"]:
                         _set_error({
-                            "error": "No authentication token available. Please ensure you're properly authenticated.",
+                            "message": "No authentication token available. Please ensure you're properly authenticated.",
                         }, None, _access_ctx)
                         return await _call_func(_is_async_func, func, *args, **kwargs)
                 except Exception as e:
                     _set_error({
-                        "error": "Failed to get access token from context. Ensure the Context parameter is properly annotated.",
+                        "message": "Failed to get access token from context. Ensure the Context parameter is properly annotated.",
                         "raw_error": str(e),
                     }, None, _access_ctx)
                     return await _call_func(_is_async_func, func, *args, **kwargs)
                 _client = None
                 if self.enable_multi_zone and not _keycardai_auth_info["zone_id"]:
                     _set_error({
-                        "error": "Zone ID is required for multi-zone configuration but not found in request.",
+                        "message": "Zone ID is required for multi-zone configuration but not found in request.",
                     }, None, _access_ctx)
                     return await _call_func(_is_async_func, func, *args, **kwargs)
                 try:
                     _client = await self._get_or_create_client(_keycardai_auth_info)
                     if _client is None:
                         _set_error({
-                            "error": "OAuth client not available. Server configuration issue.",
+                            "message": "OAuth client not available. Server configuration issue.",
                         }, None, _access_ctx)
                         return await _call_func(_is_async_func, func, *args, **kwargs)
                 except Exception as e:
                     _set_error({
-                        "error": "Failed to initialize OAuth client. Server configuration issue.",
+                        "message": "Failed to initialize OAuth client. Server configuration issue.",
                         "raw_error": str(e),
                     }, None, _access_ctx)
                     return await _call_func(_is_async_func, func, *args, **kwargs)
@@ -666,15 +666,19 @@ async def wrapper(*args, **kwargs) -> Any:
                         _token_response = await _client.exchange_token(_token_exchange_request)
                         _access_tokens[resource] = _token_response
                     except Exception as e:
-                        _error_message = f"Token exchange failed for {resource}"
+                        _error_dict: dict[str, str] = {
+                            "message": f"Token exchange failed for {resource}",
+                        }
                         if self.enable_private_key_identity and _keycardai_auth_info.get("resource_client_id"):
-                            _error_message += f" with client id: {_keycardai_auth_info['resource_client_id']}"
-                        _error_message += f": {e}"
-
-                        _set_error({
-                            "error": _error_message,
-                            "raw_error": str(e),
-                        }, resource, _access_ctx)
+                            _error_dict["message"] += f" with client id: {_keycardai_auth_info['resource_client_id']}"
+                        if hasattr(e, "error"):
+                            _error_dict["code"] = e.error
+                        if hasattr(e, "error_description") and e.error_description:
+                            _error_dict["description"] = e.error_description
+                        if not hasattr(e, "error"):
+                            _error_dict["raw_error"] = str(e)
+
+                        _set_error(_error_dict, resource, _access_ctx)
 
                 # Set successful tokens on the existing access_context (preserves any resource errors)
                 _access_ctx.set_bulk_tokens(_access_tokens)

packages/mcp/src/keycardai/mcp/server/exceptions.py

@@ -367,15 +367,15 @@ def __init__(self, message: str | None = None, *, resource: str | None = None,
             resource_info = f"'{resource}'" if resource else "resource"
 
             if error_type == "global_error":
-                error_msg = error_details.get('error', 'Unknown global error') if error_details else 'Unknown global error'
+                error_msg = error_details.get('message', 'Unknown global error') if error_details else 'Unknown global error'
                 message = (
                     f"Cannot access resource {resource_info} due to global authentication error.\n\n"
                     f"Error: {error_msg}\n\n"
                     "This typically means the initial authentication failed. "
                     "Check your authentication setup and ensure you're properly logged in."
                 )
             elif error_type == "resource_error":
-                error_msg = error_details.get('error', 'Unknown resource error') if error_details else 'Unknown resource error'
+                error_msg = error_details.get('message', 'Unknown resource error') if error_details else 'Unknown resource error'
                 message = (
                     f"Cannot access resource {resource_info} due to resource-specific error.\n\n"
                     f"Error: {error_msg}\n\n"