fix: surface Gitea auth errors and document the service PAT

Two related issues made the connected MCP server return a bare "Internal
server error" for tools that need real Gitea API access (e.g.
list_repositories), while public-repo-by-path reads worked:

1. Gitea OIDC access tokens only carry openid/profile/email and cannot call
   the repository REST API, so pure-OAuth mode fails for most tools. A service
   PAT (GITEA_TOKEN) is required in practice; per-user permission is still
   enforced before each call, so this does not weaken authorization.
2. The tool handlers caught GiteaError broadly and re-raised it as RuntimeError.
   Because GiteaAuthenticationError/GiteaAuthorizationError subclass GiteaError,
   a clean 401/403 was masked as a generic internal error and the server's
   re-authorization guidance never fired.

Changes:
- read_tools.py / repository.py / write_tools.py: re-raise the auth/authz
  subclasses before the broad GiteaError catch so server.py returns actionable
  guidance instead of a generic 500.
- .env.example + README.md: document GITEA_TOKEN as a least-privilege bot PAT,
  explain why it's needed and that OAuth remains authoritative, and note that
  list_repositories is intentionally unavailable in service-PAT mode.
- tests: assert tool handlers propagate auth errors unwrapped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/aegis_gitea_mcp/tools/read_tools.py

@@ -4,7 +4,12 @@ from __future__ import annotations
 
 from typing import Any
 
-from aegis_gitea_mcp.gitea_client import GiteaClient, GiteaError
+from aegis_gitea_mcp.gitea_client import (
+    GiteaAuthenticationError,
+    GiteaAuthorizationError,
+    GiteaClient,
+    GiteaError,
+)
 from aegis_gitea_mcp.response_limits import limit_items, limit_text
 from aegis_gitea_mcp.tools.arguments import (
     CommitDiffArgs,
@@ -62,6 +67,10 @@ async def search_code_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> dic
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to search code: {exc}") from exc
 
@@ -97,6 +106,10 @@ async def list_commits_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> di
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list commits: {exc}") from exc
 
@@ -135,6 +148,10 @@ async def get_commit_diff_tool(gitea: GiteaClient, arguments: dict[str, Any]) ->
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to get commit diff: {exc}") from exc
 
@@ -181,6 +198,10 @@ async def compare_refs_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> di
             "omitted_commits": commit_omitted,
             "omitted_files": file_omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to compare refs: {exc}") from exc
 
@@ -220,6 +241,10 @@ async def list_issues_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> dic
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list issues: {exc}") from exc
 
@@ -241,6 +266,10 @@ async def get_issue_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> dict[
             "updated_at": issue.get("updated_at", ""),
             "url": issue.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to get issue: {exc}") from exc
 
@@ -280,6 +309,10 @@ async def list_pull_requests_tool(gitea: GiteaClient, arguments: dict[str, Any])
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list pull requests: {exc}") from exc
 
@@ -303,6 +336,10 @@ async def get_pull_request_tool(gitea: GiteaClient, arguments: dict[str, Any]) -
             "updated_at": pull.get("updated_at", ""),
             "url": pull.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to get pull request: {exc}") from exc
 
@@ -332,6 +369,10 @@ async def list_labels_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> dic
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list labels: {exc}") from exc
 
@@ -361,6 +402,10 @@ async def list_tags_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> dict[
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list tags: {exc}") from exc
 
@@ -398,5 +443,9 @@ async def list_releases_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> d
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list releases: {exc}") from exc

src/aegis_gitea_mcp/tools/repository.py

@@ -6,7 +6,12 @@ import base64
 import binascii
 from typing import Any
 
-from aegis_gitea_mcp.gitea_client import GiteaClient, GiteaError
+from aegis_gitea_mcp.gitea_client import (
+    GiteaAuthenticationError,
+    GiteaAuthorizationError,
+    GiteaClient,
+    GiteaError,
+)
 from aegis_gitea_mcp.response_limits import limit_items, limit_text
 from aegis_gitea_mcp.security import sanitize_untrusted_text
 from aegis_gitea_mcp.tools.arguments import (
@@ -51,6 +56,10 @@ async def list_repositories_tool(gitea: GiteaClient, arguments: dict[str, Any])
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to list repositories: {exc}") from exc
 
@@ -78,6 +87,10 @@ async def get_repository_info_tool(gitea: GiteaClient, arguments: dict[str, Any]
             "url": repo_data.get("html_url", ""),
             "clone_url": repo_data.get("clone_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to get repository info: {exc}") from exc
 
@@ -108,6 +121,10 @@ async def get_file_tree_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> d
             "count": len(bounded),
             "omitted": omitted,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to get file tree: {exc}") from exc
 
@@ -155,5 +172,9 @@ async def get_file_contents_tool(gitea: GiteaClient, arguments: dict[str, Any])
             "sha": file_data.get("sha", ""),
             "url": file_data.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to get file contents: {exc}") from exc

src/aegis_gitea_mcp/tools/write_tools.py

@@ -4,7 +4,12 @@ from __future__ import annotations
 
 from typing import Any
 
-from aegis_gitea_mcp.gitea_client import GiteaClient, GiteaError
+from aegis_gitea_mcp.gitea_client import (
+    GiteaAuthenticationError,
+    GiteaAuthorizationError,
+    GiteaClient,
+    GiteaError,
+)
 from aegis_gitea_mcp.response_limits import limit_text
 from aegis_gitea_mcp.tools.arguments import (
     AddLabelsArgs,
@@ -34,6 +39,10 @@ async def create_issue_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> di
             "state": issue.get("state", ""),
             "url": issue.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to create issue: {exc}") from exc
 
@@ -56,6 +65,10 @@ async def update_issue_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> di
             "state": issue.get("state", ""),
             "url": issue.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to update issue: {exc}") from exc
 
@@ -78,6 +91,10 @@ async def create_issue_comment_tool(
             "body": limit_text(str(comment.get("body", ""))),
             "url": comment.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to create issue comment: {exc}") from exc
 
@@ -98,6 +115,10 @@ async def create_pr_comment_tool(gitea: GiteaClient, arguments: dict[str, Any])
             "body": limit_text(str(comment.get("body", ""))),
             "url": comment.get("html_url", ""),
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to create PR comment: {exc}") from exc
 
@@ -116,6 +137,10 @@ async def add_labels_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> dict
             "issue_number": parsed.issue_number,
             "labels": label_names or parsed.labels,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to add labels: {exc}") from exc
 
@@ -137,5 +162,9 @@ async def assign_issue_tool(gitea: GiteaClient, arguments: dict[str, Any]) -> di
             "issue_number": parsed.issue_number,
             "assignees": assignees or parsed.assignees,
         }
+    except (GiteaAuthenticationError, GiteaAuthorizationError):
+        # Let auth/authz failures surface so the server returns actionable
+        # re-authorization guidance instead of a generic internal error.
+        raise
     except GiteaError as exc:
         raise RuntimeError(f"Failed to assign issue: {exc}") from exc