Latte
385b442b6f
Reframe the README around two transports and add a local stdio quickstart with uvx/pip and Claude Desktop / Claude Code wiring. New docs: local-quickstart.md and packaging.md (uv build/publish). Document resource-type-aware authorization and classified gitea_request in security.md; stdio env vars + audit-log fallback in configuration.md; local install in deployment.md; core+adapters in architecture.md. Add the missing root AGENTS.md contract, update CLAUDE.md with the core/adapter layout, fail-closed invariants, and the branching flow (HEAD -> feature -> dev -> main). Update roadmap/todo and .env.example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
99 lines
2.6 KiB
Markdown
99 lines
2.6 KiB
Markdown
# Local quickstart (stdio)
|
|
|
|
The local transport runs AegisGitea-MCP on your own machine as a single-user MCP
|
|
server over stdio. It authenticates with **your** Gitea Personal Access Token
|
|
(PAT) — there is no OAuth, no public endpoint, and no web stack to install.
|
|
|
|
## What you need
|
|
|
|
- A Gitea instance URL (`GITEA_URL`).
|
|
- A Gitea Personal Access Token (`GITEA_TOKEN`) with least privilege:
|
|
- `read:repository`
|
|
- `write:repository` only if you intend to enable `WRITE_MODE`.
|
|
- [`uv`](https://docs.astral.sh/uv/) (for `uvx`) or `pip`.
|
|
|
|
## Run it
|
|
|
|
With `uvx` (no install):
|
|
|
|
```bash
|
|
GITEA_URL=https://git.hiddenden.cafe \
|
|
GITEA_TOKEN=<pat> \
|
|
uvx aegis-gitea-mcp
|
|
```
|
|
|
|
With pip:
|
|
|
|
```bash
|
|
pip install aegis-gitea-mcp
|
|
GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> aegis-gitea-mcp
|
|
```
|
|
|
|
A local `.env` file is also supported — drop `GITEA_URL` and `GITEA_TOKEN` in it
|
|
and just run `aegis-gitea-mcp`.
|
|
|
|
If a required variable is missing the server exits with a clear message instead
|
|
of a traceback.
|
|
|
|
## Wire it into a client
|
|
|
|
Claude Code:
|
|
|
|
```bash
|
|
claude mcp add aegis-gitea \
|
|
-e GITEA_URL=https://git.hiddenden.cafe \
|
|
-e GITEA_TOKEN=<pat> \
|
|
-- uvx aegis-gitea-mcp
|
|
```
|
|
|
|
Claude Desktop (`claude_desktop_config.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"aegis-gitea": {
|
|
"command": "uvx",
|
|
"args": ["aegis-gitea-mcp"],
|
|
"env": {
|
|
"GITEA_URL": "https://git.hiddenden.cafe",
|
|
"GITEA_TOKEN": "<pat>"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## What still applies locally
|
|
|
|
The local adapter is single-user and trusts the PAT owner, so it skips the
|
|
per-user repository-permission probe used by the public server. Everything else
|
|
is identical to the server:
|
|
|
|
- **Policy engine** (`policy.yaml`) — same allow/deny rules.
|
|
- **`WRITE_MODE`** — off by default; writes are denied unless explicitly enabled
|
|
and whitelisted.
|
|
- **`gitea_request`** full-API escape hatch — same write classifier, known-path
|
|
gate, and admin/credential denylist.
|
|
- **Secret sanitization** of tool output.
|
|
- **Tamper-evident audit log** — written to a per-user path when the container
|
|
default is not writable:
|
|
- Windows: `%LOCALAPPDATA%\aegis-gitea-mcp\audit.log`
|
|
- Linux/macOS: `$XDG_STATE_HOME/aegis-gitea-mcp/audit.log` or
|
|
`~/.local/state/aegis-gitea-mcp/audit.log`
|
|
- Override with `AUDIT_LOG_PATH`.
|
|
|
|
## Enabling writes locally
|
|
|
|
Writes are opt-in, exactly as on the server:
|
|
|
|
```bash
|
|
GITEA_URL=https://git.hiddenden.cafe \
|
|
GITEA_TOKEN=<pat-with-write-repository> \
|
|
WRITE_MODE=true \
|
|
WRITE_REPOSITORY_WHITELIST=acme/app,acme/docs \
|
|
uvx aegis-gitea-mcp
|
|
```
|
|
|
|
See [configuration.md](configuration.md) for the full variable reference and
|
|
[write-mode.md](write-mode.md) for the write-mode model.
|