Contributing to gitea-api-mcp

Thank you for your interest in contributing to gitea-api-mcp. This document provides guidelines and information for contributors.

Table of Contents

• Getting Started
• Development Setup
• Gitea API Explorer
• Code Style
• Commit Conventions
• Branch Protection Rules
• Pull Request Process
• Adding a New Tool

Getting Started

1. Fork the repository on Gitea: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp
2. Clone your fork locally
3. Create a feature branch from main
4. Make your changes
5. Submit a pull request

Development Setup

git clone https://git.mokoconsulting.tech/YourUsername/gitea-api-mcp.git
cd gitea-api-mcp
npm install
npm run build

For live recompilation during development:

npm run dev

Ensure you have a valid ~/.gitea-api-mcp.json config file pointing to a test Gitea instance before testing.

Gitea API Explorer

When adding or modifying tools, refer to your Gitea instance's built-in API explorer:

https://your-gitea-instance/api/swagger

For the Moko Consulting instance:

https://git.mokoconsulting.tech/api/swagger

The Swagger UI provides:

• Full endpoint documentation with request/response schemas
• Interactive API testing ("Try it out" button)
• Authentication configuration for testing
• Parameter type and validation details

Code Style

• Use TypeScript strict mode
• Follow the existing patterns in src/index.ts for tool registration
• Use the OwnerRepo, PaginationParams, and ConnectionParam shared parameter objects
• Format responses through formatResponse()
• Include mokostandards file headers on all new source files

File Header Template

/* Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
 *
 * This file is part of a Moko Consulting project.
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * FILE INFORMATION
 * DEFGROUP: gitea-api-mcp.<GroupName>
 * INGROUP: gitea-api-mcp
 * REPO: https://git.mokoconsulting.tech/MokoConsulting/gitea-api-mcp
 * PATH: /src/<filename>.ts
 * VERSION: 01.00.00
 * BRIEF: <One-line description>
 */

Commit Conventions

This project uses Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types

Type	Description
feat	New feature (new tool, new parameter)
fix	Bug fix
docs	Documentation only
refactor	Code change that neither fixes a bug nor adds a feature
chore	Build process, dependency updates
test	Adding or updating tests

Scope

Use the tool category as scope when applicable:

feat(issues): add gitea_issue_lock tool
fix(client): handle 204 No Content responses
docs(readme): update tool count

Branch Protection Rules

The main branch has the following protections:

• Direct pushes to main are not allowed
• All changes must come through pull requests
• At least one approval is required before merging
• Status checks must pass before merging
• Force pushes are disabled

Branch Naming

feat/short-description
fix/issue-number-description
docs/what-changed
refactor/what-changed

Pull Request Process

1. Ensure your branch is up to date with main
2. Update documentation if you added or changed tools
3. Update CHANGELOG.md under an [Unreleased] section
4. Fill out the PR template with a clear description
5. Request review from a maintainer
6. Address any review feedback
7. Squash-merge will be used for final integration

Adding a New Tool

1. Identify the Gitea API endpoint in the Swagger explorer
2. Add the tool registration in src/index.ts under the appropriate category section
3. Follow the existing parameter patterns:
   • Use OwnerRepo for tools that operate on a specific repository
   • Use PaginationParams for list endpoints
   • Always include ConnectionParam for multi-connection support
4. Use z.string().describe('...') for all parameters with clear descriptions
5. Route through formatResponse() for consistent output
6. Update the tool tables in README.md and docs/API.md
7. Add the tool to CHANGELOG.md

Example

server.tool(
  'gitea_example_action',
  'Description of what this tool does',
  {
    ...OwnerRepo,
    some_param: z.string().describe('What this parameter controls'),
    ...PaginationParams,
    ...ConnectionParam,
  },
  async ({ owner, repo, some_param, page, limit, connection }) => {
    const params: Record<string, string> = { ...pageQuery({ page, limit }) };
    if (some_param) params['some_param'] = some_param;
    return formatResponse(
      await clientFor(connection).get(`/repos/${owner}/${repo}/example`, params),
    );
  },
);