AegisGitea-MCP/docs/raw-api.md

Raw API tool: gitea_api_request

gitea_api_request sends one request to any Gitea API endpoint. It exists for endpoints that are newer than the pinned Gitea 28.1.0 swagger, so a Gitea upgrade does not have to wait for a catalog update. Prefer the generated tools whenever one exists: they have typed arguments, hints and validation.

It is a hand-written tool, not part of the generated catalog, and belongs to the misc domain. It is annotated as not read-only and destructive.

Arguments

Argument	Type	Rules
method	string	GET, POST, PUT, PATCH or DELETE. Required.
path	string	Required. Starts with /, relative to /api/v1, at most 2048 characters.
query	object	Optional. Values are strings, numbers, booleans or arrays of them.
body	any JSON	Optional request body.
sudo	string	Optional Gitea login to act as (site-admin tokens only), as for every tool.

Unknown arguments are rejected. The path is checked: no empty, . or .. segments, and no backslash, ?, #, % or control characters (put parameters in query). A body is never logged or returned. The token, access_token and sudo query parameters are refused, because credentials belong in the identity, not in the URL.

Behaviour

• It goes through the same executor as every generated tool: the identity's token, no redirects, response limits, redaction and secret masking, the result envelope and one audit event.
• There is no allow list of paths and no write classification: with full access, the token's scopes and the identity's Gitea permissions are the limit.
• READ_ONLY=true keeps the tool listed but it accepts only GET.
• TOOLSETS without misc, or DISABLED_TOOLS=gitea_api_request, removes it.
• The audit event records the method and the path, so it is visible which endpoint was called.

Example

{
  "method": "GET",
  "path": "/repos/acme/app/issues",
  "query": {"state": "open", "limit": 10}
}

The result is the usual envelope, with request.path set to the path that was called and the response under data. Content under data is untrusted, as everywhere.