# MCP Harbor

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-4.9.5-blue.svg)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-18.x-green.svg)](https://nodejs.org/)
[![codecov](https://codecov.io/gh/nomagicln/mcp-harbor/graph/badge.svg?token=TZ95P20K6P)](https://codecov.io/gh/nomagicln/mcp-harbor)

MCP Harbor is a Node.js application that provides a Model Context Protocol (MCP) server for interacting with Harbor container registry.

## Table of Contents

- [MCP Harbor](#mcp-harbor)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Prerequisites](#prerequisites)
  - [Installation](#installation)
  - [Usage](#usage)
    - [Command Line Arguments](#command-line-arguments)
    - [Environment Variables](#environment-variables)
    - [MCP Client Configuration](#mcp-client-configuration)
  - [MCP Tools](#mcp-tools)
  - [Development](#development)
    - [Running in Development Mode](#running-in-development-mode)
    - [Running Tests](#running-tests)
  - [Project Structure](#project-structure)
  - [Troubleshooting](#troubleshooting)
    - [Common Issues](#common-issues)
    - [Debug Mode](#debug-mode)
    - [Support](#support)
  - [License](#license)

## Features

- **MCP Server**: Exposes tools for interacting with Harbor through the Model Context Protocol
- **Harbor Operations**: Supports operations for projects, repositories, tags, and Helm charts
- **TypeScript**: Written in TypeScript for better type safety and developer experience
- **Automated Tests**: Comprehensive test suite for reliable functionality

## Prerequisites

Before installing MCP Harbor, ensure you have:

- Node.js 18.x or higher
- npm 8.x or higher
- Access to a Harbor registry instance
- Git (for cloning the repository)

## Installation

1. Clone the repository:

   ```bash
   git clone https://github.com/nomagicln/mcp-harbor.git
   ```

2. Navigate to the project directory:

   ```bash
   cd mcp-harbor
   ```

3. Install dependencies:

   ```bash
   npm install
   ```

4. Build the project:

   ```bash
   npm run build
   ```

## Usage

### Command Line Arguments

The application accepts the following command line arguments:

```bash
Options:
  --url       Harbor API URL                              [string] [required]
  --username  Harbor username (or robot account name)     [string] [required]
  --password  Harbor password (mutually exclusive with --token)       [string]
  --token     Harbor token for robot/service accounts                [string]
  --insecure  Disable TLS/SSL certificate validation [boolean] [default: false]
  --debug     Enable debug mode                   [boolean] [default: false]
  --help      Show help                                             [boolean]
```

> **Note:** You must provide either `--password` or `--token`, but not both.

### Environment Variables

Instead of command line arguments, you can also use environment variables. Create a `.env` file in the root directory:

```env
# Harbor API Configuration
HARBOR_URL=https://harbor.example.com
HARBOR_USERNAME=admin

# Authentication: use either PASSWORD or TOKEN (mutually exclusive)
# Option 1: Password-based authentication
HARBOR_PASSWORD=Harbor12345

# Option 2: Token-based authentication (for robot/service accounts)
# HARBOR_USERNAME=robot$myrobot
# HARBOR_TOKEN=your-robot-token-here

# Debug Mode (true/false)
DEBUG=false

# Disable TLS/SSL certificate validation (true/false)
# HARBOR_INSECURE=false
```

#### Token Authentication (Robot/Service Accounts)

Harbor supports robot accounts for automated access. To use token-based authentication:

1. Create a robot account in your Harbor instance (Administration > Robot Accounts)
2. Use the robot account name as `--username` (e.g., `robot$myrobot`)
3. Use the generated token as `--token`

```bash
mcp-harbor --url https://harbor.example.com --username "robot\$myrobot" --token "your-robot-token"
```

### MCP Client Configuration

#### Claude Desktop

Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):

**Using password authentication:**

```json
{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}
```

**Using token authentication (robot/service account):**

```json
{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "robot$myrobot",
        "--token", "your-robot-token"
      ]
    }
  }
}
```

**With self-signed certificates:**

```json
{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "admin",
        "--password", "your-password",
        "--insecure"
      ]
    }
  }
}
```

#### Cursor / Windsurf

Add the following to your MCP configuration file (`.cursor/mcp.json` or `.windsurf/mcp.json`):

```json
{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": [
        "mcp-harbor",
        "--url", "https://harbor.example.com",
        "--username", "admin",
        "--password", "your-password"
      ]
    }
  }
}
```

#### Using environment variables

You can also reference environment variables to avoid hardcoding credentials:

```json
{
  "mcpServers": {
    "harbor": {
      "command": "npx",
      "args": ["mcp-harbor"],
      "env": {
        "HARBOR_URL": "https://harbor.example.com",
        "HARBOR_USERNAME": "admin",
        "HARBOR_PASSWORD": "your-password"
      }
    }
  }
}
```

#### SSE Transport (remote/shared server)

If you prefer running the MCP server as a standalone process with SSE transport:

```bash
npx mcp-harbor --url https://harbor.example.com --username admin --password your-password --sse --port 3000
```

Then configure your MCP client to connect via SSE at `http://localhost:3000/sse`.

## MCP Tools

The MCP server exposes the following tools:

| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `list_projects` | List all projects in Harbor | None |
| `get_project` | Get project details by ID | `projectId: string` |
| `create_project` | Create a new project | `project_name: string, metadata?: object` |
| `delete_project` | Delete a project | `projectId: string` |
| `list_repositories` | List repositories in a project | `projectId: string` |
| `delete_repository` | Delete a repository | `projectId: string, repositoryName: string` |
| `list_tags` | List tags in a repository | `projectId: string, repositoryName: string` |
| `delete_tag` | Delete a tag | `projectId: string, repositoryName: string, tag: string` |
| `list_charts` | List Helm charts | `projectId: string` |
| `list_chart_versions` | List chart versions | `projectId: string, chartName: string` |
| `delete_chart` | Delete chart version | `projectId: string, chartName: string, version: string` |

## Development

### Running in Development Mode

```bash
npm run dev
```

### Running Tests

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test:coverage
```

## Project Structure

```
mcp-harbor
├── src
│   ├── app.ts                 # Main application entry point (MCP server)
│   ├── definitions
│   │   └── tool.definitions.ts # Tool definitions for MCP
│   ├── services
│   │   └── harbor.service.ts  # Harbor service implementation
│   └── types
│       └── index.ts           # TypeScript type definitions
├── test
│   └── harbor.test.ts         # Tests for Harbor service
├── .env.example              # Example environment variables
├── .gitignore               # Git ignore file
├── .eslintrc.json           # ESLint configuration
├── package.json            # Project dependencies
├── jest.config.js           # Jest configuration
├── tsconfig.test.json      # TypeScript configuration for tests
├── tsconfig.json          # TypeScript configuration
├── LICENSE                # Project license
└── README.md             # Project documentation
```

## Troubleshooting

### Common Issues

1. **Connection Failed**

    ```
    Error: Unable to connect to Harbor instance
    ```

    - Verify HARBOR_URL is correct and accessible
    - Check network connectivity
    - Ensure Harbor instance is running

2. **Authentication Failed**

    ```
    Error: Invalid credentials
    ```

    - Verify HARBOR_USERNAME and HARBOR_PASSWORD are correct
    - Check if user has required permissions

3. **Build Errors**

    ```
    Error: TypeScript compilation failed
    ```

    - Run `npm install` to ensure all dependencies are installed
    - Check TypeScript version compatibility
    - Clear the `dist` directory and rebuild

### Debug Mode

Enable debug mode by using the `--debug` flag or setting:

```env
DEBUG=true
```

### Support

For additional help:

1. Review the application logs

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.