pi-forgejo-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial public Pi extension for Forgejo via `forgejo-mcp --cli`.
+- Adds status, tool discovery, tool help, and generic operation invocation tools.
+- Adds interactive confirmation for mutating Forgejo operations.

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Thanks for your interest in contributing to `pi-forgejo-mcp`.
+
+## Prerequisites
+
+- Node.js `>=22.19.0`
+- npm
+- Pi installed locally for interactive extension testing
+- `forgejo-mcp` on your `PATH` if you want to test against a real Forgejo instance
+
+Install dependencies with:
+
+```sh
+npm ci
+```
+
+## Local development
+
+Run the full check suite before opening a pull request:
+
+```sh
+npm run check
+```
+
+This runs TypeScript, ESLint, Prettier, and Vitest.
+
+For interactive local testing:
+
+```sh
+pi -e .
+```
+
+## Formatting
+
+Check formatting with:
+
+```sh
+npm run format
+```
+
+Apply formatting with:
+
+```sh
+npm run format:write
+```
+
+## Testing with Forgejo
+
+For real Forgejo calls, set credentials in the environment of the shell that launches Pi:
+
+```sh
+export FORGEJO_URL="https://codeberg.org"
+export FORGEJO_ACCESS_TOKEN="<your personal access token>"
+pi -e .
+```
+
+Never commit real tokens. `.env` and `.env.*` files are gitignored for local use, and Pi does not load them automatically.
+
+## Pull requests
+
+Please keep changes focused and include relevant updates when applicable:
+
+- tests for behavior changes
+- documentation for user-facing changes
+- changelog entries for release-worthy changes
+- security notes for changes affecting token handling, command execution, or mutations
+
+Before submitting, run:
+
+```sh
+npm run check
+```
+
+## Security
+
+Please do not include access tokens, private repository details, issue contents, or other sensitive data in issues, pull requests, tests, or logs.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and token-handling guidance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Osborne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# pi-forgejo-mcp
+
+A [Pi](https://pi.dev/) extension for using Forgejo from Pi via the official [`forgejo-mcp`](https://codeberg.org/goern/forgejo-mcp) CLI.
+
+Use it to ask Pi to list repositories, inspect issues, create pull requests, read files, check workflow runs, manage releases, and call other Forgejo operations exposed by `forgejo-mcp`.
+
+## Install
+
+First install the official Forgejo MCP CLI:
+
+```sh
+go install codeberg.org/goern/forgejo-mcp/v2@latest
+```
+
+Make sure `forgejo-mcp` is on your `PATH`:
+
+```sh
+forgejo-mcp --help
+```
+
+### Install by asking Pi
+
+If you already have Pi installed, you can paste this prompt into Pi. It asks Pi to check prerequisites, install the extension, and then explain the remaining authentication steps:
+
+```text
+Please install the Forgejo MCP Pi extension for me.
+
+Before installing, remind me that Pi packages/extensions run with my local user permissions. Ask me for confirmation before running installation commands.
+
+Do the setup:
+1. Check whether `forgejo-mcp` is installed and on PATH.
+2. If it is missing, check whether `go` is available. If Go is available, install the official CLI with:
+   `go install codeberg.org/goern/forgejo-mcp/v2@latest`
+   Then verify `forgejo-mcp --help` works. If it does not, tell me to add `$(go env GOPATH)/bin` to PATH or configure `FORGEJO_MCP_COMMAND`.
+   If Go is not available, stop and tell me to install Go or configure `FORGEJO_MCP_COMMAND`.
+3. Install the Pi package:
+   `pi install git:codeberg.org/ozzy92/pi-forgejo-mcp@main`
+4. Do not ask me to paste a token into chat. Tell me to set `FORGEJO_URL` and `FORGEJO_ACCESS_TOKEN` in the shell that launches Pi, using 1Password, Bitwarden, direnv, or another secret store.
+5. Tell me to restart Pi or run `/reload`.
+6. After reload/restart, tell me to run: `Check Forgejo MCP status.`
+```
+
+For repeatable installs, ask Pi to install a tagged release such as `git:codeberg.org/ozzy92/pi-forgejo-mcp@v0.1.0` instead of `main`.
+
+### Manual install
+
+Install this Pi package from Codeberg:
+
+```sh
+pi install git:codeberg.org/ozzy92/pi-forgejo-mcp@main
+```
+
+For repeatable installs, install a tagged release instead of `main`:
+
+```sh
+pi install git:codeberg.org/ozzy92/pi-forgejo-mcp@v0.1.0
+```
+
+Restart Pi or run `/reload` in an existing Pi session.
+
+> **Security:** Pi packages and extensions run with your local user permissions. Review the source before installing third-party packages.
+
+## Authenticate with Forgejo
+
+Create a Forgejo personal access token with the permissions you need for the operations you want Pi to perform.
+
+The token lives in the environment of the `pi` process:
+
+```sh
+export FORGEJO_URL="https://codeberg.org" # or your Forgejo instance URL
+export FORGEJO_ACCESS_TOKEN="<your personal access token>"
+pi
+```
+
+Do **not** commit the token. Do not put it in this repository, `package.json`, Pi settings, prompts, or session files.
+
+Good places to keep the token:
+
+- your password manager, injected into the shell before launching Pi
+- a local, gitignored shell file sourced by your shell profile
+- a [`direnv`](https://direnv.net/) `.envrc` file that is not committed
+- CI/secret-store environment variables for non-interactive runs
+
+Example with 1Password CLI:
+
+```sh
+export FORGEJO_URL="https://codeberg.org"
+export FORGEJO_ACCESS_TOKEN="$(op read 'op://Private/Codeberg Forgejo/token')"
+pi
+```
+
+Example with Bitwarden CLI:
+
+```sh
+export BW_SESSION="$(bw unlock --raw)"
+export FORGEJO_URL="https://codeberg.org"
+export FORGEJO_ACCESS_TOKEN="$(bw get password 'Codeberg Forgejo token')"
+pi
+```
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting, token-handling guidance, and local execution notes.
+
+## Try it in Pi
+
+Ask Pi things like:
+
+```text
+Check Forgejo MCP status.
+List Forgejo MCP issue tools.
+Describe the list_repo_issues Forgejo MCP tool.
+List open issues in my-org/my-repo.
+Create an issue in my-org/my-repo titled "Improve docs" with body "Add screenshots".
+Show recent workflow runs for my-org/my-repo.
+```
+
+Pi will usually discover or describe the Forgejo operation first, then call it with JSON arguments.
+
+## Tools provided to Pi
+
+When Pi loads this extension, it registers four tools:
+
+| Tool                        | Purpose                                                                                             |
+| --------------------------- | --------------------------------------------------------------------------------------------------- |
+| `forgejo_mcp_status`        | Check whether `forgejo-mcp` is installed and whether runtime auth env vars are present.             |
+| `forgejo_mcp_list_tools`    | List operations exposed by the installed `forgejo-mcp` binary, optionally filtered by domain/query. |
+| `forgejo_mcp_describe_tool` | Show the parameters for one Forgejo MCP operation.                                                  |
+| `forgejo_mcp_call`          | Invoke one Forgejo MCP operation with JSON arguments.                                               |
+
+If you are driving Pi programmatically, `forgejo_mcp_call` accepts this shape:
+
+```json
+{
+  "tool": "list_repo_issues",
+  "args": {
+    "owner": "my-org",
+    "repo": "my-repo",
+    "state": "open"
+  }
+}
+```
+
+## How it works
+
+This extension does not implement the Forgejo API itself. It shells out to the official CLI:
+
+```sh
+forgejo-mcp --cli <operation> --args '<json>' --output=json
+```
+
+Read-only discovery (`forgejo_mcp_list_tools` and `forgejo_mcp_describe_tool`) uses dummy local environment variables because `forgejo-mcp` requires configuration even for local help output.
+
+Real Forgejo calls use `FORGEJO_URL` and `FORGEJO_ACCESS_TOKEN` from the Pi process environment.
+
+Large outputs are truncated to Pi's default tool-output limit, and the full output is written to a temp file. Captured stdout/stderr is sanitized so the configured access token is replaced before tool results are returned to Pi.
+
+## Safety model
+
+Operations whose names look mutating (`create_*`, `update_*`, `delete_*`, `merge_*`, `mark_*`, etc.) ask for confirmation in interactive Pi sessions.
+
+In non-interactive modes, mutating operations are blocked unless you explicitly set:
+
+```sh
+export FORGEJO_MCP_ALLOW_MUTATIONS=true
+```
+
+You can disable interactive confirmations with:
+
+```sh
+export FORGEJO_MCP_CONFIRM_MUTATIONS=false
+```
+
+When confirmations are disabled, mutating operations are treated like non-interactive runs and still require:
+
+```sh
+export FORGEJO_MCP_ALLOW_MUTATIONS=true
+```
+
+## Configuration
+
+| Variable                        | Default           | Purpose                                                         |
+| ------------------------------- | ----------------- | --------------------------------------------------------------- |
+| `FORGEJO_URL`                   | required          | Forgejo instance URL, for example `https://codeberg.org`.       |
+| `FORGEJO_ACCESS_TOKEN`          | required          | Forgejo personal access token.                                  |
+| `FORGEJO_MCP_COMMAND`           | `forgejo-mcp`     | Binary to execute. Use this if `forgejo-mcp` is not on `PATH`.  |
+| `FORGEJO_MCP_TIMEOUT_MS`        | `60000`           | Timeout per CLI call.                                           |
+| `FORGEJO_MCP_MAX_CAPTURE_BYTES` | `26214400`        | Maximum stdout/stderr captured before killing the process.      |
+| `FORGEJO_MCP_CONFIRM_MUTATIONS` | `true` in UI mode | Set to `false` to skip interactive confirmation.                |
+| `FORGEJO_MCP_ALLOW_MUTATIONS`   | unset             | Required for mutating operations when no confirmation is taken. |
+
+## Local development
+
+```sh
+git clone https://codeberg.org/ozzy92/pi-forgejo-mcp.git
+cd pi-forgejo-mcp
+npm install
+npm run check
+pi -e .
+```
+
+`npm run check` runs TypeScript, ESLint, Prettier, and Vitest.
+
+For local testing against a real Forgejo instance, copy the example environment file and source it before launching Pi:
+
+```sh
+cp .env.example .env.local
+# edit .env.local with your own token
+set -a; source .env.local; set +a
+pi -e .
+```
+
+Pi does not automatically load `.env` files. The `.env` and `.env.*` patterns are gitignored; keep real tokens out of commits.
+
+Or install the local package globally while developing:
+
+```sh
+pi install /absolute/path/to/pi-forgejo-mcp
+```
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security
+
+`pi-forgejo-mcp` is an open-source Pi extension that shells out to the official `forgejo-mcp` CLI. It does not implement Forgejo authentication itself.
+
+## Supported versions
+
+Security fixes are intended for the latest released version and the `main` branch. Older tags may not receive backports.
+
+## Reporting vulnerabilities
+
+Please do not publish access tokens, private repository names, issue contents, or other sensitive data in public reports.
+
+- For issues that can be discussed publicly, open a Codeberg issue: <https://codeberg.org/ozzy92/pi-forgejo-mcp/issues>
+- For sensitive vulnerability details, use any private contact method listed on the project or maintainer profile first. If no private channel is available, open a minimal public issue asking for a private contact path and include only high-level impact and affected components.
+
+## Secret handling
+
+The extension reads Forgejo credentials from the environment of the running Pi process:
+
+- `FORGEJO_URL`
+- `FORGEJO_ACCESS_TOKEN`
+
+The extension does not read `.env` files automatically, does not write tokens to Pi settings, and does not require tokens in tool-call arguments.
+
+Captured stdout/stderr is sanitized before being returned to Pi by replacing the configured access token with `<FORGEJO_ACCESS_TOKEN>`. Do not rely on sanitization as your only control: avoid pasting secrets into prompts, issue bodies, pull request text, or tool arguments.
+
+## Token guidance
+
+- Use a token with the least permissions needed for the operations you want Pi to perform.
+- Store the token in a password manager, `direnv`, your shell environment, or a CI/secret-store environment variable.
+- Never commit real tokens or include them in examples, prompts, logs, issues, or pull requests.
+- Rotate the token immediately if it is exposed.
+
+## Local execution trust
+
+Pi packages and extensions run with your local user permissions. Only install this package, Pi, and the `forgejo-mcp` binary from sources you trust.
+
+This extension executes `forgejo-mcp` from `PATH` by default, or from `FORGEJO_MCP_COMMAND` if set. Forgejo operations run with the permissions granted to `FORGEJO_ACCESS_TOKEN`.
+
+Mutating Forgejo operations ask for confirmation in interactive Pi sessions. If no confirmation is taken, either because Pi is non-interactive or `FORGEJO_MCP_CONFIRM_MUTATIONS=false` is set, mutating operations are blocked unless `FORGEJO_MCP_ALLOW_MUTATIONS=true` is set.

package/extensions/forgejo-mcp/cli.ts

@@ -0,0 +1,308 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { confirmMutationIfNeeded } from "./mutations.ts";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_CAPTURE_BYTES = 25 * 1024 * 1024;
+const DUMMY_FORGEJO_URL = "https://example.invalid";
+const DUMMY_FORGEJO_TOKEN = "dummy-token-for-tool-discovery";
+
+const toolNamePattern = /^[a-z0-9_]+$/;
+
+export type ForgejoToolSummary = {
+	name: string;
+	description?: string;
+	domain?: string;
+};
+
+export type CommandResult = {
+	stdout: string;
+	stderr: string;
+	code: number | null;
+	signal: NodeJS.Signals | null;
+	timedOut: boolean;
+};
+
+export type FormattedOutput = {
+	text: string;
+	details: {
+		truncated: boolean;
+		truncation?: TruncationResult;
+		fullOutputPath?: string;
+		stderr?: string;
+	};
+};
+
+export function getCommand(): string {
+	return process.env.FORGEJO_MCP_COMMAND?.trim() || "forgejo-mcp";
+}
+
+export function getTimeoutMs(): number {
+	const value = Number.parseInt(process.env.FORGEJO_MCP_TIMEOUT_MS ?? "", 10);
+	return Number.isFinite(value) && value > 0 ? value : DEFAULT_TIMEOUT_MS;
+}
+
+export function getMaxCaptureBytes(): number {
+	const value = Number.parseInt(process.env.FORGEJO_MCP_MAX_CAPTURE_BYTES ?? "", 10);
+	return Number.isFinite(value) && value > 0 ? value : DEFAULT_MAX_CAPTURE_BYTES;
+}
+
+export function discoveryEnv(): NodeJS.ProcessEnv {
+	return {
+		...process.env,
+		// Tool discovery/help is local-only and does not need real credentials.
+		FORGEJO_URL: DUMMY_FORGEJO_URL,
+		FORGEJO_ACCESS_TOKEN: DUMMY_FORGEJO_TOKEN,
+	};
+}
+
+export function requireRuntimeEnv(): NodeJS.ProcessEnv {
+	const missing: string[] = [];
+	if (!process.env.FORGEJO_URL) missing.push("FORGEJO_URL");
+	if (!process.env.FORGEJO_ACCESS_TOKEN) missing.push("FORGEJO_ACCESS_TOKEN");
+
+	if (missing.length > 0) {
+		throw new Error(
+			`Forgejo MCP is not configured. Missing ${missing.join(", ")}. ` +
+				"Set FORGEJO_URL and FORGEJO_ACCESS_TOKEN in the environment before starting Pi.",
+		);
+	}
+
+	return process.env;
+}
+
+export function sanitizeText(text: string, token = process.env.FORGEJO_ACCESS_TOKEN): string {
+	if (!token || token.length < 4) return text;
+	return text.split(token).join("<FORGEJO_ACCESS_TOKEN>");
+}
+
+export function truncateForError(text: string, max = 4_000): string {
+	const cleaned = sanitizeText(text.trim());
+	if (cleaned.length <= max) return cleaned;
+	return `${cleaned.slice(0, max)}\n...[truncated]`;
+}
+
+export function validateToolName(tool: string): string {
+	const trimmed = tool.trim();
+	if (!toolNamePattern.test(trimmed)) {
+		throw new Error(`Invalid forgejo-mcp tool name: ${tool}`);
+	}
+	return trimmed;
+}
+
+export async function runForgejo(
+	args: string[],
+	options: { env: NodeJS.ProcessEnv; signal?: AbortSignal },
+): Promise<CommandResult> {
+	const command = getCommand();
+	const timeoutMs = getTimeoutMs();
+	const maxCaptureBytes = getMaxCaptureBytes();
+
+	return new Promise<CommandResult>((resolve, reject) => {
+		let stdoutBytes = 0;
+		let stderrBytes = 0;
+		let timedOut = false;
+		let exceededCapture = false;
+		let closed = false;
+		let killStarted = false;
+		const stdoutChunks: Buffer[] = [];
+		const stderrChunks: Buffer[] = [];
+
+		const child = spawn(command, args, {
+			env: options.env,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+
+		const cleanupFns: Array<() => void> = [];
+
+		const kill = (reason: "timeout" | "abort" | "capture") => {
+			if (reason === "timeout") timedOut = true;
+			if (reason === "capture") exceededCapture = true;
+			if (killStarted) return;
+			killStarted = true;
+			if (!closed) child.kill("SIGTERM");
+			const killTimer = setTimeout(() => {
+				if (!closed) child.kill("SIGKILL");
+			}, 2_000);
+			cleanupFns.push(() => clearTimeout(killTimer));
+		};
+
+		const timeout = setTimeout(() => kill("timeout"), timeoutMs);
+		cleanupFns.push(() => clearTimeout(timeout));
+
+		const onAbort = () => kill("abort");
+		if (options.signal) {
+			if (options.signal.aborted) onAbort();
+			else {
+				options.signal.addEventListener("abort", onAbort, { once: true });
+				cleanupFns.push(() => options.signal?.removeEventListener("abort", onAbort));
+			}
+		}
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			stdoutBytes += chunk.length;
+			if (stdoutBytes + stderrBytes > maxCaptureBytes) {
+				kill("capture");
+				return;
+			}
+			stdoutChunks.push(chunk);
+		});
+
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderrBytes += chunk.length;
+			if (stdoutBytes + stderrBytes > maxCaptureBytes) {
+				kill("capture");
+				return;
+			}
+			stderrChunks.push(chunk);
+		});
+
+		child.on("error", (error) => {
+			for (const cleanup of cleanupFns) cleanup();
+			reject(error);
+		});
+
+		child.on("close", (code, signal) => {
+			closed = true;
+			for (const cleanup of cleanupFns) cleanup();
+
+			const stdout = sanitizeText(Buffer.concat(stdoutChunks).toString("utf8"));
+			const stderr = sanitizeText(Buffer.concat(stderrChunks).toString("utf8"));
+
+			if (exceededCapture) {
+				reject(
+					new Error(`forgejo-mcp output exceeded FORGEJO_MCP_MAX_CAPTURE_BYTES (${formatSize(maxCaptureBytes)}).`),
+				);
+				return;
+			}
+
+			resolve({ stdout, stderr, code, signal, timedOut });
+		});
+	});
+}
+
+export function ensureSuccess(result: CommandResult, context: string): void {
+	if (result.code === 0 && !result.timedOut) return;
+
+	const timeoutNote = result.timedOut ? " timed out" : " failed";
+	const stderr = truncateForError(result.stderr);
+	const stdout = truncateForError(result.stdout);
+	const pieces = [`forgejo-mcp ${context}${timeoutNote}`];
+	if (result.code !== null) pieces.push(`exit code: ${result.code}`);
+	if (result.signal) pieces.push(`signal: ${result.signal}`);
+	if (stderr) pieces.push(`stderr:\n${stderr}`);
+	if (stdout) pieces.push(`stdout:\n${stdout}`);
+	throw new Error(pieces.join("\n\n"));
+}
+
+export async function formatOutput(rawOutput: string, stderr: string): Promise<FormattedOutput> {
+	const trimmed = rawOutput.trim();
+	let output = trimmed || "OK (no output)";
+
+	if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+		try {
+			output = JSON.stringify(JSON.parse(trimmed), null, 2);
+		} catch {
+			output = trimmed;
+		}
+	}
+
+	const truncation = truncateHead(output, {
+		maxLines: DEFAULT_MAX_LINES,
+		maxBytes: DEFAULT_MAX_BYTES,
+	});
+
+	const details: FormattedOutput["details"] = {
+		truncated: truncation.truncated,
+	};
+
+	let text = truncation.content;
+
+	if (truncation.truncated) {
+		const dir = await mkdtemp(join(tmpdir(), "pi-forgejo-mcp-"));
+		const file = join(dir, "output.txt");
+		await writeFile(file, output, "utf8");
+
+		details.truncation = truncation;
+		details.fullOutputPath = file;
+
+		text += `\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`;
+		text += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
+		text += ` Full output saved to: ${file}]`;
+	}
+
+	const cleanedStderr = truncateForError(stderr, 2_000);
+	if (cleanedStderr) details.stderr = cleanedStderr;
+
+	return { text, details };
+}
+
+let toolsCache: ForgejoToolSummary[] | undefined;
+
+export function clearToolsCache(): void {
+	toolsCache = undefined;
+}
+
+export async function listForgejoTools(signal?: AbortSignal): Promise<ForgejoToolSummary[]> {
+	if (toolsCache) return toolsCache;
+	const result = await runForgejo(["--cli", "list", "--output=json"], { env: discoveryEnv(), signal });
+	ensureSuccess(result, "tool list");
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(result.stdout);
+	} catch (error) {
+		throw new Error(`forgejo-mcp returned invalid tool list JSON: ${String(error)}`, { cause: error });
+	}
+
+	if (!Array.isArray(parsed)) {
+		throw new Error("forgejo-mcp returned an unexpected tool list shape.");
+	}
+
+	toolsCache = parsed
+		.map((item) => item as Record<string, unknown>)
+		.filter((item) => typeof item.name === "string")
+		.map((item) => ({
+			name: String(item.name),
+			description: typeof item.description === "string" ? item.description : undefined,
+			domain: typeof item.domain === "string" ? item.domain : undefined,
+		}))
+		.sort((a, b) => `${a.domain ?? ""}/${a.name}`.localeCompare(`${b.domain ?? ""}/${b.name}`));
+
+	return toolsCache;
+}
+
+export async function callForgejoTool(
+	tool: string,
+	args: Record<string, unknown> | undefined,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+) {
+	const validTool = validateToolName(tool);
+	await confirmMutationIfNeeded(ctx, validTool, args);
+
+	const result = await runForgejo(["--cli", validTool, "--args", JSON.stringify(args ?? {}), "--output=json"], {
+		env: requireRuntimeEnv(),
+		signal,
+	});
+	ensureSuccess(result, validTool);
+
+	const output = await formatOutput(result.stdout, result.stderr);
+	return {
+		content: [{ type: "text" as const, text: output.text }],
+		details: {
+			operation: validTool,
+			...output.details,
+		},
+	};
+}

package/extensions/forgejo-mcp/index.ts

@@ -0,0 +1,138 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import {
+	callForgejoTool,
+	formatOutput,
+	getCommand,
+	listForgejoTools,
+	runForgejo,
+	discoveryEnv,
+	ensureSuccess,
+	truncateForError,
+	validateToolName,
+} from "./cli.ts";
+
+export default function forgejoMcpExtension(pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "forgejo_mcp_status",
+		label: "Forgejo MCP Status",
+		description: "Check whether the forgejo-mcp CLI and required Forgejo environment variables are available.",
+		promptSnippet: "Check Forgejo MCP bridge configuration before using Forgejo tools.",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, signal) {
+			let cliAvailable = false;
+			let cliError: string | undefined;
+			let toolCount: number | undefined;
+			try {
+				const tools = await listForgejoTools(signal);
+				cliAvailable = true;
+				toolCount = tools.length;
+			} catch (error) {
+				cliError = error instanceof Error ? error.message : String(error);
+			}
+
+			const configured = Boolean(process.env.FORGEJO_URL && process.env.FORGEJO_ACCESS_TOKEN);
+			const lines = [
+				`forgejo-mcp command: ${getCommand()}`,
+				`CLI available: ${cliAvailable ? "yes" : "no"}`,
+				`FORGEJO_URL set: ${process.env.FORGEJO_URL ? "yes" : "no"}`,
+				`FORGEJO_ACCESS_TOKEN set: ${process.env.FORGEJO_ACCESS_TOKEN ? "yes" : "no"}`,
+				`Runtime configured: ${configured ? "yes" : "no"}`,
+			];
+			if (toolCount !== undefined) lines.push(`Discovered tools: ${toolCount}`);
+			if (cliError) lines.push(`CLI error: ${truncateForError(cliError)}`);
+
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: { command: getCommand(), cliAvailable, configured, toolCount, cliError },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "forgejo_mcp_list_tools",
+		label: "Forgejo MCP List Tools",
+		description: "List operations exposed by the official forgejo-mcp CLI. Output is truncated to 2000 lines or 50KB.",
+		promptSnippet: "List Forgejo MCP operations before calling an unfamiliar Forgejo operation.",
+		promptGuidelines: [
+			"Use forgejo_mcp_list_tools to discover Forgejo operation names before using forgejo_mcp_call when the exact operation is uncertain.",
+		],
+		parameters: Type.Object({
+			domain: Type.Optional(
+				Type.String({
+					description: "Optional domain/category filter, such as repo, issue, pull, user, org, release, actions.",
+				}),
+			),
+			query: Type.Optional(
+				Type.String({ description: "Optional case-insensitive substring filter for operation names or descriptions." }),
+			),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const domain = params.domain?.trim().toLowerCase();
+			const query = params.query?.trim().toLowerCase();
+			let tools = await listForgejoTools(signal);
+
+			if (domain) tools = tools.filter((tool) => tool.domain?.toLowerCase() === domain);
+			if (query) {
+				tools = tools.filter(
+					(tool) => tool.name.toLowerCase().includes(query) || (tool.description ?? "").toLowerCase().includes(query),
+				);
+			}
+
+			const output = await formatOutput(JSON.stringify(tools, null, 2), "");
+			return {
+				content: [{ type: "text", text: output.text }],
+				details: { count: tools.length, domain, query, ...output.details },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "forgejo_mcp_describe_tool",
+		label: "Forgejo MCP Describe Tool",
+		description: "Show parameters and help for one forgejo-mcp operation.",
+		promptSnippet: "Describe a Forgejo MCP operation's required and optional arguments.",
+		promptGuidelines: [
+			"Use forgejo_mcp_describe_tool before forgejo_mcp_call when you need the argument schema for a Forgejo operation.",
+		],
+		parameters: Type.Object({
+			tool: Type.String({ description: "forgejo-mcp operation name, for example list_repo_issues or create_issue." }),
+		}),
+		async execute(_toolCallId, params, signal) {
+			const tool = validateToolName(params.tool);
+			const result = await runForgejo(["--cli", tool, "--help"], { env: discoveryEnv(), signal });
+			ensureSuccess(result, `${tool} --help`);
+			const output = await formatOutput(result.stdout, result.stderr);
+			return {
+				content: [{ type: "text", text: output.text }],
+				details: { operation: tool, ...output.details },
+			};
+		},
+	});
+
+	pi.registerTool({
+		name: "forgejo_mcp_call",
+		label: "Forgejo MCP Call",
+		description:
+			"Invoke one operation from the official forgejo-mcp CLI. Requires FORGEJO_URL and FORGEJO_ACCESS_TOKEN in Pi's environment. Output is truncated to 2000 lines or 50KB.",
+		promptSnippet: "Call Forgejo operations via forgejo-mcp CLI using JSON arguments.",
+		promptGuidelines: [
+			"Use forgejo_mcp_call for Forgejo repository, issue, pull request, release, user, organization, workflow, and file operations.",
+			"Use forgejo_mcp_describe_tool before forgejo_mcp_call unless you already know the exact Forgejo operation arguments.",
+			"Do not put FORGEJO_ACCESS_TOKEN or other secrets in forgejo_mcp_call arguments; the extension reads credentials from the environment.",
+		],
+		parameters: Type.Object({
+			tool: Type.String({
+				description: "forgejo-mcp operation name, for example list_my_repos, list_repo_issues, or create_issue.",
+			}),
+			args: Type.Optional(
+				Type.Record(Type.String(), Type.Any({ description: "JSON argument value passed through to forgejo-mcp." }), {
+					description: "JSON arguments for the operation. Use {} when the operation takes no arguments.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			return callForgejoTool(params.tool, params.args as Record<string, unknown> | undefined, signal, ctx);
+		},
+	});
+}

package/extensions/forgejo-mcp/mutations.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const mutatingOperationPattern =
+	/^(add_|approve_|cancel_|create_|delete_|dismiss_|dispatch_|edit_|fork_|mark_|merge_|remove_|request_|reset_|start_|stop_|submit_|sync_|transfer_|update_|issue_state_change|pull_request_state_change)/;
+const destructiveOperationPattern = /^(delete_|remove_|merge_|transfer_|cancel_|dismiss_|reset_)/;
+
+export function truthy(value: string | undefined): boolean {
+	return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+
+export function falsy(value: string | undefined): boolean {
+	return value === "0" || value === "false" || value === "no" || value === "off";
+}
+
+export function isMutatingOperation(tool: string): boolean {
+	return mutatingOperationPattern.test(tool);
+}
+
+export function isDestructiveOperation(tool: string): boolean {
+	return destructiveOperationPattern.test(tool);
+}
+
+export function summarizeTarget(args: Record<string, unknown> | undefined): string {
+	if (!args) return "";
+	const owner = typeof args.owner === "string" ? args.owner : undefined;
+	const repo = typeof args.repo === "string" ? args.repo : undefined;
+	const index = typeof args.index === "number" || typeof args.index === "string" ? `#${args.index}` : undefined;
+
+	const parts: string[] = [];
+	if (owner && repo) parts.push(`${owner}/${repo}`);
+	else if (repo) parts.push(repo);
+	else if (owner) parts.push(owner);
+	if (index) parts.push(index);
+
+	return parts.length > 0 ? ` (${parts.join(" ")})` : "";
+}
+
+export async function confirmMutationIfNeeded(
+	ctx: ExtensionContext,
+	tool: string,
+	args: Record<string, unknown> | undefined,
+): Promise<void> {
+	if (!isMutatingOperation(tool)) return;
+
+	if (ctx.hasUI && !falsy(process.env.FORGEJO_MCP_CONFIRM_MUTATIONS)) {
+		const severity = isDestructiveOperation(tool) ? "destructive Forgejo operation" : "Forgejo write operation";
+		const ok = await ctx.ui.confirm("Confirm Forgejo operation", `Allow ${severity}: ${tool}${summarizeTarget(args)}?`);
+		if (!ok) throw new Error(`Cancelled Forgejo operation: ${tool}`);
+		return;
+	}
+
+	if (!truthy(process.env.FORGEJO_MCP_ALLOW_MUTATIONS)) {
+		throw new Error(
+			`Refusing to run mutating Forgejo operation ${tool} without UI confirmation. ` +
+				"Set FORGEJO_MCP_ALLOW_MUTATIONS=true to allow this in non-interactive mode.",
+		);
+	}
+}

package/extensions/forgejo-mcp.ts

@@ -0,0 +1 @@
+export { default } from "./forgejo-mcp/index.ts";

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "pi-forgejo-mcp",
+  "version": "0.1.0",
+  "description": "Pi extension that exposes Forgejo via the official forgejo-mcp CLI.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ozzy",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/ozzy92/pi-forgejo-mcp.git"
+  },
+  "homepage": "https://codeberg.org/ozzy92/pi-forgejo-mcp",
+  "bugs": {
+    "url": "https://codeberg.org/ozzy92/pi-forgejo-mcp/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "forgejo",
+    "mcp",
+    "model-context-protocol",
+    "codeberg"
+  ],
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/forgejo-mcp/index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --check . --ignore-unknown",
+    "format:write": "prettier --write . --ignore-unknown",
+    "test": "vitest run",
+    "check": "npm run typecheck && npm run lint && npm run format && npm run test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.77.0",
+    "@earendil-works/pi-coding-agent": "^0.77.0",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.4.0",
+    "globals": "^17.6.0",
+    "prettier": "^3.8.3",
+    "typescript": "^5.9.0",
+    "typescript-eslint": "^8.60.0",
+    "vitest": "^4.1.7"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}