AegisGitea-MCP/docs/api-reference.md

API Reference

HTTP Endpoints

GET /

Returns basic server information. No authentication required.

Response

{
  "name": "AegisGitea MCP",
  "version": "0.1.0",
  "status": "running"
}

---

GET /health

Health check endpoint. No authentication required.

Response

{
  "status": "healthy",
  "gitea_connected": true
}

Returns HTTP 200 when healthy. Returns HTTP 503 when Gitea is unreachable.

---

GET /mcp/tools

Returns the list of available MCP tools. No authentication required (needed for ChatGPT tool discovery).

Response

{
  "tools": [
    {
      "name": "list_repositories",
      "description": "...",
      "inputSchema": { ... }
    }
  ]
}

---

POST /mcp/tool/call

Executes an MCP tool. Authentication required.

Request headers

Authorization: Bearer <api-key>
Content-Type: application/json

Request body

{
  "name": "<tool-name>",
  "arguments": { ... }
}

Response

{
  "content": [
    {
      "type": "text",
      "text": "..."
    }
  ],
  "isError": false
}

On error, isError is true and text contains the error message.

---

GET /mcp/sse

Server-Sent Events stream endpoint. Authentication required. Used for streaming MCP sessions.

---

POST /mcp/sse

Sends a client message over an active SSE session. Authentication required.

---

Authentication

All authenticated endpoints require a bearer token:

Authorization: Bearer <api-key>

Alternatively, the key can be passed as a query parameter (useful for tools that do not support custom headers):

GET /mcp/tool/call?api_key=<api-key>

---

MCP Tools

list_repositories

Lists all Gitea repositories accessible to the bot user.

Arguments: none

Example response text

Found 3 repositories:

1. myorg/backend - Backend API service [Python] ★ 42
2. myorg/frontend - React frontend [TypeScript] ★ 18
3. myorg/infra - Infrastructure as code [HCL] ★ 5

---

get_repository_info

Returns metadata for a single repository.

Arguments

Name	Type	Required	Description
owner	string	Yes	Repository owner (user or organisation)
repo	string	Yes	Repository name

Example response text

Repository: myorg/backend
Description: Backend API service
Language: Python
Stars: 42
Forks: 3
Default branch: main
Private: false
URL: https://gitea.example.com/myorg/backend

---

get_file_tree

Returns the file and directory structure of a repository.

Arguments

Name	Type	Required	Default	Description
owner	string	Yes	—	Repository owner
repo	string	Yes	—	Repository name
ref	string	No	default branch	Branch, tag, or commit SHA
recursive	boolean	No	false	Recursively list all subdirectories

Note: Recursive mode is disabled by default to limit response size. Enable with care on large repositories.

Example response text

File tree for myorg/backend (ref: main):

src/
src/main.py
src/config.py
tests/
tests/test_main.py
README.md
requirements.txt

---

get_file_contents

Returns the contents of a single file.

Arguments

Name	Type	Required	Default	Description
owner	string	Yes	—	Repository owner
repo	string	Yes	—	Repository name
filepath	string	Yes	—	Path to the file within the repository
ref	string	No	default branch	Branch, tag, or commit SHA

Limits

• Files larger than MAX_FILE_SIZE_BYTES (default 1 MB) are rejected.
• Binary files that cannot be decoded as UTF-8 are returned as raw base64.

Example response text

Contents of myorg/backend/src/main.py (ref: main):

import fastapi
...

---

Error Responses

All errors follow this structure:

{
  "content": [
    {
      "type": "text",
      "text": "Error: <description>"
    }
  ],
  "isError": true
}

Common error scenarios:

Scenario	HTTP Status	isError
Missing or invalid API key	401	— (rejected before tool runs)
Rate limited IP address	429	—
Tool not found	404	—
Repository not found in Gitea	200	true
File too large	200	true
Gitea API unavailable	200	true