256 lines
4.3 KiB
Markdown
256 lines
4.3 KiB
Markdown
# 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` |
|