mcp-forgejo

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: Apache-2.0

README ΒΆ

πŸ€– AI-Generated Content β€” The content of this repository, including all source code, documentation, and configuration files, has been generated by an artificial intelligence assistant or created using artificial intelligence assistant. While efforts have been made to ensure correctness and security, the code should be reviewed before use in any production environment.

mcp-forgejo β€” MCP Server

CI Release License MCP Go Version Go Reference Test Coverage gosec govulncheck gremlins

Badge note: the Go Reference badge above links to https://pkg.go.dev/github.com/teran/mcp-forgejo (module path github.com/teran/mcp-forgejo). The Test Coverage, gosec, govulncheck and gremlins badges are placeholders wired to the CI source β€” the checks they represent are enforced in .github/workflows/ci.yml (the coverage gate requires β‰₯ 95%, gosec/govulncheck findings are fixed-not-suppressed, and gremlins runs as a hard mutation-testing gate).

A Model Context Protocol server that wraps the Forgejo REST API so a model-driven client can perform common software-development tasks: repositories, files, issues, pull requests, branches, releases, and organizations.

Default language for this repository is English. SPEC.md and AGENTS.md are strictly English. If you need the README (or any doc) in another language, you must request it explicitly.

Features

The server exposes 51 tools covering the full read β†’ write/update β†’ delete surface. Each is a complete use-case (no client-side chaining of low-level calls) and is described with full metadata (annotations + per-tool instructions) in SPEC.md Β§6.

Read (19)

  • forgejo_repo_search β€” search repositories
  • forgejo_repo_get β€” repository details
  • forgejo_repo_list_contents β€” list directory contents
  • forgejo_file_get β€” read a file
  • forgejo_diff_get β€” diff between refs, or a PR diff
  • forgejo_commit_list β€” list commits
  • forgejo_branch_list β€” list branches
  • forgejo_branch_get β€” get a branch
  • forgejo_org_list β€” list your organizations
  • forgejo_issue_list β€” list issues
  • forgejo_issue_get β€” get an issue and its comments
  • forgejo_pull_list β€” list pull requests
  • forgejo_pull_get β€” get a PR with its changed files and checks
  • forgejo_release_list β€” list releases (or the latest)
  • forgejo_tag_list β€” list tags
  • forgejo_milestone_list β€” list milestones
  • forgejo_label_list β€” list labels
  • forgejo_user_get β€” get the current user, or a user by name
  • forgejo_user_list β€” search users

Write / Update (22)

  • forgejo_repo_create β€” create a repository (current user or an org)
  • forgejo_repo_update β€” update a repository
  • forgejo_repo_fork β€” fork a repository
  • forgejo_org_create β€” create an organization
  • forgejo_file_write β€” write or update a file in one commit
  • forgejo_file_write_many β€” write several files in one commit
  • forgejo_branch_create β€” create a branch
  • forgejo_issue_create β€” create an issue
  • forgejo_issue_update β€” update / close / reopen an issue
  • forgejo_issue_comment_add β€” add an issue comment
  • forgejo_issue_set_labels β€” replace the labels of an issue
  • forgejo_pull_create β€” create a pull request
  • forgejo_pull_update β€” update / close / reopen a PR
  • forgejo_pull_merge β€” merge a PR (merge/squash/rebase)
  • forgejo_pull_review β€” create and submit a PR review
  • forgejo_release_create β€” create a release
  • forgejo_release_asset_upload β€” upload a release asset
  • forgejo_tag_create β€” create a tag
  • forgejo_milestone_create β€” create a milestone
  • forgejo_milestone_update β€” update a milestone
  • forgejo_label_create β€” create a label
  • forgejo_label_update β€” update a label

Delete (10) β€” destructive; these require explicit confirmation

  • forgejo_file_delete β€” delete a file
  • forgejo_branch_delete β€” delete a branch (never the default branch)
  • forgejo_issue_delete β€” delete an issue
  • forgejo_comment_delete β€” delete an issue comment
  • forgejo_release_delete β€” delete a release
  • forgejo_repo_delete β€” delete a repository
  • forgejo_org_delete β€” delete an organization
  • forgejo_tag_delete β€” delete a tag
  • forgejo_milestone_delete β€” delete a milestone
  • forgejo_label_delete β€” delete a label

Requirements

  • Go 1.27+ (see go.mod / GO_VERSION in CI).

Install & Run

go build -o mcp-forgejo ./cmd/mcp-forgejo
Run locally (stdio)
FORGEJO_URL=https://git.example.com FORGEJO_TOKEN=<pat> \
  ./mcp-forgejo -mode stdio
Run as a remote sidecar (HTTP/SSE)
FORGEJO_URL=https://git.example.com FORGEJO_TOKEN=<pat> \
  LISTEN_ADDR=:8080 ./mcp-forgejo -mode http

Or run the container image (built by GoReleaser β€” the Dockerfile only copies the prebuilt binary in, it does not recompile; see Dockerfile):

goreleaser build --snapshot --clean --single-target --output dist/mcp-forgejo
docker build -t mcp-forgejo .
docker run --rm -p 8080:8080 \
  -e FORGEJO_URL=https://git.example.com \
  -e FORGEJO_TOKEN=<pat> \
  mcp-forgejo -mode http
Example: STDIO

Minimal configuration β€” the server reads FORGEJO_URL and FORGEJO_TOKEN from the environment and talks to the local client over stdin/stdout:

export FORGEJO_URL=https://git.example.com
export FORGEJO_TOKEN=<pat>

# Optional:
export LOG_LEVEL=info                 # enable logging (writes to /tmp/mcp-forgejo.log, chmod 600)
export LOG_FILENAME=/tmp/mcp-forgejo.log
export LOG_FORMAT=text                # or "json"

./mcp-forgejo -mode stdio

The -mode flag may be omitted β€” stdio is the default when neither -mode nor -mode http is given.

Example: HTTP/SSE

The same env vars plus the listener address. Logs go to stdout (12-factor), so this mode is meant to run as a sidecar behind a reverse proxy that terminates TLS and enforces client auth:

export FORGEJO_URL=https://git.example.com
export FORGEJO_TOKEN=<pat>
export LISTEN_ADDR=:8080

export LOG_LEVEL=info                 # optional in HTTP mode β€” defaults to "info" (to stdout)
export LOG_FORMAT=text                # or "json"

./mcp-forgejo -mode http

The client connects to the MCP streamable HTTP endpoint served at the listener root (the SDK's StreamableHTTPHandler, see server/http.go); the path is configurable in the SDK options.

Configuration (env vars)
Env var Type Default Description
FORGEJO_URL string (from env) Base URL of the Forgejo instance, e.g. https://git.example.com. Required.
FORGEJO_TOKEN string (empty) Forgejo personal access token (PAT). Secret β€” never logged/leaked. Required for the stdio transport; optional for the HTTP transport (over HTTP the token is supplied per-request via Authorization: Bearer <token>; FORGEJO_TOKEN is only a fallback).
LISTEN_ADDR string :8080 MCP listen address for the HTTP/SSE MCP transport (O04).
INTERNAL_ADDR string :8081 Internal observability address β€” separate listener for /metrics, /debug/pprof/*, /healthz, /readyz (HTTP/SSE mode only; see Metrics & Observability).
LOG_LEVEL string (unset) Logging level (trace/debug/info/warn/error). Transport-dependent (L02): in HTTP/SSE mode logging is always enabled, defaulting to info when LOG_LEVEL is unset; in stdio mode it is enabled only when set β€” unset β‡’ disabled (no log file).
LOG_FILENAME string /tmp/mcp-forgejo.log Log file path for stdio transport (chmod 600). Ignored for HTTP/SSE (logs go to stdout, 12-factor).
LOG_FORMAT string text text (logrus text, full absolute timestamp) or json.

Configuration is loaded with kelseyhightower/envconfig. There is no ALLOW_DIRS: the server never touches the local filesystem β€” all operations go to the remote Forgejo API (see SPEC.md Β§3).

Startup banner

When logging is enabled β€” always in HTTP/SSE mode (defaults to info); in stdio mode only when LOG_LEVEL is set β€” the server writes a startup banner as the first log line on the transport's logging channel (file for stdio, stdout for HTTP/SSE):

Starting mcp-forgejo/1.2.3 (commit: abc1234; built at 2026-09-10T12:00:00Z)

The banner is populated at build time via ldflags (appName/appVersion/appCommitHash/appTimestamp, see .goreleaser.yaml and SPEC.md Β§8 B02/B05).

Metrics & Observability

In HTTP/SSE mode the server exposes an observability endpoint on a separate internal listener, INTERNAL_ADDR (default :8081), distinct from the MCP listen address (LISTEN_ADDR, default :8080). It is always enabled in HTTP/SSE mode β€” there is no opt-out β€” and is not started in stdio mode. A reverse proxy should forward only the MCP listener, never the observability one.

Endpoint Purpose
GET /metrics Prometheus metrics via the promhttp default registry β€” the standard Go collectors (runtime/memstats + net/http) plus upstream Forgejo response metrics (O03): forgejo_upstream_request_duration_seconds, forgejo_upstream_request_total (labelled {method,status}), forgejo_upstream_request_size_bytes, forgejo_upstream_response_size_bytes.
GET /debug/pprof/… net/http/pprof profiling (cmdline, profile, symbol, trace).
GET /healthz Liveness probe (always 200).
GET /readyz Readiness probe (always 200).

These are served by their own http.Server, separate from the MCP JSON-RPC/SSE flow. Alongside the standard Go collectors, the upstream Forgejo response metrics (O03) are exposed on /metrics, observed once per outbound Forgejo request by the infrastructure client. See SPEC.md Β§7.1.

Transports & Auth

  • Transport: Hybrid β€” STDIO (local editor/CLI companion) and HTTP/SSE (remote sidecar). See SPEC.md Β§1 for the task-derived justification.
  • OAuth2: not used β€” a single Forgejo PAT via Authorization: token <PAT> is the natural, minimal mechanism. See SPEC.md Β§2 for the justification.
  • TLS: never implemented inside the server. Terminate TLS at the reverse proxy (nginx / Caddy / ingress) in front of the HTTP/SSE listener.
  • HTTP/SSE security: the server authenticates every incoming request with an Authorization: Bearer <token> header (rejecting others with 401) and uses that token (or the FORGEJO_TOKEN fallback) against Forgejo. For defense in depth, place the HTTP/SSE listener behind a reverse proxy that enforces client authn/authz (mTLS / OIDC / ACL), and prefer a dedicated low-privilege Forgejo user for the token. See SPEC.md Β§5 (S07).
Token: per-transport handling

The Forgejo PAT is sourced per-transport β€” the HTTP transport accepts it from the client, the stdio transport from the environment:

Role When How
Obtain (HTTP) Per incoming HTTP request The MCP client sends the PAT as an Authorization: Bearer <token> header. The server reads it, injects it into the request context, and rejects requests lacking a valid Bearer token with 401 Unauthorized.
Obtain (stdio) Startup / configuration The server reads the PAT from the FORGEJO_TOKEN environment variable (required for stdio; startup fails if empty).
Present (outbound) Every outbound request to Forgejo The server sends the resolved token as an Authorization: token <PAT> header on every call it makes to the Forgejo REST API (see forgejo.go). A per-request Bearer token overrides the config fallback.

Two important clarifications:

  1. Inbound (HTTP/SSE): the server does authenticate incoming requests β€” each request must carry an Authorization: Bearer <token> header (case- insensitive scheme, non-empty token) or it is rejected with 401. The Bearer header on the MCP listener is distinct from the outbound token scheme used to call Forgejo. For defense in depth, still place the HTTP/SSE listener behind a reverse proxy that enforces client authn/authz (mTLS / OIDC / ACL).
  2. Not OAuth2: the Bearer header is a transport wrapper; Forgejo's PAT mechanism remains the token scheme (Authorization: token <PAT>). The token is never logged, leaked in error messages, or echoed in tool outputs (it is redacted to [REDACTED]).

Development

golangci-lint run ./...        # lint + gofmt/gofumpt; findings fixed
go test -race ./...            # unit tests with race detector
go-arch-lint check             # dependency rules, see .go-arch-lint.yml
gosec ./...                    # findings must be FIXED
govulncheck ./...              # findings must be FIXED
go test -coverprofile=cover.out ./...
go tool cover -func=cover.out | awk '/^total:/ {print $3}'  # must be >= 95%
gremlins unleash . --threshold-efficacy=90 --threshold-mcover=80 --timeout-coefficient=60  # HARD GATE
make e2e                       # e2e tests (needs Docker); also: make e2e-cover

CI enforces a 95% coverage gate (build fails below it), the race detector, lint, gosec, govulncheck, go-arch-lint, and gremlins (mutation testing) as a hard gate. See .github/workflows/ci.yml.

End-to-end tests (e2e)

The e2e/ suite verifies the full path between the MCP tool handler and a real Forgejo backend. It runs through the github.com/teran/go-docker-testsuite harness, which spins up a real Forgejo container (requires a Docker daemon):

make e2e          # go test -tags e2e ./...
make e2e-cover    # e2e with a separate coverage profile (e2e-cover.out)

Every file in e2e/ carries a //go:build e2e build tag, so the suite is excluded from the default unit run (go test ./... / make test). CI runs it in a dedicated e2e job as a hard gate (a failing e2e test breaks the build). See SPEC.md Β§8 (T02/C04/N30).

Architecture

See SPEC.md for the application-level architecture: package layout (cmd/ + top-level packages), the tool registry, transport wiring, config, security, logging, and error handling.

Contributing / TDD

This project is developed test-first (TDD): a failing test is written before the implementation that satisfies it. CI enforces the discipline with a 95% coverage gate and gremlins mutation testing as a hard gate.

The @qa / @developer split referenced elsewhere is how AI agents in this repo cooperate (each writes tests / implementation in an isolated context) β€” see AGENTS.md for the agent operating rules. It does not apply to a human making changes directly; the test-first rule is universal:

  1. Write a failing test for the behavior you're adding (new tool, bug fix, refactor).
  2. Implement just enough to make it pass.
  3. Keep the gates green β€” run the checks in Development and ensure coverage stays β‰₯ 95%.

License

Apache License 2.0

Directories ΒΆ

Path Synopsis
Package application implements the use cases (tool handlers) of mcp-forgejo.
Package application implements the use cases (tool handlers) of mcp-forgejo.
cmd
mcp-forgejo command
Command mcp-forgejo is the composition root of the mcp-forgejo MCP server.
Command mcp-forgejo is the composition root of the mcp-forgejo MCP server.
Package config loads server configuration from the environment using kelseyhightower/envconfig.
Package config loads server configuration from the environment using kelseyhightower/envconfig.
Package domain holds the pure entities, error taxonomy and service interfaces of mcp-forgejo.
Package domain holds the pure entities, error taxonomy and service interfaces of mcp-forgejo.
infrastructure
forgejo
Package forgejo implements the Forgejo REST client.
Package forgejo implements the Forgejo REST client.
Package logging configures a logrus logger with a sink appropriate to the transport (L1): HTTP/SSE logs to stdout, stdio logs to a file.
Package logging configures a logrus logger with a sink appropriate to the transport (L1): HTTP/SSE logs to stdout, stdio logs to a file.
Package observability exposes Prometheus metrics, pprof profiling and liveness/readiness probes on a separate internal HTTP listener, distinct from the MCP listen address.
Package observability exposes Prometheus metrics, pprof profiling and liveness/readiness probes on a separate internal HTTP listener, distinct from the MCP listen address.
Package server wires the Forgejo client, the application use cases and the MCP SDK into a tool registry, and provides the transport drivers (stdio and HTTP/SSE).
Package server wires the Forgejo client, the application use cases and the MCP SDK into a tool registry, and provides the transport drivers (stdio and HTTP/SSE).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL