Architecture

Component Overview

src/
  index.ts    -- MCP server entry point, tool registrations (120+ tools)
  client.ts   -- HTTP client for MokoGitea REST API v1
  config.ts   -- Configuration loader (multi-connection support)
  types.ts    -- TypeScript type definitions
  server.ts   -- Server factory for embedded use
  sse.ts      -- SSE transport for hosted deployments

index.ts -- Server Entry Point

The main module that:

Creates the McpServer instance with stdio transport
Loads configuration on startup via loadConfig()
Registers all 120+ tools organized by category
Provides shared parameter schemas (OwnerRepo, PaginationParams, ConnectionParam)
Routes tool calls through clientFor(connection) to resolve the target MokoGitea instance
Formats all API responses through formatResponse() for consistent MCP output

client.ts -- HTTP Client

GiteaClient is a zero-dependency HTTP client built on node:https and node:http:

Prepends /api/v1 to all endpoint paths
Sets Authorization: token <token> header on every request
Supports GET, POST, PUT, PATCH, DELETE methods
Handles query parameter construction via URL.searchParams
Parses JSON responses automatically
30-second request timeout
Optional TLS certificate verification bypass (insecure flag)

config.ts -- Configuration Loader

Loads the connection configuration from disk:

Default path: ~/.mcp_mokogitea.json
Override via GITEA_API_MCP_CONFIG environment variable
Also supports GITEA_URL + GITEA_TOKEN environment variables for single-instance setup
Validates that at least one connection exists
Sets defaultConnection to the first connection if not explicitly specified
getConnection() resolves a named connection or falls back to the default

types.ts -- Type Definitions

Three core interfaces:

GiteaConnection -- Single connection config (baseUrl, token, insecure?)
GiteaConfig -- Full config with named connections map and default
ApiResponse -- Standardized response wrapper (status, data)

Key Tool Patterns

Metadata Tools (`gitea_metadata_get` / `gitea_metadata_update`)

Repository metadata is stored server-side via the MokoGitea API (/repos/{owner}/{repo}/metadata). The update tool uses merge semantics: it fetches the current metadata, spreads it into a new object, then overwrites only the fields you provide. Read-only and deprecated fields (display_name, package_type) are stripped before the PUT.

Writable fields:

Field	Example	Description
`name`	`MokoSuiteCRM`	Project name
`org`	`MokoConsulting`	Organization
`description`	`Layer 1 — CRM...`	Project description
`license_spdx`	`GPL-3.0-or-later`	SPDX license identifier
`license_name`	`GNU General Public License v3`	Human-readable license
`element_name`	`pkg_mokosuitecrm`	Extension element name
`platform`	`joomla`	Platform (joomla, go, mcp, etc.)
`standards_version`	`05.01.00`	mokoplatform standards version
`standards_source`	`https://git..../mokoplatform`	Standards repo URL
`maintainer`	`Moko Consulting`	Maintainer name
`maintainer_url`	`https://mokoconsulting.tech`	Maintainer website
`info_url`	`https://mokoconsulting.tech/support/...`	Product info page
`target_version`	`6..*`	Target platform version
`php_minimum`	`8.1`	Minimum PHP version
`language`	`PHP`	Primary language
`extension_type`	`package`	Extension type
`entry_point`	`source/`	Build entry point

Read-only fields (in GET response only):

Field	Example	Description
`display_name`	`Package - MokoSuiteBackup`	Computed from `extension_type` + `name`

Bulk File Push (`gitea_bulk_file_push`)

Pushes a single file to multiple repos in one operation. Supports two modes:

Explicit repos: provide a repos array of repository names
Platform discovery: provide a platform string (e.g. joomla) to auto-discover all repos in the org with that metadata platform

Design Decisions

Pages