forgejo-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

npm run build          # Compile TypeScript to dist/
npm run dev            # Run stdio server (tsx, no build needed)
npm run dev:http       # Run HTTP server on port 3000
npm test               # Run all tests
npm run test:watch     # Watch mode
npx vitest run src/__tests__/tools/repository.test.ts  # Run a single test file
npm run lint           # ESLint

Architecture

This is an MCP (Model Context Protocol) server for Forgejo/Gitea instances, providing 457 tools across 9 categories. It has two transport modes: stdio (for Claude Code/Desktop) and HTTP (for remote access).

Request Flow

Entry point (index.ts or http.ts)
  → config.ts (loads env vars / CLI args, validates URL for SSRF)
  → server.ts (creates McpServer, registers all tool groups)
  → tools/*.ts (each tool calls ForgejoClient methods)
  → client.ts (wraps fetch with token auth, hits /api/v1)

Key Modules

• server.ts — Factory that creates McpServer and calls nine register*Tools() functions (one per file in tools/). In lazy mode (--lazy / FORGEJO_LAZY_TOOLS, off by default) it registers every tool disabled plus a load_tool_area tool that enables an area's tools and sends notifications/tools/list_changed; this only works in clients that refetch the tool list mid-session
• client.ts — ForgejoClient class with get/post/patch/put/delete/getRaw methods. Errors are wrapped in ForgejoApiError with sanitized URLs (no token leakage). Refuses request paths containing ./.. segments or unencoded ?, #, or backslashes
• compact.ts — Wraps the SDK's tools/list handler to strip validation-only schema keywords and boilerplate from the tool list sent to clients (saves context; Zod validation is unchanged). The compacted list is cached by a key that server.ts supplies per request, which must identify the tools currently enabled (in lazy mode this includes the loaded areas)
• config.ts — resolveConfig() merges CLI args > env vars > defaults. Tool areas (TOOL_AREAS) can be disabled with --disable-<area> / --disable a,b or FORGEJO_DISABLED_AREAS; server.ts skips those groups. validateBaseUrl() blocks SSRF (cloud metadata IPs, private ranges)
• validation.ts — Centralized Zod schemas (zOwner, zRepo, zFilePath, zPage, zLimit, etc.) shared across all tool files
• tools/helpers.ts — formatResponse(data) and formatError(err) produce the MCP content format; encodePath(value) percent-encodes a slash-separated value for use in a request path
• http.ts — HTTP transport: one McpServer + transport per client session (LRU-capped), RateLimiter class, optional Bearer auth (FORGEJO_MCP_API_KEY), Origin check when unauthenticated, security headers, /health endpoint