@mokoconsulting/mcp-mokogitea-api 1.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,161 @@
+# Contributing to Moko Consulting Projects
+
+Thank you for your interest in contributing. All Moko Consulting repositories follow this universal workflow and version policy.
+
+## Branching Workflow
+
+```
+feature/* ──PR──> dev ──draft PR──> (renamed to rc) ──merge──> main
+```
+
+### Step by step
+
+1. **Create a feature branch** from `dev`:
+   ```bash
+   git checkout dev && git pull
+   git checkout -b feature/my-change
+   ```
+
+2. **Work and commit** on your feature branch. Push to origin.
+
+3. **Open a PR**: `feature/my-change` → `dev`. After review and checks, merge it.
+
+4. **When ready for release**, open a **draft PR**: `dev` → `main`.
+   - This automatically renames the source branch to `rc` (release candidate)
+   - An RC pre-release is built and uploaded
+
+5. **Alpha and beta branches** are created by manually renaming the branch before the RC stage:
+   - Rename `dev` to `alpha` for early testing → alpha pre-release is built
+   - Rename `alpha` to `beta` for feature-complete testing → beta pre-release is built
+   - When the draft PR is created, the branch is renamed to `rc`
+
+6. **Once PR checks pass** on the `rc` branch, mark the PR as ready and merge to `main`.
+
+7. **Merging to main** triggers the stable release pipeline:
+   - Minor version bump (e.g., `02.09.xx` → `02.10.00`)
+   - Stability suffix stripped (clean version)
+   - Gitea release created with ZIP/tar.gz packages
+   - `updates.xml` updated (Joomla extensions)
+   - `dev` branch recreated from `main`
+
+### Branch summary
+
+| Branch | Purpose | Created by |
+|--------|---------|-----------|
+| `feature/*` | New features and fixes | Developer |
+| `dev` | Integration branch | Auto-recreated after release |
+| `alpha` | Alpha pre-release testing | Manual rename from `dev` |
+| `beta` | Beta pre-release testing | Manual rename from `alpha` |
+| `rc` | Release candidate | Auto-renamed on draft PR to main |
+| `main` | Stable releases | Protected, merge only |
+| `version/XX.YY.ZZ` | Archived release snapshots | Auto-created by CI |
+
+### Protected branches
+
+| Branch | Direct push | Merge via |
+|--------|------------|-----------|
+| `main` | Blocked (CI bot whitelisted) | PR merge only |
+| `dev` | Blocked (CI bot whitelisted) | PR merge from feature/* |
+| `rc` | Blocked (CI bot whitelisted) | Auto-created on draft PR |
+| `alpha` | Blocked (CI bot whitelisted) | Manual rename |
+| `beta` | Blocked (CI bot whitelisted) | Manual rename |
+| `feature/*` | Open | N/A (source branch) |
+
+## Version Policy
+
+### Format
+
+All versions use `XX.YY.ZZ` — three two-digit segments, zero-padded:
+
+- **XX** — Major version (breaking changes)
+- **YY** — Minor version (new features, bumped on release to main)
+- **ZZ** — Patch version (auto-incremented on every push to dev/feature branches)
+
+Rollover: patch `99` → `00` increments minor; minor `99` → `00` increments major.
+
+### Stability suffixes
+
+Each branch appends a suffix to indicate stability:
+
+| Branch | Suffix | Example |
+|--------|--------|---------|
+| `main` | (none) | `02.09.00` |
+| `dev` | `-dev` | `02.09.01-dev` |
+| `feature/*` | `-dev` | `02.09.01-dev` |
+| `alpha` | `-alpha` | `02.09.01-alpha` |
+| `beta` | `-beta` | `02.09.01-beta` |
+| `rc` | `-rc` | `02.09.01-rc` |
+
+### Auto version bump
+
+On every push to `dev`, `feature/*`, or `patch/*`:
+
+1. Patch version incremented
+2. Stability suffix `-dev` applied
+3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.)
+4. Commit created with `[skip ci]` to avoid loops
+
+### Release version flow
+
+Version bumps happen at specific release events:
+
+| Event | Bump | Example |
+|-------|------|---------|
+| Feature merged to dev | Patch bump after dev release | `02.09.01-dev` → release → `02.09.02-dev` |
+| Dev promoted to RC | Minor bump | `02.09.02-dev` → `02.10.00-rc` |
+| RC merged to main | Minor bump | `02.10.00-rc` → `02.11.00` (stable) |
+| Dev recreated from main | Patch bump | `02.11.00` → `02.11.01-dev` |
+
+### Release stream copies
+
+When a higher-stability release is published, copies are created for all lesser streams with the same base version:
+
+- **RC `02.10.00-rc`** also creates: `02.10.00-dev`, `02.10.00-alpha`, `02.10.00-beta`
+- **Stable `02.11.00`** also creates: `02.11.00-dev`, `02.11.00-alpha`, `02.11.00-beta`, `02.11.00-rc`
+
+This ensures Joomla sites on ANY stability channel see the update (Joomla only shows versions higher than what's installed).
+
+### Version files
+
+The version tools update all files containing version stamps:
+
+- `.mokogitea/manifest.xml` (canonical source)
+- Joomla XML manifests (`<version>` tag)
+- `README.md`, `CHANGELOG.md` (`VERSION:` pattern)
+- `package.json`, `pyproject.toml`
+- Any text file with a `VERSION: XX.YY.ZZ` label
+
+Files synced from other repos (with a `# REPO:` header) are not touched.
+
+## Code Standards
+
+- **PHP**: PSR-12, tabs for indentation
+- **Copyright**: all files must include the Moko Consulting copyright header
+- **License**: SPDX identifier `GPL-3.0-or-later` (or as specified per repo)
+- **Attribution**: use `Authored-by: Moko Consulting` in commits, not individual names
+
+## Commit Messages
+
+Use conventional commit format:
+
+```
+type(scope): short description
+
+Optional body with context.
+
+Authored-by: Moko Consulting
+```
+
+Types: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `ci`
+
+Special flags in commit messages:
+- `[skip ci]` — skip all CI workflows
+- `[skip bump]` — skip auto version bump only
+
+## Reporting Issues
+
+Use the repository's issue tracker with the appropriate template.
+
+---
+
+*Moko Consulting <hello@mokoconsulting.tech>*

package/README.md

@@ -0,0 +1,286 @@
+<!-- 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
+-->
+
+# gitea-api-mcp
+
+[![License: GPL-3.0-or-later](https://img.shields.io/badge/License-GPL--3.0--or--later-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![MCP](https://img.shields.io/badge/MCP-compatible-brightgreen.svg)](https://modelcontextprotocol.io)
+[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-green.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
+
+> MCP server for Gitea REST API v1 operations -- 61 tools for complete Gitea instance management from Claude Code and other MCP clients.
+
+## Table of Contents
+
+- [Background](#background)
+- [Install](#install)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Tools](#tools)
+- [Contributing](#contributing)
+- [License](#license)
+- [Revision History](#revision-history)
+
+## Background
+
+`gitea-api-mcp` is a Model Context Protocol (MCP) server that exposes 61 tools for interacting with the Gitea REST API v1. It supports multiple named connections, allowing you to manage several Gitea instances from a single server. Authentication uses Gitea's native `Authorization: token` header format.
+
+## Install
+
+### Prerequisites
+
+- Node.js >= 20.0.0
+- A Gitea instance with API access
+- A Gitea access token (Settings > Applications > Generate Token)
+
+### Build from Source
+
+```bash
+git clone https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp.git
+cd gitea-api-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+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 |
+|-------|------|----------|-------------|
+| `baseUrl` | string | Yes | Base URL of your Gitea instance |
+| `token` | string | Yes | Gitea API access token |
+| `insecure` | boolean | No | Skip TLS verification (self-signed certs) |
+
+Override the config path with the `GITEA_API_MCP_CONFIG` environment variable.
+
+### Multi-Connection Example
+
+```json
+{
+  "defaultConnection": "moko",
+  "connections": {
+    "moko": {
+      "baseUrl": "https://git.mokoconsulting.tech",
+      "token": "token-for-moko-gitea"
+    },
+    "github-mirror": {
+      "baseUrl": "https://gitea.example.com",
+      "token": "token-for-mirror"
+    }
+  }
+}
+```
+
+## Usage
+
+### Claude Code Registration
+
+Add to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or project-level `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "gitea-moko": {
+      "command": "node",
+      "args": ["/path/to/gitea-api-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+### Multi-Connection Usage in Claude Code
+
+When using multiple connections, pass the `connection` parameter to any tool:
+
+```
+Use gitea_repo_get with connection "github-mirror" to get owner/repo details.
+```
+
+If `connection` is omitted, the `defaultConnection` is used.
+
+## Tools
+
+### User / Auth (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_me` | Get the authenticated user info |
+| `gitea_user_orgs` | List organizations the authenticated user belongs to |
+| `gitea_user_repos` | List repositories owned by the authenticated user |
+
+### Repositories (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_repo_get` | Get repository details |
+| `gitea_repo_create` | Create a new repository |
+| `gitea_repo_delete` | Delete a repository |
+| `gitea_repo_edit` | Edit repository settings |
+| `gitea_repo_fork` | Fork a repository |
+| `gitea_repo_search` | Search repositories |
+| `gitea_org_repos` | List repositories in an organization |
+| `gitea_list_connections` | List configured Gitea connections |
+
+### File Contents (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_file_get` | Get file contents from a repository |
+| `gitea_dir_get` | Get directory contents (file listing) from a repository |
+| `gitea_file_create_or_update` | Create or update a file in a repository |
+| `gitea_file_delete` | Delete a file from a repository |
+| `gitea_tree_get` | Get the git tree for a repository (recursive file listing) |
+
+### Branches (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_branches_list` | List branches in a repository |
+| `gitea_branch_get` | Get a specific branch |
+| `gitea_branch_create` | Create a new branch |
+| `gitea_branch_delete` | Delete a branch |
+
+### Commits (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_commits_list` | List commits in a repository |
+| `gitea_commit_get` | Get a specific commit |
+
+### Issues (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_issues_list` | List issues in a repository |
+| `gitea_issue_get` | Get a single issue by number |
+| `gitea_issue_create` | Create a new issue |
+| `gitea_issue_update` | Update an issue |
+| `gitea_issue_comments_list` | List comments on an issue |
+| `gitea_issue_comment_create` | Add a comment to an issue |
+| `gitea_issue_search` | Search issues across all repositories |
+
+### Labels (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_labels_list` | List labels in a repository |
+| `gitea_label_create` | Create a label |
+
+### Milestones (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_milestones_list` | List milestones in a repository |
+| `gitea_milestone_create` | Create a milestone |
+
+### Pull Requests (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_pulls_list` | List pull requests |
+| `gitea_pull_get` | Get a single pull request |
+| `gitea_pull_create` | Create a pull request |
+| `gitea_pull_merge` | Merge a pull request |
+| `gitea_pull_files` | List files changed in a pull request |
+| `gitea_pull_review_create` | Create a pull request review |
+
+### Releases (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_releases_list` | List releases |
+| `gitea_release_get` | Get a single release by ID |
+| `gitea_release_latest` | Get the latest release |
+| `gitea_release_create` | Create a new release |
+| `gitea_release_delete` | Delete a release |
+
+### Tags (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_tags_list` | List tags |
+| `gitea_tag_create` | Create a tag |
+| `gitea_tag_delete` | Delete a tag |
+
+### Actions (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_actions_runs_list` | List workflow runs for a repository |
+| `gitea_actions_run_get` | Get a specific workflow run |
+
+### Organizations (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_org_get` | Get organization details |
+| `gitea_org_teams_list` | List teams in an organization |
+| `gitea_org_members_list` | List members of an organization |
+
+### Users (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_user_get` | Get a user profile |
+| `gitea_users_search` | Search users |
+
+### Webhooks (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_webhooks_list` | List webhooks for a repository |
+| `gitea_webhook_create` | Create a webhook |
+
+### Wiki (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_wiki_pages_list` | List wiki pages |
+| `gitea_wiki_page_get` | Get a wiki page |
+
+### Notifications (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_notifications_list` | List notifications for the authenticated user |
+| `gitea_notifications_read` | Mark all notifications as read |
+
+### Generic (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `gitea_api_request` | Make a raw API request to any Gitea v1 endpoint |
+| `gitea_list_connections` | List configured Gitea connections |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.
+
+## License
+
+[GPL-3.0-or-later](https://www.gnu.org/licenses/gpl-3.0.html) -- Copyright (C) 2026 Moko Consulting
+
+## Revision History
+
+| Version | Date | Description |
+|---------|------|-------------|
+| 0.0.1 | 2026-05-07 | Initial release with 61 tools |

package/SECURITY.md

@@ -0,0 +1,91 @@
+<!-- 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
+-->
+
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.0.x | Yes |
+
+## Reporting a Vulnerability
+
+To report a security vulnerability, please email **hello@mokoconsulting.tech** with the subject line `[SECURITY] gitea-api-mcp`. Do not open a public issue for security vulnerabilities.
+
+We will acknowledge receipt within 48 hours and provide an initial assessment within 5 business days.
+
+## Token Storage Security
+
+### Configuration File
+
+The config file `~/.gitea-api-mcp.json` stores Gitea API tokens in plaintext. Follow these practices to protect your tokens:
+
+#### File Permissions
+
+Set restrictive permissions on the config file so only your user can read it:
+
+```bash
+chmod 600 ~/.gitea-api-mcp.json
+```
+
+On Windows, ensure the file is only readable by your user account through the file properties security tab.
+
+#### What to Avoid
+
+- **Never** commit `~/.gitea-api-mcp.json` or any file containing tokens to version control
+- **Never** share config files containing real tokens
+- **Never** log or print token values in debug output
+- **Never** store tokens in environment variables visible to other processes if avoidable
+
+#### Token Scope
+
+When generating Gitea access tokens, follow the principle of least privilege:
+
+- Only grant the scopes (permissions) your workflow requires
+- Use separate tokens for separate purposes or environments
+- Rotate tokens periodically
+- Revoke tokens that are no longer needed
+
+#### Token Generation
+
+1. Navigate to your Gitea instance Settings > Applications
+2. Under "Manage Access Tokens," enter a token name
+3. Select only the required scopes
+4. Click "Generate Token"
+5. Copy the token immediately -- it will not be shown again
+
+### Network Security
+
+#### TLS Verification
+
+By default, the client verifies TLS certificates. The `insecure: true` option disables certificate verification for self-signed certificates. Use this only for:
+
+- Local development instances
+- Internal instances with self-signed certificates where the network is trusted
+
+**Never** use `insecure: true` for production instances accessible over the public internet.
+
+#### API Prefix
+
+All requests are sent to `/api/v1` endpoints with:
+
+- `Authorization: token <your-token>` header
+- `Content-Type: application/json` header
+- 30-second request timeout
+
+### MCP Transport Security
+
+This server uses stdio transport, meaning it communicates through standard input/output with the MCP client (e.g., Claude Code). The token is never exposed through network ports or HTTP endpoints by the MCP server itself.
+
+## Security Checklist
+
+- [ ] Config file permissions set to `600` (Unix) or user-only (Windows)
+- [ ] Tokens scoped to minimum required permissions
+- [ ] Config file excluded from version control (`.gitignore`)
+- [ ] `insecure` flag only used for trusted internal instances
+- [ ] Tokens rotated on a regular schedule
+- [ ] Unused tokens revoked promptly