AegisGitea-MCP/docs/raw-api.md

Raw API Dispatch (gitea_request)

gitea_request is a generic escape hatch that can call any Gitea REST endpoint by method and path. It exists for the long tail of the Gitea API that the curated, typed tools do not cover (merging PRs, reviews, writing files, webhooks, branch/tag protections, collaborators, Actions/CI, packages, notifications, and so on).

Prefer the dedicated tools whenever one exists. Use gitea_request only for endpoints they do not cover. It is subject to policy, write-mode, and the sensitive-path denylist described below.

Arguments

Field	Type	Notes
method	enum	GET, HEAD, POST, PUT, PATCH, DELETE (case-insensitive). Any other method is rejected before any network call.
path	string	Gitea REST path. The /api/v1 prefix is optional. A full URL may be supplied — the host and query string are stripped.
query	object	Optional query-string parameters.
body	object	Optional JSON request body. Never logged.

The response is returned in a stable envelope:

{
  "method": "GET",
  "path": "/api/v1/repos/acme/app/pulls/1",
  "write": false,
  "repository": "acme/app",
  "data": { "...": "..." }
}

List responses add count and omitted; oversized objects are returned as a truncated JSON string with "truncated": true. All responses are bounded by MAX_TOOL_RESPONSE_ITEMS / MAX_TOOL_RESPONSE_CHARS.

Two-layer authorization

A single tool surface would normally collapse the granularity of policy.yaml. To preserve it, every call is authorized twice:

1. Central gate (server.py). The registered gitea_request tool name is allowed/denied like any other tool. In service-PAT mode the central gate also parses the target repository from the path and verifies that the signed-in user has permission on that repository before the service PAT is used.
2. Handler gate (raw_tools.py). The handler derives a coarse virtual tool name of the form gitea_request:<METHOD>:<top-path-segment> (for example gitea_request:GET:repos or gitea_request:DELETE:repos) and runs it back through the policy engine with the parsed repository, target path, and a is_write flag (true for any method other than GET/HEAD). This reuses the existing write-mode + write-whitelist enforcement and lets policy.yaml allow or deny raw dispatch per method and per top-level path segment.

Because the policy engine matches tool names by exact set membership (only paths use globbing), the virtual name is deliberately coarse and stable.

Example: lock raw dispatch to reads

tools:
  deny:
    - gitea_request:POST:repos
    - gitea_request:PUT:repos
    - gitea_request:PATCH:repos
    - gitea_request:DELETE:repos

Sensitive-path denylist

Independently of policy.yaml, the handler blocks endpoints that touch an admin or credential surface for every method, including GET (a GET on these already leaks credentials or privileged configuration):

• /admin
• *tokens*
• *secrets*
• *hooks*
• *keys* (and *gpg_keys*)
• applications/oauth2
• actions/runners/registration-token

This denylist lives in the handler and cannot be re-opened from policy.yaml. It is overridden only by setting RAW_API_ALLOW_SENSITIVE=true.

Configuration

Variable	Default	Notes
RAW_API_ENABLED	true	Killswitch. When false, gitea_request refuses every dispatch with a 403.
RAW_API_ALLOW_SENSITIVE	false	When true, the admin/credential denylist is bypassed. Leave false unless you fully understand the exposure.

Security warning

With WRITE_MODE=true, the write whitelist is the only brake on POST/PUT/PATCH/DELETE across the entire Gitea API surface reachable by gitea_request. Any write method against a whitelisted repository will be attempted. Keep the whitelist tight, prefer denying the write virtual tool names in policy.yaml, and keep RAW_API_ALLOW_SENSITIVE=false.

Behavioral notes and edge cases

• Full URL supplied instead of a path: only the path is used; the host and query string are discarded (query carries query parameters).
• Path traversal (..): rejected during argument validation (400).
• Unknown / non-HTTP method: rejected during argument validation, before any network call.
• Cross-repo endpoints such as /repos/search and /repos/issues/search are intentionally not treated as repository-scoped, so repository is null for them.
• Non-repository writes such as POST /user/repos or POST /orgs are denied with "write operation requires a repository target". This is the secure default — the per-user permission model is repository-scoped, so there is no repository against which to verify the write. This behavior is intentional and is not worked around.
• Service-PAT mode: non-repository endpoints (for example GET /user/orgs) are denied by the central gate because per-user permission can only be verified against a repository target. Use the dedicated tools for those, or run in OAuth-only mode.