docs: Add documentation site and API reference

2026-02-13 15:12:14 +01:00
parent d82fe87113
commit e17d34e6d7
7 changed files with 968 additions and 0 deletions
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -0,0 +1,117 @@
+# 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://0.0.0.0: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