AegisGitea-MCP/docs/packaging.md

Packaging & publishing

AegisGitea-MCP is distributed as a single Python package, aegis-gitea-mcp, built with uv and published to the self-hosted Gitea package registry.

Distribution layout

One package, two console scripts, one optional extra:

Console script	Entry point	Requires
aegis-gitea-mcp	aegis_gitea_mcp.stdio_app:main	core only
aegis-gitea-mcp-server	aegis_gitea_mcp.server_entry:main	[server] extra

• Core (default install): httpx, pydantic, pydantic-settings, PyYAML, python-dotenv, structlog, mcp. Enough to run the local stdio server.
• [server] extra: fastapi, uvicorn[standard], PyJWT[crypto], python-multipart. The public HTTP/OAuth server.

The aegis-gitea-mcp-server entry point degrades gracefully: invoked without the web stack it prints install 'aegis-gitea-mcp[server]' instead of a ModuleNotFoundError traceback.

Build locally

uv build
# -> dist/aegis_gitea_mcp-<version>-py3-none-any.whl
# -> dist/aegis_gitea_mcp-<version>.tar.gz

Smoke-test the local stdio server from the built wheel:

GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> \
  uvx --from ./dist/aegis_gitea_mcp-*.whl aegis-gitea-mcp

Install from the Gitea registry

uv pip install \
  --index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple \
  aegis-gitea-mcp

(With pip, use --index-url the same way.)

Cutting a release

Releases are tag-driven. The publish workflow (.gitea/workflows/publish.yml) triggers on a v* tag, runs lint + tests first, builds with uv, and publishes to the Gitea PyPI registry.

1. Bump version in pyproject.toml (e.g. 0.2.0).

2. Open a PR into dev, merge dev into main.

3. Tag the release commit and push the tag:

   git tag v0.2.0
   git push origin v0.2.0
   

4. The workflow publishes the wheel + sdist and attaches them to the run.

Required CI secrets

The publish job reuses the existing REGISTRY_TOKEN Actions secret — the same PAT (write:package) that docker.yml uses to push images — so no new secret is needed. The token authenticates as its owning Gitea user, so GITHUB_ACTOR is the username and the token is the password.

Secret	Purpose
REGISTRY_TOKEN	PAT with write:package; used for both image and package pushes

If the secret is absent the job fails loudly rather than publishing anonymously.

Publishing to public PyPI is intentionally not configured. A second, separately-gated uv publish step would be required and is left as a commented stub in the workflow.