@mokoconsulting/mcp-mokogitea-api 1.4.0 → 1.4.2

package/wiki/ARCHITECTURE.md

@@ -1,144 +0,0 @@
-← [Home](Home)
-
-# 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
-
----
-
-*Repo: [gitea-api-mcp](https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp) . [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/mokoplatform/wiki/Home)*
-
-| Revision | Date | Author | Description |
-|---|---|---|---|
-| 1.0 | 2026-05-09 | Moko Consulting | Initial version |

package/wiki/Home.md

@@ -1,35 +0,0 @@
-# gitea-api-mcp
-
-MCP server for Gitea REST API v1 operations — 61 tools for repos, issues, PRs, releases, branches, actions, orgs, wiki, webhooks, and more
-
-| Field | Value |
-|---|---|
-| **Language** | Markdown |
-| **License** | GPL-3.0-or-later |
-| **Platform** | [Gitea](https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp) |
-
----
-
-## Guides
-
-| Page | Description |
-|---|---|
-| [INSTALLATION](INSTALLATION) | - **Node.js** >= 20.0.0 ([download](https://nodejs.org)) |
-
-## Reference
-
-| Page | Description |
-|---|---|
-| [ARCHITECTURE](ARCHITECTURE) | index.ts    -- MCP server entry point, tool registrations (61 tools) |
-
----
-
-> [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/mokoplatform/wiki/Home)
-
----
-
-*Repo: [gitea-api-mcp](https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp) . [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/mokoplatform/wiki/Home)*
-
-| Revision | Date | Author | Description |
-|---|---|---|---|
-| 1.0 | 2026-05-09 | Moko Consulting | Initial version |

package/wiki/INSTALLATION.md

@@ -1,170 +0,0 @@
-← [Home](Home)
-
-# Installation Guide
-
-## Prerequisites
-
-- **Node.js** >= 20.0.0 ([download](https://nodejs.org))
-- **npm** (included with Node.js)
-- A **Gitea instance** with API access enabled
-- A **Gitea access token** with appropriate scopes
-
-## Install
-
-### Clone and Build
-
-```bash
-git clone https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp.git
-cd gitea-api-mcp
-npm install
-npm run build
-```
-
-The compiled output is placed in `dist/index.js`.
-
-### Verify the Build
-
-```bash
-node dist/index.js --help
-```
-
-## Gitea Token Generation
-
-1. Log in to your Gitea instance (e.g., `https://git.mokoconsulting.tech`)
-2. Navigate to **Settings** (click your avatar, top-right corner)
-3. Select **Applications** from the sidebar
-4. Under **Manage Access Tokens**, enter a descriptive token name (e.g., `mcp-server`)
-5. Select the required permission scopes:
-   - `repo` -- for repository operations
-   - `admin:org` -- for organization management
-   - `notification` -- for notification tools
-   - `user` -- for user profile operations
-   - `issue` -- for issue and pull request tools
-   - `package` -- if using package-related endpoints
-6. Click **Generate Token**
-7. **Copy the token immediately** -- it will not be displayed again
-
-## Configuration
-
-### Config File Format
-
-Create `~/.gitea-api-mcp.json`:
-
-```json
-{
-  "defaultConnection": "moko",
-  "connections": {
-    "moko": {
-      "baseUrl": "https://git.mokoconsulting.tech",
-      "token": "your-gitea-access-token",
-      "insecure": false
-    }
-  }
-}
-```
-
-### Config Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `defaultConnection` | string | No | Name of the default connection (defaults to the first one) |
-| `connections` | object | Yes | Map of named connections |
-| `connections.<name>.baseUrl` | string | Yes | Base URL of the Gitea instance (no trailing slash) |
-| `connections.<name>.token` | string | Yes | Gitea API access token |
-| `connections.<name>.insecure` | boolean | No | Skip TLS certificate verification (default: `false`) |
-
-### Custom Config Path
-
-Override the default config location with an environment variable:
-
-```bash
-export GITEA_API_MCP_CONFIG=/path/to/custom-config.json
-```
-
-### File Permissions
-
-Secure your config file since it contains API tokens:
-
-```bash
-chmod 600 ~/.gitea-api-mcp.json
-```
-
-## Claude Code Registration
-
-### Project-Level (`.mcp.json`)
-
-Create or edit `.mcp.json` in your project root:
-
-```json
-{
-  "mcpServers": {
-    "gitea-moko": {
-      "command": "node",
-      "args": ["/absolute/path/to/gitea-api-mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-### Global-Level (`~/.claude/claude_desktop_config.json`)
-
-```json
-{
-  "mcpServers": {
-    "gitea-moko": {
-      "command": "node",
-      "args": ["/absolute/path/to/gitea-api-mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-After registering, restart Claude Code or run `/mcp` to verify the server is connected.
-
-## Troubleshooting
-
-### "Failed to load config" Error
-
-- Verify `~/.gitea-api-mcp.json` exists and is valid JSON
-- Check that at least one connection is defined in `connections`
-- If using `GITEA_API_MCP_CONFIG`, verify the path is correct and the file is readable
-
-### "Connection not found" Error
-
-- The `connection` parameter you passed does not match any key in `connections`
-- Run `gitea_list_connections` to see available connections
-- Check for typos in the connection name
-
-### Authentication Failures (HTTP 401)
-
-- Verify your token is correct and has not expired
-- Ensure the token has the required scopes for the operation
-- Check that the `baseUrl` points to the correct Gitea instance
-- Confirm the Gitea instance has API access enabled (admin setting)
-
-### TLS / Certificate Errors
-
-- For self-signed certificates, set `"insecure": true` in the connection config
-- Ensure the Gitea instance URL uses the correct protocol (`https://` vs `http://`)
-
-### Timeout Errors
-
-- The default request timeout is 30 seconds
-- Check network connectivity to the Gitea instance
-- Verify the Gitea instance is running and responsive
-- For large responses (e.g., recursive tree listings), consider pagination
-
-### MCP Server Not Appearing in Claude Code
-
-- Ensure the path in your MCP config is an absolute path to `dist/index.js`
-- Verify the build completed successfully (`npm run build`)
-- Check that Node.js >= 20.0.0 is in your PATH
-- Restart Claude Code after modifying MCP configuration
-
----
-
-*Repo: [gitea-api-mcp](https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp) . [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/mokoplatform/wiki/Home)*
-
-| Revision | Date | Author | Description |
-|---|---|---|---|
-| 1.0 | 2026-05-09 | Moko Consulting | Initial version |