# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Model Context Protocol (MCP) server that provides AI assistants (like Claude) with access to Gogs git hosting APIs. The server uses stdio transport to communicate and exposes tools for managing users, repositories, commits, branches, issues, and comments.

## Architecture

### Core Components

- **src/index.ts**: Main MCP server implementation
  - Defines all MCP tool schemas using Zod
  - Registers request handlers for tool calls, resources, and listings
  - Uses stdio transport for communication with MCP clients
  - Entry point with shebang for direct execution

- **src/gogs-client.ts**: Gogs API client
  - Wraps all Gogs REST API v1 calls using axios
  - Handles authentication via access token in headers
  - Provides typed methods for all supported Gogs operations

- **src/types.ts**: TypeScript type definitions
  - All Gogs API response types (User, Repository, Issue, Commit, Branch, etc.)
  - Configuration interfaces

### MCP Tool Categories

The server exposes tools in these categories:
- **User Management**: get_current_user, get_user, search_users
- **Repository Management**: list_user_repositories, search_repositories, get_repository, create_repository, delete_repository
- **Content Access**: get_contents, get_raw_content, list_branches, get_commits
- **Issue Tracking**: list_issues, get_issue, create_issue, update_issue, list_issue_comments, create_issue_comment, update_issue_comment

## Development Commands

### Build and Run
```bash
# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Run in development mode (with tsx)
npm run dev

# Run built version
npm start

# Watch mode for development
npm run watch
```

### TypeScript Configuration
- Target: ES2022
- Module: Node16 (ESM with .js extensions in imports)
- Outputs to `dist/` with declarations and source maps

## Environment Configuration

Required environment variables:
- `GOGS_SERVER_URL`: URL of your Gogs server (required)
- `GOGS_ACCESS_TOKEN`: Gogs access token for authenticated operations (optional but recommended)

Create `.env` file from `.env.example` template for local development.

## Docker Deployment

Multi-stage Dockerfile optimizes image size:
1. Builder stage: Installs all deps and builds TypeScript
2. Production stage: Only production deps and built files

```bash
# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t gogs-mcp-server .
docker run --env-file .env gogs-mcp-server
```

## Issue Handling Workflow

When working on issues in this repository:
- Always update the issue you're working on with status comments
- Add labels to issues if none exist
- Write comments describing the current status of the work
- When creating commit messages, mention the issue number if it exists (e.g., "Fix authentication bug #12")

## Code Style

- Use ES modules with `.js` extensions in imports (required by Node16 module resolution)
- All API client methods should be async and return typed responses
- Tool handlers in index.ts should parse inputs with Zod schemas before processing
- Error handling: catch errors, return formatted error responses with `isError: true`


## Issue handling
 - always update the issue which you works on
 - always add label to the issue if no label added
 - always write comment with the current status of the work 
 - when you create commit message, mention the issue if exists
 - never close the issue