Content
# MCP Harbor
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
[](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 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 [string] [required]
--password Harbor password [string] [required]
--debug Enable debug mode [boolean] [default: false]
--help Show help [boolean]
```
### 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
HARBOR_PASSWORD=Harbor12345
# Debug Mode (true/false)
DEBUG=false
```
## 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.
