Return explicit error for tokens lacking scopes

src/aegis_gitea_mcp/server.py

@@ -371,6 +371,24 @@ async def authenticate_and_rate_limit(
                             "scopes_observed": observed_scopes,
                         },
                     )
+                    message = (
+                        "OAuth token is valid but lacks required Gitea API access. "
+                        "Re-authorize this OAuth app in Gitea and try again."
+                    )
+                    if request.url.path.startswith("/mcp/"):
+                        return _oauth_unauthorized_response(
+                            request,
+                            message,
+                            scope=READ_SCOPE,
+                        )
+                    return JSONResponse(
+                        status_code=401,
+                        content={
+                            "error": "Authentication failed",
+                            "message": message,
+                            "request_id": getattr(request.state, "request_id", "-"),
+                        },
+                    )
                 else:
                     probe_result = "pass"
                     _api_scope_cache[token_hash] = now + _API_SCOPE_CACHE_TTL