# Getting Started

## Prerequisites

- Python 3.10 or higher
- A running Gitea instance
- A Gitea bot user with access to the repositories you want to expose
- `make` (optional but recommended)

## 1. Install

```bash
git clone <repo-url>
cd AegisGitea-MCP

# Install production dependencies
make install

# Or install with dev dependencies (for testing and linting)
make install-dev
```

To install manually without `make`:

```bash
python -m venv venv
source venv/bin/activate        # Linux/macOS
# or: venv\Scripts\activate     # Windows

pip install -e .
# dev: pip install -e ".[dev]"
```

## 2. Create a Gitea Bot User

1. In your Gitea instance, create a dedicated user (e.g. `ai-bot`).
2. Grant that user **read access** to any repositories the AI should be able to see.
3. Generate an API token for the bot user:
   - Go to **User Settings** > **Applications** > **Generate Token**
   - Give it a descriptive name (e.g. `aegis-mcp-token`)
   - Copy the token — you will not be able to view it again.

## 3. Configure

Copy the example environment file and fill in your values:

```bash
cp .env.example .env
```

Minimum required settings in `.env`:

```env
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=<your-bot-user-token>
AUTH_ENABLED=true
MCP_API_KEYS=<your-generated-api-key>
```

See [Configuration](configuration.md) for the full list of settings.

## 4. Generate an API Key

The MCP server requires clients to authenticate with a bearer token. Generate one:

```bash
make generate-key
# or: python scripts/generate_api_key.py
```

Copy the printed key into `MCP_API_KEYS` in your `.env` file.

## 5. Run

```bash
make run
# or: python -m aegis_gitea_mcp.server
```

The server starts on `http://127.0.0.1:8080` by default.

Verify it is running:

```bash
curl http://localhost:8080/health
# {"status": "healthy", ...}
```

## 6. Connect an AI Client

### ChatGPT

Use this single URL in the ChatGPT MCP connector:

```
http://<host>:8080/mcp/sse?api_key=<your-api-key>
```

ChatGPT uses the SSE transport: it opens a persistent GET stream on this URL and sends tool call messages back via POST to the same URL. The `api_key` query parameter is the recommended method because the ChatGPT interface does not support setting custom request headers.

### Other MCP clients

Clients that support custom headers can use:

- **SSE URL:** `http://<host>:8080/mcp/sse`
- **Tool discovery URL:** `http://<host>:8080/mcp/tools` (no auth required)
- **Tool call URL:** `http://<host>:8080/mcp/tool/call`
- **Authentication:** `Authorization: Bearer <your-api-key>`

For a production deployment behind a reverse proxy, see [Deployment](deployment.md).

## Next Steps

- [Configuration](configuration.md) — tune file size limits, rate limiting, log paths
- [API Reference](api-reference.md) — available tools and endpoints
- [Security](security.md) — understand authentication and audit logging
- [Deployment](deployment.md) — Docker and Traefik setup