mcp-mokogitea-api/docs/ARCHITECTURE.md

<!-- Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
SPDX-License-Identifier: GPL-3.0-or-later
DEFGROUP: gitea-api-mcp.Documentation
REPO: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp
-->

# Architecture

## Component Overview

```
src/
  index.ts    -- MCP server entry point, tool registrations (61 tools)
  client.ts   -- HTTP client for Gitea REST API v1
  config.ts   -- Configuration loader (multi-connection support)
  types.ts    -- TypeScript type definitions
```

### index.ts -- Server Entry Point

The main module that:

- Creates the `McpServer` instance with stdio transport
- Loads configuration on startup via `loadConfig()`
- Registers all 61 tools organized by category
- Provides shared parameter schemas (`OwnerRepo`, `PaginationParams`, `ConnectionParam`)
- Routes tool calls through `clientFor(connection)` to resolve the target Gitea 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 (Gitea's native auth format)
- 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: `~/.gitea-api-mcp.json`
- Override via `GITEA_API_MCP_CONFIG` environment variable
- 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`)

## Design Decisions

### Token Authentication

Gitea uses `Authorization: token <access-token>` as its native authentication header format, unlike GitHub's `Bearer` token format. This server uses the native Gitea format directly, ensuring compatibility with all Gitea versions without requiring OAuth2 setup.

### Multi-Connection Architecture

Every tool accepts an optional `connection` parameter. This enables:

- Managing multiple Gitea instances from a single MCP server
- Switching between production, staging, and development instances
- Cross-instance operations within a single Claude Code session

The connection is resolved at call time, not at startup, so different tool calls can target different instances.

### node:https (Zero HTTP Dependencies)

The HTTP client uses Node.js built-in `node:https` and `node:http` modules instead of third-party libraries (e.g., axios, node-fetch). This decision:

- Eliminates supply-chain risk from HTTP client dependencies
- Reduces `node_modules` size
- Avoids compatibility issues across Node.js versions
- Provides full control over TLS configuration (needed for `insecure` flag)

### Stdio Transport

The MCP server uses stdio transport (stdin/stdout) rather than HTTP/SSE. This means:

- No network ports are opened by the server
- Tokens are never exposed through HTTP endpoints
- The server runs as a child process of the MCP client
- Communication is process-local, reducing attack surface

### Shared Parameter Objects

Common parameter patterns are defined as reusable objects:

- `OwnerRepo` -- `{ owner, repo }` for all repository-scoped operations
- `PaginationParams` -- `{ page, limit }` for all list endpoints
- `ConnectionParam` -- `{ connection }` for multi-connection routing

This ensures consistency across all 61 tools and simplifies adding new tools.

## Data Flow

```
                        +-----------------+
                        |  Claude Code /  |
                        |  MCP Client     |
                        +--------+--------+
                                 |
                            stdio (JSON-RPC)
                                 |
                        +--------v--------+
                        |  index.ts       |
                        |  McpServer      |
                        |  (tool router)  |
                        +--------+--------+
                                 |
                     +-----------+-----------+
                     |                       |
              +------v------+        +-------v-------+
              |  config.ts  |        |  client.ts    |
              |  loadConfig |        |  GiteaClient  |
              |  getConn    |        |  (HTTP calls) |
              +------+------+        +-------+-------+
                     |                        |
              +------v------+         HTTPS / HTTP
              | ~/.gitea-   |                 |
              | api-mcp.json|        +--------v--------+
              +-------------+        |  Gitea Instance |
                                     |  /api/v1/*      |
                                     +-----------------+
```

1. Claude Code sends a JSON-RPC tool call over stdio
2. `McpServer` routes the call to the registered tool handler
3. The handler calls `clientFor(connection)` which resolves the connection from config
4. `GiteaClient` constructs the HTTP request and sends it to the Gitea API
5. The JSON response is wrapped in `formatResponse()` and returned to the MCP client