Latte
b275f5c0c2
test / test (push) Has been cancelled
lint / lint (push) Has been cancelled
docker / test (pull_request) Successful in 13s
docker / lint (pull_request) Successful in 2m3s
lint / lint (pull_request) Successful in 16s
test / test (pull_request) Successful in 14s
docker / docker-test (pull_request) Successful in 42s
docker / docker-publish (pull_request) Has been skipped
131 lines
3.2 KiB
Markdown
131 lines
3.2 KiB
Markdown
# 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
|