gogs-mcp/CLAUDE.md

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, list_user_emails, add_user_emails, delete_user_emails
• Repository Management: list_user_repositories, search_repositories, get_repository, create_repository, delete_repository
• Content Access: get_contents, get_raw_content, list_branches, get_commits, get_tree
• Issue Tracking: list_issues, get_issue, create_issue, update_issue, list_issue_comments, create_issue_comment, update_issue_comment
• Label Management: list_labels, get_label, create_label, update_label, delete_label, list_issue_labels, add_issue_labels, remove_issue_label, replace_issue_labels, remove_all_issue_labels
• Milestone Management: list_milestones, get_milestone, create_milestone, update_milestone, delete_milestone
• Organization Management: list_user_organizations, create_organization, list_public_organizations, get_organization, update_organization, add_organization_member
• Team Management: list_organization_teams, create_team, get_team, add_team_member, remove_team_member
• Release Management: list_releases
• Collaborator Management: list_collaborators, check_collaborator, add_collaborator, remove_collaborator
• Public Key Management: list_user_keys, list_my_keys, get_public_key, create_public_key, delete_public_key
• Deploy Key Management: list_deploy_keys, get_deploy_key, create_deploy_key, delete_deploy_key
• Webhook Management: list_hooks, create_hook, update_hook, delete_hook
• User Followers: list_followers, list_following, check_following, follow_user, unfollow_user
• Markdown Rendering: render_markdown, render_markdown_raw
• Admin APIs (⚠️ requires admin privileges): admin_create_user, admin_edit_user, admin_delete_user, admin_create_user_public_key, admin_delete_user_public_key, admin_create_org, admin_list_org_teams, admin_create_user_org, admin_create_user_repo

Development Commands

Build and Run

# 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

   # 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

Documentation Standards

When working on this project, maintaining up-to-date documentation is critical:

README.md Updates

• Always update README.md when adding new features, tools, or API endpoints
• Add new tools to the "Available Tools" section with full parameter documentation
• Update feature lists when implementing new capabilities
• Keep the documentation in sync with actual implementation

CLAUDE.md Updates

• Update MCP Tool Categories when adding new tool categories
• Document any new architecture patterns or components
• Add development guidelines for new features or patterns
• Update build commands if the build process changes

Documentation Guidelines

1. When adding new MCP tools: Document in both CLAUDE.md (for developers) and README.md (for users)
2. When implementing API endpoints: Add to the undocumented endpoints table if not in official docs
3. When changing architecture: Update the Core Components section in CLAUDE.md
4. When adding dependencies: Document any new configuration or setup steps
5. Before committing: Always ensure documentation reflects the current state of the codebase

Undocumented API Endpoints

Maintain a table in README.md of any Gogs API endpoints that work but are not officially documented. This helps users understand full capabilities and helps track potential features for future Gogs API documentation.