# 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 --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp
```

The package comes from the Gitea package registry, see [packaging.md](packaging.md). Always pass
the `--index`: the name is not registered on public PyPI, and a bare `uvx aegis-gitea-mcp` would
resolve there. From a clone use
`uv run --directory /path/to/AegisGitea-MCP aegis-gitea-mcp serve`.

## 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`.