<!-- 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
-->

# 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](#getting-started)
- [Development Setup](#development-setup)
- [Gitea API Explorer](#gitea-api-explorer)
- [Code Style](#code-style)
- [Commit Conventions](#commit-conventions)
- [Branch Protection Rules](#branch-protection-rules)
- [Pull Request Process](#pull-request-process)
- [Adding a New Tool](#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

```bash
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:

```bash
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

```typescript
/* 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](https://www.conventionalcommits.org/):

```
<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

```typescript
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),
    );
  },
);
```