# API Reference

## HTTP Endpoints

### `GET /`

Returns basic server information. No authentication required.

**Response**

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

---

### `GET /health`

Health check endpoint. No authentication required.

**Response**

```json
{
  "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**

```json
{
  "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**

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

**Response**

```json
{
  "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:

```json
{
  "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` |