# 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

## Installation

### Prerequisites

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

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

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

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

## Usage

### With Claude Desktop

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

### With Other MCP Clients

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

# Run the server
npm start
```

## 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)

## 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)