# Getting Started

## Prerequisites

- Python 3.10 or higher
- A running Gitea instance
- A Gitea OAuth2 application for this MCP server
- `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 OAuth2 Application

1. In Gitea, open **User Settings > Applications**.
2. Create an OAuth2 application for AegisGitea-MCP.
3. Set the redirect URI to `https://<host>/oauth/callback`.
4. Copy the client ID and client secret.

## 3. Configure

Copy the example environment file and fill in your values:

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

Minimum OAuth settings in `.env`:

```env
GITEA_URL=https://gitea.example.com
OAUTH_MODE=true
GITEA_OAUTH_CLIENT_ID=<your-gitea-oauth-client-id>
GITEA_OAUTH_CLIENT_SECRET=<your-gitea-oauth-client-secret>
PUBLIC_BASE_URL=https://<host>
OAUTH_STATE_SECRET=<random-32-byte-minimum-secret>
```

`GITEA_TOKEN` is optional. If it is set, use a narrowly scoped service PAT and only grant it repository access you are prepared to expose after per-user authorization checks. If it is not set, Gitea REST calls use the authenticated user's OAuth token directly.

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

## 4. Optional Standard API Key Mode

For non-OAuth deployments, configure `GITEA_TOKEN` and `MCP_API_KEYS`. Generate an API key with:

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

Copy the printed key into `MCP_API_KEYS` in your `.env` file and set `OAUTH_MODE=false`.

## 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

### Claude

In claude.ai, open **Settings > Connectors > Add custom connector** and paste:

```
https://<host>/mcp
```

Claude discovers OAuth metadata, registers through `/register`, and uses PKCE S256 automatically.

### Claude Code

```bash
claude mcp add --transport http aegis-gitea https://<host>/mcp
```

Claude Code uses the same remote MCP and OAuth metadata. Local development loopback callbacks are allowed by default.

### Cowork

Cowork uses the same connector infrastructure and MCP URL as Claude.

### SSE compatibility

If your client still expects SSE transport, use:

- **SSE URL:** `https://<host>/mcp/sse`
- **Tool discovery URL:** `https://<host>/mcp/tools` (no auth required)
- **Tool call URL:** `https://<host>/mcp/tool/call`

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