118 lines
2.9 KiB
Markdown
118 lines
2.9 KiB
Markdown
# 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
|