108 lines
4.2 KiB
Markdown
108 lines
4.2 KiB
Markdown
# 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 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 and run setup
|
|
|
|
```bash
|
|
git clone https://git.hiddenden.cafe/Hiddenden/AegisGitea-MCP.git
|
|
cd AegisGitea-MCP
|
|
uv sync
|
|
uv run aegis-gitea-mcp setup
|
|
```
|
|
|
|
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 `AEGIS_ENV_FILE`, else `./.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
|
|
uv run aegis-gitea-mcp serve
|
|
```
|
|
|
|
It waits for JSON-RPC on stdin (stdout is reserved for the protocol, logs go to stderr). Stop it
|
|
with Ctrl+D.
|
|
|
|
For HTTP:
|
|
|
|
```bash
|
|
MCP_TRANSPORT=http uv run aegis-gitea-mcp serve # or: serve --transport http
|
|
curl http://127.0.0.1:8080/health
|
|
```
|
|
|
|
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.
|
|
|
|
## 3. Connect a client
|
|
|
|
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).
|
|
|
|
## 4. Try it
|
|
|
|
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 validate-audit
|
|
```
|
|
|
|
## Running without a clone
|
|
|
|
With `uvx`, no checkout is needed:
|
|
|
|
```bash
|
|
GITEA_URL=https://git.example.com GITEA_TOKEN=<your-gitea-token> uvx aegis-gitea-mcp
|
|
```
|
|
|
|
The package comes from the Gitea package registry, see [packaging.md](packaging.md).
|
|
|
|
## Where state lives
|
|
|
|
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`.
|