@vbcdx/forgejo-plugin

An MCP server for Forgejo. It gives AI agents a fixed set of 35 tools for repositories, issues, comments, labels, milestones, pull requests, reviews, commit statuses and Actions runs, with a write gate and verified results.

• Runs over stdio (for a local agent harness) or Streamable HTTP (as a network service or container).
• Write gate: reads only by default. Writes and destructive operations need explicit opt-in.
• Verified results: writes are read back to confirm them, and a timed-out or ambiguous write is reported as such rather than as success or failure. dispatch_workflow and cancel_workflow_run are acknowledged only (outcome accepted); the run itself is not awaited.

The full specification is in docs/contract.md.

Requirements

• Node.js 22 or later
• A Forgejo instance and an access token (or username and password) for it

Install

npm install -g @vbcdx/forgejo-plugin

This installs the vbcdx-forgejo command. To run it without installing:

npx -y --package=@vbcdx/forgejo-plugin vbcdx-forgejo --help

Usage

vbcdx-forgejo mcp          Start the stdio MCP server (default)
vbcdx-forgejo serve        Start the network MCP server (Streamable HTTP)
vbcdx-forgejo healthcheck  Probe a running serve endpoint; exit 0 if healthy
vbcdx-forgejo manifest     Print the JSON tool manifest
vbcdx-forgejo --help
vbcdx-forgejo --version

Register with an MCP client

Claude Code:

claude mcp add forgejo --scope user \
  -e VBCDX_FORGEJO_URL=https://git.example.com \
  -e VBCDX_FORGEJO_WRITES=off \
  -- vbcdx-forgejo mcp

Codex:

codex mcp add forgejo \
  --env VBCDX_FORGEJO_URL=https://git.example.com \
  --env VBCDX_FORGEJO_WRITES=off \
  -- vbcdx-forgejo mcp

For OpenCode, see examples/opencode.json. More detail is in examples/registration.md.

The package also ships a vbcdx.json declaration, so the vbcdx installer can register it for you:

npm install -g @vbcdx/vbcdx
vbcdx install tool @vbcdx/forgejo-plugin --harness=claude

Configuration

Settings are read from the environment once, at startup. See .env.example.

| Variable | Default | Description | | --- | --- | --- | | VBCDX_FORGEJO_URL | none | Forgejo instance URL, optionally ending in /api/v1. Required for any call. | | VBCDX_FORGEJO_WRITES | off | off (reads only), write (ordinary writes), or full (also destructive tools). | | VBCDX_FORGEJO_TIMEOUT_MS | 30000 | Total deadline per tool call, 1000 to 120000 ms. |

Tools are always listed. A call made without valid configuration or credentials returns an error explaining what is missing.

Credentials (stdio mode)

Credentials are never passed on the command line or in the environment. Every tool takes a credential_file argument: the absolute path to a file like this:

VBCDX_AGENTS_ROLE=code-agent
VBCDX_AGENTS_USER=example-bot
VBCDX_AGENTS_TOKEN=<forgejo access token>
# VBCDX_AGENTS_PASSWORD=<optional, used once if the token is rejected with 401>

The file must be a regular file you own with mode 0600, in a directory with mode 0700:

install -d -m 0700 ~/.config/vbcdx/forgejo
install -m 0600 /dev/null ~/.config/vbcdx/forgejo/code-agent.env

See examples/credential-file.env for the full format.

Network mode

vbcdx-forgejo serve exposes the same tools over MCP Streamable HTTP:

VBCDX_FORGEJO_URL=https://git.example.com vbcdx-forgejo serve
# MCP endpoint: POST http://127.0.0.1:8080/mcp
# Liveness:     GET  http://127.0.0.1:8080/healthz

In this mode there is no credential file. Each request carries its own credential in the Authorization header (Bearer <token>, token <token>, or Basic <base64(user:password)>), which is used for that request only.

| Variable | Default | Description | | --- | --- | --- | | VBCDX_FORGEJO_HTTP_PORT | 8080 | Listen port. | | VBCDX_FORGEJO_HTTP_HOST | 127.0.0.1 | Bind address. | | VBCDX_FORGEJO_TLS_CERT | none | PEM certificate path. Set together with the key to serve HTTPS. | | VBCDX_FORGEJO_TLS_KEY | none | PEM private key path. | | VBCDX_FORGEJO_HTTP_ALLOWED_ORIGINS | none | Comma-separated browser origins allowed to call the server. Requests with any other Origin header get 403. |

Without TLS settings the server speaks plain HTTP; run it behind a TLS-terminating reverse proxy or on a trusted network. Outbound connections to Forgejo always verify TLS.

Docker

docker build -t vbcdx-forgejo .
docker run --rm -p 8080:8080 \
  -e VBCDX_FORGEJO_URL=https://git.example.com \
  vbcdx-forgejo

The image runs serve as a non-root user and listens on all interfaces. No credentials are stored in the image.

Tools

Run vbcdx-forgejo manifest for every tool's input and output schema.

| Effect | Tools | | --- | --- | | Read | whoami, list_repositories, get_repository, list_branches, get_file, list_issues, get_issue, list_comments, get_comment, list_labels, list_milestones, list_pull_requests, get_pull_request, get_pull_request_diff, list_pull_request_files, list_reviews, get_review, list_commit_statuses, list_workflow_runs, get_workflow_run, list_workflow_jobs | | Write (write or full) | create_repository, create_issue, update_issue, set_issue_labels, create_comment, update_comment, create_pull_request, update_pull_request, create_review, set_commit_status, dispatch_workflow | | Destructive (full only) | delete_comment, merge_pull_request, cancel_workflow_run |

Destructive tools also require an exact confirmation string naming the target, and edits to comments or pull requests check the expected current state (a body hash or head SHA) first.

list_reviews caps each review body at 2000 characters by default (body_max_chars) and can filter by commit_id and state; use get_review to read one review in full.

Results

Each call returns a text summary and a JSON envelope in structuredContent with outcome, effect, request and verification. The outcome is one of ok, accepted, refused, failed, unverified or indeterminate.

Development

npm ci
npm test
node bin/vbcdx-forgejo.js --help

License

MIT