163 lines
7.4 KiB
Markdown
163 lines
7.4 KiB
Markdown
# Gitza MCP
|
|
|
|
Connect MCP clients to selected Gitza repositories. The same implementation runs
|
|
locally over stdio or as a hosted service with browser sign-in.
|
|
|
|
Source: [Gitza/gitza-mcp on Gitza](https://git.gitza.co.za/Gitza/gitza-mcp).
|
|
|
|
User guide: [AI tools and MCP](https://docs.gitza.co.za/mcp), including setup,
|
|
permissions, troubleshooting and client compatibility limits.
|
|
|
|
Version 0.1.0 requires Node 24 or newer. Install the pinned npm release:
|
|
|
|
```sh
|
|
npm install -g @gitza/mcp@0.1.0
|
|
```
|
|
|
|
The same archive and its SHA-256 checksum are available on the
|
|
[Gitza release page](https://git.gitza.co.za/Gitza/gitza-mcp/releases/tag/v0.1.0).
|
|
|
|
## Local connection
|
|
|
|
Create a token in Gitza under **Settings → Applications**, restricted to the
|
|
repositories you want to expose. Select **read:repository** and **read:issue** for
|
|
reading, or **write:repository** and **write:issue** for the supported writes.
|
|
Account/admin scopes are not required. A local allowlist also restricts public
|
|
repositories that the token could otherwise read.
|
|
|
|
Set `GITZA_TOKEN` in the environment used to launch your client. Do not place the
|
|
token in shell arguments, Git URLs or a committed configuration file. Then add
|
|
the installed executable to Claude Code:
|
|
|
|
```sh
|
|
claude mcp add --transport stdio --scope user gitza \
|
|
--env GITZA_REPOSITORIES=you/project -- gitza-mcp stdio
|
|
```
|
|
|
|
To build and install from source:
|
|
|
|
```sh
|
|
git clone https://git.gitza.co.za/Gitza/gitza-mcp.git
|
|
cd gitza-mcp
|
|
corepack pnpm install --frozen-lockfile
|
|
corepack pnpm build
|
|
npm pack --ignore-scripts
|
|
npm install -g ./gitza-mcp-0.1.0.tgz
|
|
```
|
|
|
|
For clients using JSON configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"gitza": {
|
|
"command": "gitza-mcp",
|
|
"args": ["stdio"],
|
|
"env": { "GITZA_REPOSITORIES": "you/project", "GITZA_WRITE": "false" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The client process must inherit `GITZA_TOKEN`. Use the client's secure secret
|
|
configuration if it does not inherit shell variables. Never commit a literal token.
|
|
|
|
`GITZA_REPOSITORIES` is a comma-separated, explicit allowlist. Read-only is the
|
|
default; set `GITZA_WRITE=true` to enable the three write tools. Tokens remain
|
|
revocable in Gitza regardless of this setting. `GITZA_URL` selects one fixed
|
|
instance; tools cannot change it. Local credentials are never sent to a broker.
|
|
|
|
## Hosted connection
|
|
|
|
Connect to the Gitza hosted service:
|
|
|
|
```sh
|
|
claude mcp add --transport http --scope user gitza https://mcp.gitza.co.za/mcp
|
|
claude mcp login gitza
|
|
```
|
|
|
|
You can also run `/mcp` in Claude Code and follow browser authentication. Select repositories
|
|
and optionally enable issue creation, comments and PR creation. New repositories
|
|
are never selected automatically. Visit `/connections` on the MCP origin to revoke
|
|
individual connections or remove all grants and the stored upstream credential.
|
|
|
|
The OAuth scope `gitza:access` means access to a user-approved connection. Exact
|
|
repositories and read/write capabilities live in the persisted grant and are
|
|
checked on every call. OAuth tokens are opaque, bound to the MCP resource and
|
|
separate from upstream account credentials.
|
|
|
|
## Tools
|
|
|
|
| Tool | Main inputs |
|
|
| ----------------------- | ------------------------------------------------------------------- |
|
|
| `list_repositories` | Optional `query`, `page`, `limit` |
|
|
| `get_repository` | `repository` |
|
|
| `list_directory` | `repository`, optional `path`, `ref`, `page`, `limit` |
|
|
| `get_file` | `repository`, `path`, optional `ref`, `start_line`, `max_lines` |
|
|
| `list_branches` | `repository`, optional `page`, `limit` |
|
|
| `list_commits` | `repository`, optional `sha`, `page`, `limit` |
|
|
| `list_issues` | `repository`, optional `state`, `page`, `limit` |
|
|
| `get_issue` | `repository`, `index` |
|
|
| `list_comments` | `repository`, `index`, optional `page`, `limit` |
|
|
| `list_pull_requests` | `repository`, optional `state`, `page`, `limit` |
|
|
| `get_pull_request` | `repository`, `index` |
|
|
| `get_pull_request_diff` | `repository`, `index`, optional line window and `expected_head_sha` |
|
|
| `create_issue` | `repository`, `title`, optional `body` |
|
|
| `add_comment` | `repository`, `index`, `body` |
|
|
| `create_pull_request` | `repository`, `title`, `base`, `head`, optional `body` |
|
|
|
|
`repository` is `owner/name`. PR creation requires an already pushed branch in the
|
|
selected repository; fork-qualified heads are rejected. Use
|
|
ordinary Git tools for editing, committing and pushing. This release does not
|
|
merge, delete repositories, execute code, provide CI tools or forward arbitrary API
|
|
requests. Symlinks, submodules and external download URLs are not followed.
|
|
|
|
Lists return `data` and `next_page`. Text readers return windows and `next_line`.
|
|
Pin file reads to a commit SHA and use the PR head SHA when paging a diff. Binary
|
|
files are reported explicitly. Results are capped at 256 KiB, text windows at
|
|
60,000 bytes, and upstream bodies at 4 MiB. Larger results return an actionable
|
|
error. There is no implicit whole-repository download or indexing.
|
|
|
|
Tool errors use `isError` with a stable error code. Missing and inaccessible objects
|
|
share an error to avoid disclosing private metadata. Writes are never retried
|
|
automatically. After an uncertain write outcome, inspect Gitza before retrying.
|
|
|
|
## Data boundaries
|
|
|
|
Repository content and comments are untrusted data. They cannot grant permissions.
|
|
Every operation is constrained by the connection's repository IDs, allowed actions
|
|
and current upstream access. A renamed/replaced repository requires reselection.
|
|
|
|
The hosted service stores encrypted upstream account credentials. On the supported
|
|
backend, OAuth credentials can be broader than the repositories selected in MCP;
|
|
the MCP grant restricts their use by this service. Protect database backups and
|
|
encryption keys separately. No shared administrator credential is used for tools.
|
|
|
|
Content returned to your AI client may be processed by its model provider outside
|
|
South Africa. Local or South African MCP hosting does not determine where that
|
|
provider processes the response. The MCP itself makes no model calls.
|
|
|
|
## Develop and verify
|
|
|
|
From the repository root, use Node 24 and the pinned package manager:
|
|
|
|
```sh
|
|
corepack pnpm install --frozen-lockfile
|
|
corepack pnpm lint
|
|
corepack pnpm typecheck
|
|
corepack pnpm test
|
|
corepack pnpm build
|
|
PLAYWRIGHT_SKIP_BROWSER_GC=1 corepack pnpm exec playwright install chromium
|
|
corepack pnpm test:integration
|
|
```
|
|
|
|
Integration tests require Docker. They create a uniquely named, loopback-only
|
|
instance and PostgreSQL database, exercise real API and OAuth flows, then remove
|
|
only their own containers and volumes. They never target a deployed service.
|
|
`MCP_KEEP_FIXTURE=1` retains that disposable stack for debugging; the printed path
|
|
contains secret test configuration and must not be committed or shared.
|
|
|
|
See [OPERATIONS.md](OPERATIONS.md) for hosting,
|
|
[RELEASE.md](RELEASE.md) for release evidence and
|
|
[CONTRIBUTING.md](CONTRIBUTING.md) for contribution instructions. MIT applies
|
|
only to the MCP implementation; see [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).
|