# Gogs MCP Server

A Model Context Protocol (MCP) server that provides access to Gogs git hosting APIs. This server enables AI assistants like Claude to interact with Gogs repositories, users, and other resources.

## Features

This MCP server provides tools to:

- **User Management**
  - Get authenticated user information
  - Get specific user details
  - Search for users

- **Repository Management**
  - List user repositories
  - Search repositories
  - Get repository information
  - Create new repositories
  - Delete repositories

- **Content Access**
  - Get file and directory contents
  - Get raw file content
  - List repository branches
  - Get commit history

- **Issue Management**
  - List issues in a repository
  - Get specific issue details
  - Create new issues
  - Update existing issues (including state changes)
  - List comments on issues
  - Add comments to issues
  - Edit existing comments

## Installation

### Prerequisites

- Node.js 18 or higher
- npm or yarn
- A Gogs server instance
- Gogs access token (optional, but recommended for authenticated access)

**OR**

- Docker and Docker Compose (for containerized deployment)

### Setup

1. Clone this repository:
   ```bash
   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

### Docker Setup

1. Clone this repository:
   ```bash
   git clone ssh://git@207.154.220.231:10022/claude/gogs-mcp.git
   cd gogs-mcp
   ```

2. Create a `.env` file from the example:
   ```bash
   cp .env.example .env
   ```

3. Edit `.env` and configure your Gogs server URL and access token:
   ```bash
   GOGS_SERVER_URL=https://your-gogs-server.com
   GOGS_ACCESS_TOKEN=your-access-token-here
   ```

4. Build and run with Docker Compose:
   ```bash
   docker-compose up -d
   ```

   Or build the Docker image manually:
   ```bash
   docker build -t gogs-mcp-server .
   docker run --env-file .env gogs-mcp-server
   ```

## Configuration

### Generate Gogs Access Token

1. Log in to your Gogs instance
2. Navigate to Settings → Applications
3. Create a new access token with appropriate permissions
4. Copy the token for use in configuration

### Environment Variables

Create a `.env` file or set environment variables:

```bash
GOGS_SERVER_URL=https://your-gogs-server.com
GOGS_ACCESS_TOKEN=your-access-token-here

# Transport mode (optional, default: stdio)
TRANSPORT_MODE=stdio  # or 'http' for HTTP/SSE transport

# HTTP server configuration (only used when TRANSPORT_MODE=http)
HTTP_PORT=3000
HTTP_HOST=0.0.0.0
```

The access token is optional but recommended. Without it:
- User email fields may be empty (anti-spam measure)
- Some operations requiring authentication will fail
- Only public repositories will be accessible

### Transport Modes

The server supports two transport modes:

**stdio (default)**: For use with MCP clients like Claude Desktop
- Communicates via standard input/output
- Runs as a subprocess of the MCP client
- Suitable for desktop applications

**http**: For HTTP-based access with Server-Sent Events (SSE)
- Exposes HTTP endpoints for the MCP protocol
- Runs as a standalone web server
- Suitable for web applications and remote access
- Supports CORS for cross-origin requests

## Usage

### With Claude Desktop (stdio mode)

Add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gogs": {
      "command": "node",
      "args": ["/absolute/path/to/gogs-mcp-server/dist/index.js"],
      "env": {
        "GOGS_SERVER_URL": "https://your-gogs-server.com",
        "GOGS_ACCESS_TOKEN": "your-access-token-here",
        "TRANSPORT_MODE": "stdio"
      }
    }
  }
}
```

### HTTP Mode

To run the server in HTTP mode for web applications:

1. Set the transport mode to HTTP in your `.env` file:
   ```bash
   TRANSPORT_MODE=http
   HTTP_PORT=3000
   HTTP_HOST=0.0.0.0
   ```

2. Start the server:
   ```bash
   npm start
   ```

3. The server will be available at:
   - SSE endpoint: `http://localhost:3000/sse`
   - Message endpoint: `http://localhost:3000/message`
   - Health check: `http://localhost:3000/health`

4. Connect your MCP client to the SSE endpoint to establish a persistent connection.

### HTTP Mode with Docker

```bash
# Set environment variables in .env
TRANSPORT_MODE=http
HTTP_PORT=3000

# Run with docker-compose
docker-compose up -d

# Or run with Docker directly
docker run -p 3000:3000 \
  -e GOGS_SERVER_URL=https://your-gogs-server.com \
  -e GOGS_ACCESS_TOKEN=your-access-token-here \
  -e TRANSPORT_MODE=http \
  -e HTTP_PORT=3000 \
  gogs-mcp-server:latest
```

### With Other MCP Clients (stdio mode)

The server uses stdio transport and can be integrated with any MCP-compatible client:

```bash
# Set environment variables
export GOGS_SERVER_URL=https://your-gogs-server.com
export GOGS_ACCESS_TOKEN=your-access-token-here
export TRANSPORT_MODE=stdio

# Run the server
npm start
```

### With Docker

You can use the Docker image with MCP clients by mounting it as a command:

```json
{
  "mcpServers": {
    "gogs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GOGS_SERVER_URL=https://your-gogs-server.com",
        "-e", "GOGS_ACCESS_TOKEN=your-access-token-here",
        "gogs-mcp-server:latest"
      ]
    }
  }
}
```

Or using docker-compose:

```json
{
  "mcpServers": {
    "gogs": {
      "command": "docker-compose",
      "args": [
        "-f", "/absolute/path/to/gogs-mcp-server/docker-compose.yml",
        "run",
        "--rm",
        "gogs-mcp-server"
      ]
    }
  }
}
```

## Available Tools

### User Tools

#### `get_current_user`
Get information about the authenticated user.

#### `get_user`
Get information about a specific user.
- `username` (string, required): Username to look up

#### `search_users`
Search for users by username.
- `query` (string, required): Search query
- `limit` (number, optional): Maximum results (default: 10)

### Repository Tools

#### `list_user_repositories`
List repositories for a user.
- `username` (string, optional): Username (omit for authenticated user)

#### `search_repositories`
Search for repositories.
- `query` (string, required): Search query
- `uid` (number, optional): User ID to filter by
- `limit` (number, optional): Maximum results (default: 10)
- `page` (number, optional): Page number (default: 1)

#### `get_repository`
Get information about a specific repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

#### `create_repository`
Create a new repository.
- `name` (string, required): Repository name
- `description` (string, optional): Repository description
- `private` (boolean, optional): Create as private (default: false)
- `auto_init` (boolean, optional): Initialize with README (default: false)
- `gitignores` (string, optional): Gitignore templates (e.g., "Go,VisualStudioCode")
- `license` (string, optional): License template (e.g., "MIT License")
- `readme` (string, optional): README template (default: "Default")

#### `delete_repository`
Delete a repository (requires admin access).
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

### Content Tools

#### `get_contents`
Get file or directory contents from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `path` (string, required): File or directory path
- `ref` (string, optional): Branch, tag, or commit SHA (default: default branch)

#### `get_raw_content`
Get raw file content from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `ref` (string, required): Branch, tag, or commit SHA
- `path` (string, required): File path

#### `list_branches`
List all branches in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name

#### `get_commits`
Get commit history from a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `sha` (string, optional): Branch name or commit SHA
- `page` (number, optional): Page number (default: 1)

### Issue Management Tools

#### `list_issues`
List issues in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `state` (string, optional): Filter by state - 'open', 'closed', or 'all' (default: 'open')
- `labels` (string, optional): Comma-separated list of label names
- `page` (number, optional): Page number (default: 1)
- `per_page` (number, optional): Results per page (default: 30)

#### `get_issue`
Get a specific issue by number.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number

#### `create_issue`
Create a new issue in a repository.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `title` (string, required): Issue title
- `body` (string, optional): Issue description
- `assignee` (string, optional): Username to assign the issue to
- `milestone` (number, optional): Milestone ID
- `labels` (array of numbers, optional): Array of label IDs

#### `update_issue`
Update an existing issue (including closing or reopening).
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `title` (string, optional): Issue title
- `body` (string, optional): Issue description
- `assignee` (string, optional): Username to assign the issue to
- `milestone` (number, optional): Milestone ID
- `state` (string, optional): Issue state - 'open' or 'closed'
- `labels` (array of numbers, optional): Array of label IDs

#### `list_issue_comments`
List all comments on an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number

#### `create_issue_comment`
Add a comment to an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `number` (number, required): Issue number
- `body` (string, required): Comment text

#### `update_issue_comment`
Edit an existing comment on an issue.
- `owner` (string, required): Repository owner username
- `repo` (string, required): Repository name
- `commentId` (number, required): Comment ID
- `body` (string, required): Updated comment text

## Development

### Run in Development Mode

```bash
npm run dev
```

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

## API Documentation

The Gogs API documentation is included in the `docs-api` submodule. For more information about the Gogs REST API, see:
- [Gogs API Documentation](https://github.com/gogs/docs-api)
- Local docs: `docs-api/README.md`

## Security Considerations

- **Access Tokens**: Keep your access tokens secure. Never commit them to version control.
- **Permissions**: The access token's permissions determine what operations are available.
- **Private Repositories**: Access to private repositories requires authentication.
- **Rate Limiting**: Be aware of any rate limiting imposed by your Gogs server.

## Troubleshooting

### "GOGS_SERVER_URL environment variable is required"
Make sure you've set the `GOGS_SERVER_URL` environment variable or included it in your MCP client configuration.

### "404 Not Found" errors
This can indicate:
- Invalid server URL
- Repository or user doesn't exist
- Authentication required but not provided
- Insufficient permissions

### "401 Unauthorized" errors
- Check that your access token is correct and hasn't expired
- Verify the token has appropriate permissions for the operation

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol)
- Designed for [Gogs](https://gogs.io) git hosting
- API documentation from [gogs/docs-api](https://github.com/gogs/docs-api)