docs: retarget setup to Claude connectors

docs/getting-started.md

@@ -4,7 +4,7 @@
 
 - Python 3.10 or higher
 - A running Gitea instance
-- A Gitea bot user with access to the repositories you want to expose
+- A Gitea OAuth2 application for this MCP server
 - `make` (optional but recommended)
 
 ## 1. Install
@@ -31,14 +31,12 @@ pip install -e .
 # dev: pip install -e ".[dev]"
 ```
 
-## 2. Create a Gitea Bot User
+## 2. Create a Gitea OAuth2 Application
 
-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.
+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
 
@@ -48,27 +46,31 @@ Copy the example environment file and fill in your values:
 cp .env.example .env
 ```
 
-Minimum required settings in `.env`:
+Minimum OAuth 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>
+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. Generate an API Key
+## 4. Optional Standard API Key Mode
 
-The MCP server requires clients to authenticate with a bearer token. Generate one:
+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.
+Copy the printed key into `MCP_API_KEYS` in your `.env` file and set `OAUTH_MODE=false`.
 
 ## 5. Run
 
@@ -88,24 +90,35 @@ curl http://localhost:8080/health
 
 ## 6. Connect an AI Client
 
-### ChatGPT
+### Claude
 
-Use this single URL in the ChatGPT MCP connector:
+In claude.ai, open **Settings > Connectors > Add custom connector** and paste:
 
 ```
-http://<host>:8080/mcp/sse?api_key=<your-api-key>
+https://<host>/mcp
 ```
 
-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.
+Claude discovers OAuth metadata, registers through `/register`, and uses PKCE S256 automatically.
 
-### Other MCP clients
+### Claude Code
 
-Clients that support custom headers can use:
+```bash
+claude mcp add --transport http aegis-gitea https://<host>/mcp
+```
 
-- **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>`
+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).