@mokoconsulting/mcp-mokogitea-api 1.3.0 → 1.4.0

package/.mokogitea/workflows/npm-publish.yml

@@ -28,24 +28,27 @@ jobs:
       - name: Build
         run: npm run build
 
-      - name: Check if version changed
-        id: version
+      - name: Auto-bump patch version
         run: |
           PKG_NAME=$(node -p "require('./package.json').name")
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          PUBLISHED=$(npm view "${PKG_NAME}@${PKG_VERSION}" version 2>/dev/null || echo "")
-          if [ "$PUBLISHED" = "$PKG_VERSION" ]; then
-            echo "skip=true" >> "$GITHUB_OUTPUT"
-            echo "Version ${PKG_VERSION} already published, skipping."
+          CURRENT=$(node -p "require('./package.json').version")
+          PUBLISHED=$(npm view "${PKG_NAME}@latest" version 2>/dev/null || echo "0.0.0")
+          if [ "$CURRENT" = "$PUBLISHED" ]; then
+            npm version patch --no-git-tag-version
+            NEW_VER=$(node -p "require('./package.json').version")
+            echo "Bumped ${CURRENT} -> ${NEW_VER}"
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            git add package.json
+            git commit -m "chore: bump to ${NEW_VER} [skip ci]"
+            git push
           else
-            echo "skip=false" >> "$GITHUB_OUTPUT"
-            echo "Publishing ${PKG_NAME}@${PKG_VERSION}"
+            echo "Version ${CURRENT} not yet published, using as-is."
           fi
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Publish
-        if: steps.version.outputs.skip != 'true'
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --production=false
+
+COPY tsconfig.json ./
+COPY src/ ./src/
+RUN npx tsc && npm prune --production
+
+EXPOSE 3100
+
+ENV PORT=3100
+ENV NODE_ENV=production
+
+# SSE mode by default for Docker deployments
+CMD ["node", "dist/sse.js"]

package/README.md

@@ -250,12 +250,15 @@ If `connection` is omitted, the `defaultConnection` is used.
 | `gitea_webhooks_list` | List webhooks for a repository |
 | `gitea_webhook_create` | Create a webhook |
 
-### Wiki (2 tools)
+### Wiki (5 tools)
 
 | Tool | Description |
 |------|-------------|
 | `gitea_wiki_pages_list` | List wiki pages |
 | `gitea_wiki_page_get` | Get a wiki page |
+| `gitea_wiki_page_create` | Create a new wiki page |
+| `gitea_wiki_page_edit` | Edit an existing wiki page |
+| `gitea_wiki_page_delete` | Delete a wiki page |
 
 ### Notifications (2 tools)
 

package/dist/index.js

@@ -690,6 +690,43 @@ server.tool('gitea_webhook_create', 'Create a webhook', {
 // ── Wiki ────────────────────────────────────────────────────────────────
 server.tool('gitea_wiki_pages_list', 'List wiki pages', { ...OwnerRepo, ...PaginationParams, ...ConnectionParam }, async ({ owner, repo, page, limit, connection }) => formatResponse(await clientFor(connection).get(`/repos/${owner}/${repo}/wiki/pages`, pageQuery({ page, limit }))));
 server.tool('gitea_wiki_page_get', 'Get a wiki page', { ...OwnerRepo, page_name: z.string().describe('Page name/slug'), ...ConnectionParam }, async ({ owner, repo, page_name, connection }) => formatResponse(await clientFor(connection).get(`/repos/${owner}/${repo}/wiki/page/${page_name}`)));
+server.tool('gitea_wiki_page_create', 'Create a new wiki page', {
+    ...OwnerRepo,
+    title: z.string().describe('Page title'),
+    content: z.string().describe('Page content (markdown)'),
+    message: z.string().optional().describe('Commit message for the wiki change'),
+    ...ConnectionParam,
+}, async ({ owner, repo, title, content, message, connection }) => {
+    const body = {
+        title,
+        content_base64: Buffer.from(content).toString('base64'),
+    };
+    if (message !== undefined)
+        body.message = message;
+    return formatResponse(await clientFor(connection).post(`/repos/${owner}/${repo}/wiki/pages`, body));
+});
+server.tool('gitea_wiki_page_edit', 'Edit an existing wiki page', {
+    ...OwnerRepo,
+    page_name: z.string().describe('Current page name/slug'),
+    content: z.string().describe('New page content (markdown)'),
+    title: z.string().optional().describe('New page title (to rename)'),
+    message: z.string().optional().describe('Commit message for the wiki change'),
+    ...ConnectionParam,
+}, async ({ owner, repo, page_name, content, title, message, connection }) => {
+    const body = {
+        content_base64: Buffer.from(content).toString('base64'),
+    };
+    if (title !== undefined)
+        body.title = title;
+    if (message !== undefined)
+        body.message = message;
+    return formatResponse(await clientFor(connection).patch(`/repos/${owner}/${repo}/wiki/page/${page_name}`, body));
+});
+server.tool('gitea_wiki_page_delete', 'Delete a wiki page', {
+    ...OwnerRepo,
+    page_name: z.string().describe('Page name/slug to delete'),
+    ...ConnectionParam,
+}, async ({ owner, repo, page_name, connection }) => formatResponse(await clientFor(connection).delete(`/repos/${owner}/${repo}/wiki/page/${page_name}`)));
 // ── Notifications ───────────────────────────────────────────────────────
 server.tool('gitea_notifications_list', 'List notifications for the authenticated user', {
     status_types: z.string().optional().describe('Comma-separated: read, unread, pinned'),

package/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GiteaConfig } from './types.js';
+export declare function createMcpServer(cfg: GiteaConfig): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,12 @@
+// Copyright 2026 Moko Consulting <hello@mokoconsulting.tech>
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Creates a configured MCP server instance for use by both stdio and SSE transports.
+// Import index.ts to register all tools on its exported `server` singleton,
+// then re-export a factory that initializes config and returns the server.
+import { server, initConfig } from './index.js';
+export function createMcpServer(cfg) {
+    initConfig(cfg);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/sse.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.js

@@ -0,0 +1,87 @@
+// Copyright 2026 Moko Consulting <hello@mokoconsulting.tech>
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// SSE transport entry point for MokoGitea MCP server.
+// Run with: node dist/sse.js
+// Or: GITEA_URL=https://gitea.example.com GITEA_TOKEN=xxx node dist/sse.js
+//
+// Listens on PORT (default 3100) and serves SSE at /sse with POST at /message.
+import { createServer } from 'node:http';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createMcpServer } from './server.js';
+import { loadConfig } from './config.js';
+const PORT = parseInt(process.env.PORT ?? '3100', 10);
+async function main() {
+    const config = await loadConfig();
+    const transports = new Map();
+    const httpServer = createServer(async (req, res) => {
+        // CORS headers for browser clients
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        // Health check
+        if (req.url === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', tools: 120 }));
+            return;
+        }
+        // SSE endpoint - client connects here
+        if (req.url === '/sse' && req.method === 'GET') {
+            const transport = new SSEServerTransport('/message', res);
+            const sessionId = transport.sessionId;
+            transports.set(sessionId, transport);
+            const server = createMcpServer(config);
+            await server.connect(transport);
+            req.on('close', () => {
+                transports.delete(sessionId);
+            });
+            return;
+        }
+        // Message endpoint - client sends tool calls here
+        if (req.url?.startsWith('/message') && req.method === 'POST') {
+            const url = new URL(req.url, `http://${req.headers.host}`);
+            const sessionId = url.searchParams.get('sessionId');
+            if (!sessionId || !transports.has(sessionId)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Invalid or missing sessionId' }));
+                return;
+            }
+            const transport = transports.get(sessionId);
+            await transport.handlePostMessage(req, res);
+            return;
+        }
+        // Root - info page
+        if (req.url === '/' || req.url === '') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                name: '@mokoconsulting/mokogitea-mcp',
+                version: '1.1.0',
+                description: 'MCP server for Gitea and MokoGitea - 120+ tools',
+                endpoints: {
+                    sse: '/sse',
+                    message: '/message',
+                    health: '/health',
+                },
+                docs: 'https://git.mokoconsulting.tech/MokoConsulting/mcp_mokogitea_api',
+            }));
+            return;
+        }
+        res.writeHead(404);
+        res.end('Not found');
+    });
+    httpServer.listen(PORT, () => {
+        process.stderr.write(`MokoGitea MCP SSE server listening on port ${PORT}\n`);
+        process.stderr.write(`  SSE: http://localhost:${PORT}/sse\n`);
+        process.stderr.write(`  Health: http://localhost:${PORT}/health\n`);
+    });
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=sse.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@mokoconsulting/mcp-mokogitea-api",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "MCP server for Gitea REST API v1 operations",
 	"type": "module",
 	"main": "dist/index.js",
@@ -29,6 +29,6 @@
 	"author": "Moko Consulting <hello@mokoconsulting.tech>",
 	"repository": {
 		"type": "git",
-		"url": "https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp.git"
+		"url": "https://git.mokoconsulting.tech/MokoConsulting/mcp-mokogitea-api.git"
 	}
 }

package/src/index.ts

@@ -1059,6 +1059,59 @@ server.tool(
 	async ({ owner, repo, page_name, connection }) => formatResponse(await clientFor(connection).get(`/repos/${owner}/${repo}/wiki/page/${page_name}`)),
 );
 
+server.tool(
+	'gitea_wiki_page_create',
+	'Create a new wiki page',
+	{
+		...OwnerRepo,
+		title: z.string().describe('Page title'),
+		content: z.string().describe('Page content (markdown)'),
+		message: z.string().optional().describe('Commit message for the wiki change'),
+		...ConnectionParam,
+	},
+	async ({ owner, repo, title, content, message, connection }) => {
+		const body: Record<string, unknown> = {
+			title,
+			content_base64: Buffer.from(content).toString('base64'),
+		};
+		if (message !== undefined) body.message = message;
+		return formatResponse(await clientFor(connection).post(`/repos/${owner}/${repo}/wiki/pages`, body));
+	},
+);
+
+server.tool(
+	'gitea_wiki_page_edit',
+	'Edit an existing wiki page',
+	{
+		...OwnerRepo,
+		page_name: z.string().describe('Current page name/slug'),
+		content: z.string().describe('New page content (markdown)'),
+		title: z.string().optional().describe('New page title (to rename)'),
+		message: z.string().optional().describe('Commit message for the wiki change'),
+		...ConnectionParam,
+	},
+	async ({ owner, repo, page_name, content, title, message, connection }) => {
+		const body: Record<string, unknown> = {
+			content_base64: Buffer.from(content).toString('base64'),
+		};
+		if (title !== undefined) body.title = title;
+		if (message !== undefined) body.message = message;
+		return formatResponse(await clientFor(connection).patch(`/repos/${owner}/${repo}/wiki/page/${page_name}`, body));
+	},
+);
+
+server.tool(
+	'gitea_wiki_page_delete',
+	'Delete a wiki page',
+	{
+		...OwnerRepo,
+		page_name: z.string().describe('Page name/slug to delete'),
+		...ConnectionParam,
+	},
+	async ({ owner, repo, page_name, connection }) =>
+		formatResponse(await clientFor(connection).delete(`/repos/${owner}/${repo}/wiki/page/${page_name}`)),
+);
+
 // ── Notifications ───────────────────────────────────────────────────────
 
 server.tool(

package/src/server.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 Moko Consulting <hello@mokoconsulting.tech>
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// Creates a configured MCP server instance for use by both stdio and SSE transports.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GiteaConfig } from './types.js';
+
+// Import index.ts to register all tools on its exported `server` singleton,
+// then re-export a factory that initializes config and returns the server.
+import { server, initConfig } from './index.js';
+
+export function createMcpServer(cfg: GiteaConfig): McpServer {
+	initConfig(cfg);
+	return server;
+}

package/src/sse.ts

@@ -0,0 +1,100 @@
+// Copyright 2026 Moko Consulting <hello@mokoconsulting.tech>
+// SPDX-License-Identifier: GPL-3.0-or-later
+//
+// SSE transport entry point for MokoGitea MCP server.
+// Run with: node dist/sse.js
+// Or: GITEA_URL=https://gitea.example.com GITEA_TOKEN=xxx node dist/sse.js
+//
+// Listens on PORT (default 3100) and serves SSE at /sse with POST at /message.
+
+import { createServer } from 'node:http';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { createMcpServer } from './server.js';
+import { loadConfig } from './config.js';
+
+const PORT = parseInt(process.env.PORT ?? '3100', 10);
+
+async function main(): Promise<void> {
+	const config = await loadConfig();
+	const transports = new Map<string, SSEServerTransport>();
+
+	const httpServer = createServer(async (req, res) => {
+		// CORS headers for browser clients
+		res.setHeader('Access-Control-Allow-Origin', '*');
+		res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+		res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+
+		if (req.method === 'OPTIONS') {
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+
+		// Health check
+		if (req.url === '/health') {
+			res.writeHead(200, { 'Content-Type': 'application/json' });
+			res.end(JSON.stringify({ status: 'ok', tools: 120 }));
+			return;
+		}
+
+		// SSE endpoint - client connects here
+		if (req.url === '/sse' && req.method === 'GET') {
+			const transport = new SSEServerTransport('/message', res);
+			const sessionId = transport.sessionId;
+			transports.set(sessionId, transport);
+
+			const server = createMcpServer(config);
+			await server.connect(transport);
+
+			req.on('close', () => {
+				transports.delete(sessionId);
+			});
+			return;
+		}
+
+		// Message endpoint - client sends tool calls here
+		if (req.url?.startsWith('/message') && req.method === 'POST') {
+			const url = new URL(req.url, `http://${req.headers.host}`);
+			const sessionId = url.searchParams.get('sessionId');
+			if (!sessionId || !transports.has(sessionId)) {
+				res.writeHead(400, { 'Content-Type': 'application/json' });
+				res.end(JSON.stringify({ error: 'Invalid or missing sessionId' }));
+				return;
+			}
+			const transport = transports.get(sessionId)!;
+			await transport.handlePostMessage(req, res);
+			return;
+		}
+
+		// Root - info page
+		if (req.url === '/' || req.url === '') {
+			res.writeHead(200, { 'Content-Type': 'application/json' });
+			res.end(JSON.stringify({
+				name: '@mokoconsulting/mokogitea-mcp',
+				version: '1.1.0',
+				description: 'MCP server for Gitea and MokoGitea - 120+ tools',
+				endpoints: {
+					sse: '/sse',
+					message: '/message',
+					health: '/health',
+				},
+				docs: 'https://git.mokoconsulting.tech/MokoConsulting/mcp_mokogitea_api',
+			}));
+			return;
+		}
+
+		res.writeHead(404);
+		res.end('Not found');
+	});
+
+	httpServer.listen(PORT, () => {
+		process.stderr.write(`MokoGitea MCP SSE server listening on port ${PORT}\n`);
+		process.stderr.write(`  SSE: http://localhost:${PORT}/sse\n`);
+		process.stderr.write(`  Health: http://localhost:${PORT}/health\n`);
+	});
+}
+
+main().catch((err) => {
+	process.stderr.write(`Fatal: ${err}\n`);
+	process.exit(1);
+});

package/tsconfig.json

@@ -15,5 +15,5 @@
 		"sourceMap": true
 	},
 	"include": ["src/**/*"],
-	"exclude": ["node_modules", "dist"]
+	"exclude": ["node_modules", "dist", "src/server.ts", "src/sse.ts"]
 }

package/wiki/ARCHITECTURE.md

@@ -0,0 +1,144 @@
+← [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

@@ -0,0 +1,35 @@
+# 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

@@ -0,0 +1,170 @@
+← [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 |