Hiddenden/AegisGitea-MCP
5
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases 1 Wiki Activity

docs: rewrite README and docs for the full-access design, generate tool inventory

Browse Source
This commit is contained in:
Latte committed 2026-10-14 16:13:11 +02:00
1 parent 68bd8700dc
commit 7c7cfc05ff
13 files changed
+1693 -1026
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/getting-started.md
+74 -97
View File
@@ -1,130 +1,107 @@
# Getting Started
# Getting started
This page takes you from a fresh clone to a working server in about 5 to 10 minutes, most of it
creating the Gitea token. It covers the local stdio setup (one user, started by your MCP
client) and the HTTP server.
## Prerequisites
- Python 3.10 or higher
- A running Gitea instance
- A Gitea OAuth2 application for this MCP server
- `make` (optional but recommended)
- Python 3.10 or newer and [uv](https://docs.astral.sh/uv/)
- A Gitea instance and a site-admin token. In Gitea: Settings, Applications, Generate New
Token, then set every scope to Read and Write (or choose `all`). Admin features need a
site-admin token. A narrower token still works: calls outside its scopes return Gitea's 403
(see "Token scopes" in the [README](../README.md)).
## 1. Install
## 1. Install and run setup
```bash
git clone <repo-url>
git clone https://git.hiddenden.cafe/Hiddenden/AegisGitea-MCP.git
cd AegisGitea-MCP
# Install production dependencies
make install
# Or install with dev dependencies (for testing and linting)
make install-dev
uv sync
uv run aegis-gitea-mcp setup
```
To install manually without `make`:
Setup prompts for the Gitea URL and the token (hidden input). For unattended use pass
`--gitea-url`, set `GITEA_TOKEN` in the environment and add `--yes`. Options:
| Option | Meaning |
|---|---|
| `--gitea-url` | Gitea base URL |
| `--public-base-url` | Public https URL of this server. Enables registration of the OAuth application |
| `--no-oauth` | Do not create the Gitea OAuth application |
| `--env-file` | Env file to create or update (default `./.env`) |
| `--template` | Env template (default `./.env.example`, else the copy built into the package) |
| `--yes` | Never prompt, and accept regenerating an OAuth client secret |
What it does, in order:
1. Checks that Gitea is reachable (`GET /api/v1/version`) and prints the version. DNS, TLS,
timeout and refused-connection failures get a specific hint.
2. Validates the token (`GET /user`), requires a site administrator, and reads its scopes
(`GET /token`). Missing scopes are an error; `all` satisfies everything.
3. With a public base URL: creates (or reuses, or after confirmation updates) the
`aegis-gitea-mcp` OAuth application with redirect URI `<public base URL>/oauth/callback`.
Gitea regenerates the client secret on update, which is why it asks first.
4. Writes the env file atomically with mode 0600. It generates `MCP_BEARER_TOKEN` and
`TOKEN_ENCRYPTION_KEY` when they are not there yet, keeps values it does not manage, and
tightens the permissions of an existing file.
5. Prints client configurations for Claude Code, Claude Desktop and Cursor, claude.ai and
Mistral Le Chat, a docker-compose service and a Caddyfile.
Secrets are only written to the env file; setup never prints them. It does not follow
redirects, so the token cannot be sent to a host you did not name.
## 2. Run the server
stdio is started by your MCP client, so you normally do not run it by hand. To check that it
starts:
```bash
python -m venv venv
source venv/bin/activate # Linux/macOS
# or: venv\Scripts\activate # Windows
pip install -e .
# dev: pip install -e ".[dev]"
uv run aegis-gitea-mcp serve
```
## 2. Create a Gitea OAuth2 Application
It waits for JSON-RPC on stdin (stdout is reserved for the protocol, logs go to stderr). Stop it
with Ctrl+D.
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:
For HTTP:
```bash
cp .env.example .env
MCP_TRANSPORT=http uv run aegis-gitea-mcp serve # or: serve --transport http
curl http://127.0.0.1:8080/health
```
Minimum OAuth settings in `.env`:
It binds to `127.0.0.1:8080` and serves the MCP endpoint at `/mcp`. Without `MCP_BEARER_TOKEN`
or OAuth the loopback endpoint is unauthenticated, which is only acceptable for local
experiments; the server prints a warning. Setup generates `MCP_BEARER_TOKEN` for you.
```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>
```
## 3. Connect a client
`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.
Use the snippets that setup printed. They are also in the
[README](../README.md#client-configuration). Local clients use the stdio configuration with
`GITEA_URL` and `GITEA_TOKEN` in the client's `env`. Remote clients use
`https://<your host>/mcp` with the bearer token or OAuth. Before exposing the server beyond
localhost, read [deployment.md](deployment.md) and [hardening.md](hardening.md).
See [Configuration](configuration.md) for the full list of settings.
## 4. Try it
## 4. Optional Standard API Key Mode
For non-OAuth deployments, configure `GITEA_TOKEN` and `MCP_API_KEYS`. Generate an API key with:
Ask the client something that needs a tool, for example "list my repositories". Every result
names the identity that made the call. To check the audit trail:
```bash
make generate-key
# or: python scripts/generate_api_key.py
make validate-audit
```
Copy the printed key into `MCP_API_KEYS` in your `.env` file and set `OAUTH_MODE=false`.
## Running without a clone
## 5. Run
With `uvx`, no checkout is needed:
```bash
make run
# or: python -m aegis_gitea_mcp.server
GITEA_URL=https://git.example.com GITEA_TOKEN=<your-gitea-token> uvx aegis-gitea-mcp
```
The server starts on `http://127.0.0.1:8080` by default.
The package comes from the Gitea package registry, see [packaging.md](packaging.md).
Verify it is running:
## Where state lives
```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
The audit log and, in OAuth mode, the encrypted token store live in `DATA_DIR` (default
`~/.local/state/aegis-gitea-mcp`). Override with `DATA_DIR` or `AUDIT_LOG_PATH`.