gitza-mcp/README.md

7.3 KiB

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.

User guide: AI tools and MCP, including setup, permissions, troubleshooting and client compatibility limits.

Version 0.1.0 requires Node 24 or newer. Install the pinned release with npm install -g @gitza/mcp@0.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:

claude mcp add --transport stdio --scope user gitza \
  --env GITZA_REPOSITORIES=you/project -- gitza-mcp stdio

The launch command can also be npx -y @gitza/mcp@0.1.0 stdio. To build and install from source:

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:

{
  "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:

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:

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 for hosting, RELEASE.md for release evidence and CONTRIBUTING.md for contribution instructions. MIT applies only to the MCP implementation; see THIRD-PARTY-NOTICES.md.