@mokoconsulting/mcp-mokogitea-api 1.4.0 → 1.4.1

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 |