gitza-mcp/RELEASE.md

102 lines
7.2 KiB
Markdown

# Gitza MCP 0.1.0 release
Gitza MCP is maintained in its own MIT-licensed repository at
[git.gitza.co.za/Gitza/gitza-mcp](https://git.gitza.co.za/Gitza/gitza-mcp).
It was extracted from the initial implementation on 2026-10-25. It has no
Gitza monorepo dependency. Source publication does not publish an npm package,
container release or hosted endpoint.
## Verification
Standalone verification on 2026-10-25 passed lint, type checking, compilation,
40 unit/protocol tests, 35 API/database/security tests, four browser OAuth
workflows, packed installation, and AMD64 container protocol/migration/readiness
checks. The standalone production dependency audit reported zero known
vulnerabilities. No hosted CI result is claimed.
The standalone release checks cover:
| Check | Coverage |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Unit and MCP protocol | 40 tests for secret generation, validation, encryption, isolation, output bounds, write permission, fork-reference rejection, audit-error redaction, negotiation and discovery |
| Real API, database and HTTP security | 35 tests against disposable backend 15.0.6 and PostgreSQL 18, covering all tools, scoped/read-only tokens, cross-account denial, membership removal, persistence, atomic consumption, concurrent refresh, token audience/account/scope/expiry, revoked/expired grants, discovery and malformed requests |
| Browser OAuth | Four Chromium workflows for sign-in/consent, upstream credential refresh, HTTP tool calls, MCP refresh rotation, revocation, read-only denial, cancellation/disconnect, invalid PKCE/resource/state/CSRF, and refresh replay |
| Accessibility | Axe checks on consent and connection management; desktop/mobile consent screenshots |
| Installed package | Pack, install in a clean directory, negotiate MCP, list tools and read a private file |
| Container | Standalone frozen-lockfile build, non-root/read-only stdio, private-file read, migration command and hosted PostgreSQL readiness |
Run all checks below before publishing. Integration tests create uniquely named,
loopback-only fixtures and remove only their own containers and volumes. They
never use production accounts or databases. Keep fixture credentials private.
Production Compose verification also passed migration ordering, a non-superuser
application database role, persistence across restart, and an encrypted credential
round trip through pg_dump/pg_restore into a separate database.
## Client compatibility
The release was exercised with these clients on 2026-10-25.
| Client | Version | Verified |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- |
| Claude Code | 2.1.310 | Clean temporary configuration, stdio connection, hosted browser login and HTTP connection |
| MCP Inspector CLI | 2.12.0 | stdio discovery and private file, issue and PR reads |
| Official TypeScript SDK client | 1.32.2 | stdio and Streamable HTTP initialization, discovery and calls, with HTTP tokens obtained through real browser OAuth |
The checks ran on macOS ARM64 and Linux containers. Windows and other GUI clients
have not been tested. Claude Code hosted login and explicit repository consent were also verified.
Native callbacks accept exact localhost and loopback IPs; unsafe HTTP hosts remain denied.
## Release checks
Use Node 24, Docker and the pinned pnpm version from this repository's root:
```sh
corepack pnpm install --frozen-lockfile
corepack pnpm check
PLAYWRIGHT_SKIP_BROWSER_GC=1 corepack pnpm exec playwright install chromium
docker build --platform linux/amd64 -t gitza-mcp:check .
MCP_TEST_IMAGE=gitza-mcp:check corepack pnpm test:integration
corepack pnpm test:deployment
corepack pnpm audit --prod
```
For optional client checks, retain a new fixture with `MCP_KEEP_FIXTURE=1`, then
run `node --import tsx tests/clients.ts` with `MCP_FIXTURE_PATH` set to its printed
path. This uses temporary client settings. It requires the installed Claude CLI
and npm access for the pinned Inspector. Remove that fixture's Compose project
and volumes afterward.
The optional `.forgejo/workflows/check.yml` performs these checks on a separately
provisioned `gitza-mcp-linux` runner. This repository does not provision a runner,
enable hosted Actions, or automatically publish releases. Local checks remain
the gate until that runner is configured and a successful CI run is recorded.
## Package and publish
```sh
corepack pnpm build
mkdir -p artifacts
npm pack --ignore-scripts --pack-destination artifacts
shasum -a 256 artifacts/gitza-mcp-0.1.0.tgz
```
Inspect the packed file list and preserve checksums with the release. After source
review and confirmation of npm-scope ownership, publish the exact tested archive:
```sh
npm publish artifacts/gitza-mcp-0.1.0.tgz --access public
```
Publication is a separate release action. Do not commit build artifacts, test
reports, credentials or local configuration. `LICENSE` applies to this MCP
implementation; names and trademarks are not licensed by it.
For hosting, follow `OPERATIONS.md`: register the upstream OAuth application,
provision an approved South African service/database, inject persistent secrets,
migrate, configure HTTPS/DNS, monitoring and backups, then verify live client
sign-in and revocation before announcing the endpoint.
Upgrade by pinning a new package/image version and repeating the compatibility
suite. Keep the preceding image and database backup as the rollback pair. Lost
keys or deliberately revoked grants require affected users to reconnect.