Forgejo Client

Comprehensive Rust client library for Forgejo/Gitea with MCP server and demo data generation.

Workspace layout

This repository is a Cargo workspace with three crates under crates/:

Crate	Role
forge_client	REST API client that talks to a real Forgejo/Gitea backend (the shipped binaries forgejo_client, demo-feed, demo-test, quick-test live here).
forge_server	oschema-first JSON-RPC daemon — a Hero front-end whose handlers proxy to the Forgejo backend through forge_client. Serves forge/rpc.sock.
forge_sdk	Typed async client for forge_server, generated from its oschema (ForgeServerClient).

forge_client carries the feature flags; build/test commands that pass --features must target it (cargo … -p forge_client --features …). The Makefile and CI already do this.

cargo build --release --workspace        # build everything
cargo run -p forge_server -- --info      # show the server manifest

Features

• Forgejo/Gitea REST API Client - Type-safe async HTTP client for all Forgejo operations
• Rhai Scripting - Execute scripts with Forgejo integration via forgejo_client binary
• MCP Server - Model Context Protocol server for AI integration (59+ tools)
• Demo Data - Generate test data for development and testing

Quick Start

Prerequisites

Our client depends on features not available in the standard Forgejo server.

For testing with a demo deployment, see: https://forge.ourworld.tf/lhumina_research/forgejo_fork

Run run_test.sh which sets up:

• Forgejo instance at http://localhost:3333
• Admin user: administrator / password1234
• Test user: testuser / testuser

Installation

Download and install the latest binaries:

curl -sSL https://forge.ourworld.tf/api/packages/lhumina_research/generic/forgejo-runner/dev/install.sh | bash

Installs to ~/hero/bin/. Add to PATH:

export PATH="$HOME/hero/bin:$PATH"

Build from Source

# Build with all features (default)
cargo build --release

# Build with specific features
cargo build --release --features rhai
cargo build --release --features mcp

Usage

The forgejo_client binary serves as both a Rhai script runner and an MCP server.

Rhai Script Runner

# Execute a single script
forgejo_client script.rhai [args...]

# Run all scripts in a directory
forgejo_client --dir ./scripts

# Syntax check scripts without executing
forgejo_client --test ./scripts

# Show help
forgejo_client --help

Example script (get_user.rhai):

#!/usr/bin/env forgejo_client

let client = new_forgejo_client("http://localhost:3333")
    .token(env("FORGEJO_TOKEN"))
    .connect()?;

let user = client.get_current_user()?;
print(`Logged in as: ${user.login}`);

MCP Server

Start the MCP server as a subcommand of forgejo_client:

# Start with user/password (auto-creates API token, like Go version)
forgejo_client mcp --user administrator --passwd password1234

# Start with explicit token
forgejo_client mcp --token <api-token>

# Custom URL and listen address
forgejo_client mcp --user admin --passwd pass --url http://myforge:3333 --listen 0.0.0.0:4856

# Environment variables also work (CLI flags take priority)
FORGEJO_TOKEN=xxx forgejo_client mcp

MCP Options

Flag	Env Variable	Default	Description
--url	FORGEJO_URL	http://localhost:3333	Forgejo server URL
--token	FORGEJO_TOKEN	-	Existing API token
--user	FORGEJO_USER	-	Username for automatic token creation
--passwd	FORGEJO_PASS	-	Password for automatic token creation
--listen	MCP_LISTEN_ADDR	127.0.0.1:4856	Listen address

Resolution order: CLI flag > environment variable > default.

Endpoints

• MCP: http://<listen>/mcp (StreamableHTTP transport)
• Health: http://<listen>/health

MCP Tools (59 tools)

The MCP server exposes the following tool categories:

Users (6): get_current_user, get_user, list_users, create_user, delete_user, set_user_password

Repositories (6): list_repos, get_repo, create_repo, create_org_repo, update_repo, delete_repo

Organizations (7): list_orgs, get_org, create_org, update_org, delete_org, list_org_repos, list_org_members

Issues (5): list_issues, get_issue, create_issue, update_issue, delete_issue

Labels (6): list_labels, get_label, create_label, update_label, delete_label, sync_labels

Milestones (5): list_milestones, get_milestone, create_milestone, update_milestone, delete_milestone

Teams (7): list_teams, get_team, create_team, delete_team, list_team_members, add_team_member, remove_team_member

Projects (18): list/get/create/update/update_status/delete/list_columns/create_column/delete_column for both repo-level and org-level projects

Branches (4): list_branches, get_branch, create_branch, delete_branch

Comments (4): list_issue_comments, create_issue_comment, update_issue_comment, delete_issue_comment

Pull Requests (8): list_pull_requests, get_pull_request, create_pull_request, update_pull_request, merge_pull_request, list_pull_request_files, list_pull_reviews, create_pull_review

Finder (1): find_issues (cross-repository search)

Defaults (1): apply_defaults (sync labels and milestones to a repository)

Using the Client Library

use ourforge_client::ForgejoClient;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = ForgejoClient::new(
        "http://localhost:3333",
        "your_token_here"
    )?;

    // Get current user
    let user = client.get_current_user().await?;
    println!("User: {}", user.login);

    // List repositories
    let repos = client.list_repos(None, 1, 10).await?;
    for repo in repos {
        println!("Repo: {}/{}", repo.owner.as_ref().map(|o| o.login.as_str()).unwrap_or("?"), repo.name);
    }

    Ok(())
}

Available Client Methods

Repositories

list_my_repos, list_repos, list_org_repos, get_repo, create_repo, create_org_repo, edit_repo, delete_repo

Issues

list_issues, get_issue, create_issue, update_issue, delete_issue

Labels & Milestones

list_labels, get_label, create_label, edit_label, delete_label, sync_labels | list_milestones, get_milestone, create_milestone, edit_milestone, delete_milestone

Organizations

list_my_orgs, list_orgs, get_org, create_org, edit_org, delete_org, list_org_members

Users (Admin)

get_current_user, get_user, list_users, create_user, delete_user, set_user_password

Teams

list_org_teams, get_team, create_team, delete_team, add_team_member, remove_team_member, list_team_members

Branches

list_branches, get_branch, create_branch, delete_branch

Comments

list_issue_comments, create_issue_comment, update_issue_comment, delete_issue_comment

Pull Requests

list_pull_requests, get_pull_request, create_pull_request, update_pull_request, merge_pull_request, list_pull_request_files, list_pull_reviews, create_pull_review

Projects (Repo & Org)

list_projects, get_project, create_project, update_project, update_project_status, delete_project, list_project_columns, create_project_column, delete_project_column (plus org variants)

Finder

find_issues

Demo Data

# Populate server with demo data
make demodata

# Run demo data + validation tests
make demodata-test

# Check server connectivity
make check-server

API Specification

Forgejo API documentation is available as OpenAPI/Swagger:

• Swagger UI: http://localhost:3333/api/swagger
• Swagger JSON: http://localhost:3333/swagger.v1.json

Environment Variables

Variable	Description	Default
FORGEJO_URL	Base URL of the Forgejo instance	http://localhost:3333
FORGEJO_TOKEN	API token for authentication	-
FORGEJO_USER	Username (for demo binaries & MCP)	administrator
FORGEJO_PASS	Password (for demo binaries & MCP)	password1234
MCP_LISTEN_ADDR	MCP server listen address	127.0.0.1:4856

License

See LICENSE file for details