feat: add read-write Forgejo MCP app for ChatGPT #1

Merged

lost-rob0t merged 54 commits from feat/read-only-mcp-v1-final into main

2026-09-05 03:20:41 +00:00

lost-rob0t commented

2026-08-31 18:39:28 +00:00

(Migrated from github.com)

What changed

Implements forgejo-chatgpt-plugin v0.2 as a read/write remote MCP server for ChatGPT Developer Mode / custom apps.

dependency-free Node 22+ runtime
bounded Forgejo REST client
MCP initialize, tools/list, tools/call, and ping flow
Streamable HTTP endpoint at /mcp
health endpoint at /healthz
optional inbound bearer authentication
file-backed Forgejo and MCP secrets
reusable Nix package and NixOS module
normal Chat-mode read + write test documentation

Tool surface

29 tools total: 14 reads + 15 mutations.

Read operations cover repositories, branches, commits, trees, bounded UTF-8 files, code search, issues, pull requests, changed files, and bounded PR diffs.

Mutation operations include:

create/delete branches
create/update/delete repository files
forgejo_commit_changes for atomic multi-file commits (up to 100 create/update/delete operations, including feature-branch creation)
create/edit/comment issues
create/edit/comment pull requests
request reviewers
submit APPROVED / COMMENT / REQUEST_CHANGES PR reviews
merge pull requests

forgejo_delete_branch, forgejo_delete_file, and forgejo_merge_pull_request are explicitly annotated destructiveHint: true. Other mutations are writable/non-destructive.

There is still no generic HTTP tool, shell tool, Git SSH key, repository-admin tool, or arbitrary command execution.

Security boundary

The server talks to Forgejo only through its REST API using a dedicated runtime token. The intended StarIntel deployment runs it beside Forgejo and uses http://127.0.0.1:3000 internally, avoiding a loop through the public Git ingress.

Repository file reads and PR diffs are bounded. The NixOS module loads credentials with systemd LoadCredential, so credential values do not enter the Nix store or process argv. The MCP service defaults to 127.0.0.1:9473 and should initially be reached through Secure MCP Tunnel or an authenticated HTTPS boundary.

The Forgejo token should have repository write permission required for the desired mutation operations but should not have instance-admin privileges.

Validation

The original read-only slice was executed successfully before write expansion (9/9 tests).

The expanded v0.2 test suite is committed and adds coverage for:

POST issue mutations
UTF-8 -> base64 file writes
atomic multi-file commits
SHA enforcement on update/delete operations
PR merge request payloads
MCP routing for write operations
write vs destructive MCP annotations

The expanded suite was not re-run in the ChatGPT implementation container because that environment has no outbound DNS and no Nix installation. Run npm test, nix build, and the starintel-infra source-build evaluation before merge/deploy.

ChatGPT

docs/chatgpt.md documents testing from a new normal ChatGPT chat, not Work mode. The write smoke test is:

create a disposable feature branch
create a file on that branch
read it back and obtain its SHA
update it
open a pull request

ChatGPT may require confirmation before executing write/destructive tools; that is expected Developer Mode behavior.

Intended StarIntel deployment

execution host: source-build
Forgejo API from MCP: http://127.0.0.1:3000
MCP backend: 127.0.0.1:9473
eventual public MCP endpoint: https://mcp.git.starintel.actor/mcp
first integration test: Secure MCP Tunnel, before permanent public ingress

Do not merge until the expanded Node tests and Nix/source-build evaluation have been run in the real development/infra environment.

## What changed Implements `forgejo-chatgpt-plugin` v0.2 as a **read/write** remote MCP server for ChatGPT Developer Mode / custom apps. - dependency-free Node 22+ runtime - bounded Forgejo REST client - MCP `initialize`, `tools/list`, `tools/call`, and ping flow - Streamable HTTP endpoint at `/mcp` - health endpoint at `/healthz` - optional inbound bearer authentication - file-backed Forgejo and MCP secrets - reusable Nix package and NixOS module - normal Chat-mode read + write test documentation ## Tool surface 29 tools total: **14 reads + 15 mutations**. Read operations cover repositories, branches, commits, trees, bounded UTF-8 files, code search, issues, pull requests, changed files, and bounded PR diffs. Mutation operations include: - create/delete branches - create/update/delete repository files - `forgejo_commit_changes` for atomic multi-file commits (up to 100 create/update/delete operations, including feature-branch creation) - create/edit/comment issues - create/edit/comment pull requests - request reviewers - submit APPROVED / COMMENT / REQUEST_CHANGES PR reviews - merge pull requests `forgejo_delete_branch`, `forgejo_delete_file`, and `forgejo_merge_pull_request` are explicitly annotated `destructiveHint: true`. Other mutations are writable/non-destructive. There is still no generic HTTP tool, shell tool, Git SSH key, repository-admin tool, or arbitrary command execution. ## Security boundary The server talks to Forgejo only through its REST API using a dedicated runtime token. The intended StarIntel deployment runs it beside Forgejo and uses `http://127.0.0.1:3000` internally, avoiding a loop through the public Git ingress. Repository file reads and PR diffs are bounded. The NixOS module loads credentials with systemd `LoadCredential`, so credential values do not enter the Nix store or process argv. The MCP service defaults to `127.0.0.1:9473` and should initially be reached through Secure MCP Tunnel or an authenticated HTTPS boundary. The Forgejo token should have repository write permission required for the desired mutation operations but should not have instance-admin privileges. ## Validation The original read-only slice was executed successfully before write expansion (9/9 tests). The expanded v0.2 test suite is committed and adds coverage for: - POST issue mutations - UTF-8 -> base64 file writes - atomic multi-file commits - SHA enforcement on update/delete operations - PR merge request payloads - MCP routing for write operations - write vs destructive MCP annotations The expanded suite was **not re-run in the ChatGPT implementation container** because that environment has no outbound DNS and no Nix installation. Run `npm test`, `nix build`, and the `starintel-infra` source-build evaluation before merge/deploy. ## ChatGPT `docs/chatgpt.md` documents testing from a **new normal ChatGPT chat**, not Work mode. The write smoke test is: 1. create a disposable feature branch 2. create a file on that branch 3. read it back and obtain its SHA 4. update it 5. open a pull request ChatGPT may require confirmation before executing write/destructive tools; that is expected Developer Mode behavior. ## Intended StarIntel deployment - execution host: `source-build` - Forgejo API from MCP: `http://127.0.0.1:3000` - MCP backend: `127.0.0.1:9473` - eventual public MCP endpoint: `https://mcp.git.starintel.actor/mcp` - first integration test: Secure MCP Tunnel, before permanent public ingress Do not merge until the expanded Node tests and Nix/source-build evaluation have been run in the real development/infra environment.