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>
79 lines
2.3 KiB
Markdown
79 lines
2.3 KiB
Markdown
# Deployment
|
|
|
|
## Secure Defaults
|
|
|
|
- Default bind is `127.0.0.1`.
|
|
- Binding `0.0.0.0` requires `ALLOW_INSECURE_BIND=true`.
|
|
- Write mode disabled by default.
|
|
- Policy checks run before tool execution.
|
|
- OAuth-protected MCP challenge responses are enabled by default for tool calls.
|
|
|
|
## Local stdio install (single user)
|
|
|
|
The local transport needs only the core package (no web stack):
|
|
|
|
```bash
|
|
pip install aegis-gitea-mcp # or: uvx aegis-gitea-mcp
|
|
GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> aegis-gitea-mcp
|
|
```
|
|
|
|
It authenticates with your Gitea PAT, runs policy + `WRITE_MODE` + audit, and
|
|
serves over stdio for Claude Desktop / Claude Code. See
|
|
[local-quickstart.md](local-quickstart.md).
|
|
|
|
## Local Development (HTTP server)
|
|
|
|
```bash
|
|
make install-dev
|
|
cp .env.example .env
|
|
make run
|
|
```
|
|
|
|
The HTTP server requires the web stack. From a published package that is the
|
|
`[server]` extra:
|
|
|
|
```bash
|
|
pip install 'aegis-gitea-mcp[server]'
|
|
aegis-gitea-mcp-server
|
|
```
|
|
|
|
## Docker
|
|
|
|
Use `docker/Dockerfile`:
|
|
|
|
- Multi-stage image build.
|
|
- Non-root runtime user.
|
|
- Production env flags (`NODE_ENV=production`, `ENVIRONMENT=production`).
|
|
- Only required app files copied.
|
|
- Healthcheck on `/health`.
|
|
|
|
Run examples:
|
|
|
|
```bash
|
|
docker compose --profile prod up -d
|
|
docker compose --profile dev up -d
|
|
```
|
|
|
|
## CI/CD (Gitea Workflows)
|
|
|
|
Workflows live in `.gitea/workflows/`:
|
|
|
|
- `lint.yml`: ruff + format checks + mypy.
|
|
- `test.yml`: lint + tests + coverage fail-under `80`.
|
|
- `docker.yml`: lint + test + docker smoke-test gating; image publish on push to `main`/`dev` and on approved PR review targeting `main`/`dev`; tags include commit SHA plus `latest` (`main`) or `dev` (`dev`).
|
|
|
|
Docker publish settings:
|
|
- `vars.PUSH_IMAGE=true` enables registry push.
|
|
- `vars.REGISTRY_IMAGE` sets the target image name (for example `registry.example.com/org/aegis-gitea-mcp`).
|
|
- `vars.REGISTRY_HOST` is optional and overrides the login host detection.
|
|
- `secrets.REGISTRY_USER` and `secrets.REGISTRY_TOKEN` are required when push is enabled.
|
|
|
|
## Production Recommendations
|
|
|
|
- Place MCP behind TLS reverse proxy.
|
|
- Set `PUBLIC_BASE_URL=https://<your-mcp-domain>` so OAuth metadata advertises HTTPS endpoints.
|
|
- Restrict inbound traffic to expected clients.
|
|
- Persist and monitor audit logs.
|
|
- Monitor `/metrics` and auth-failure events.
|
|
- Rotate OAuth client credentials when required.
|