MCP Harbor

MCP Harbor is a Node.js application that provides a Model Context Protocol (MCP) server for interacting with Harbor container registry. It also includes a REST API for Harbor operations.

MCP Harbor

Features

MCP Server: Exposes tools for interacting with Harbor through the Model Context Protocol
REST API: Provides RESTful endpoints for Harbor operations
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

Clone the repository:

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

Navigate to the project directory:
```
cd mcp-harbor
```
Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Start the application:
```
npm start
```

Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# Required
HARBOR_URL=https://your-harbor-instance.com
HARBOR_USERNAME=your_username
HARBOR_PASSWORD=your_password

# Optional
PORT=3000                  # Server port (default: 3000)
LOG_LEVEL=info            # Logging level (default: info)
ENABLE_HTTPS=false       # Enable HTTPS (default: false)
SSL_CERT_PATH=/path/to/cert.pem  # Required if ENABLE_HTTPS=true
SSL_KEY_PATH=/path/to/key.pem    # Required if ENABLE_HTTPS=true

Configuration File

Additional configuration options can be set in src/config/harbor.config.ts:

{
  timeout: 30000,         // API request timeout in milliseconds
  retryAttempts: 3,      // Number of retry attempts for failed requests
  cacheEnabled: true,     // Enable response caching
  cacheTTL: 300          // Cache TTL in seconds
}

API Endpoints

Projects

GET /projects - List all projects
GET /projects/:id - Get project details
POST /projects - Create a new project
DELETE /projects/:id - Delete a project

Repositories

GET /projects/:projectId/repositories - List repositories in a project
DELETE /projects/:projectId/repositories/:repositoryName - Delete a repository

Helm Charts

GET /projects/:projectId/charts - List Helm charts in a project
GET /projects/:projectId/charts/:chartName/versions - List versions of a Helm chart
DELETE /projects/:projectId/charts/:chartName/versions/:version - Delete a Helm chart version

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 | id: number | | create_project | Create a new project | name: string, public?: boolean | | delete_project | Delete a project | id: number | | list_repositories | List repositories in a project | projectId: number | | delete_repository | Delete a repository | projectId: number, repoName: string | | list_tags | List tags in a repository | projectId: number, repoName: string | | delete_tag | Delete a tag | projectId: number, repoName: string, tag: string | | list_charts | List Helm charts | projectId: number | | list_chart_versions | List chart versions | projectId: number, chartName: string | | delete_chart | Delete chart version | projectId: number, chartName: string, version: string |

Development

Running in Development Mode

npm run dev

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- test/harbor.test.ts

Debug Tools

The project includes debug tools in the tools directory:

# Test Harbor connection
npm run test:connection

# Start debug server
npm run debug:server

Project Structure

mcp-harbor
├── src
│   ├── app.ts                 # Main application entry point (MCP server)
│   ├── config
│   │   └── harbor.config.ts   # Harbor configuration
│   ├── controllers
│   │   └── harbor.controller.ts # REST API controllers
│   ├── services
│   │   └── harbor.service.ts  # Harbor service implementation
│   ├── models 
│   │   └── harbor.model.ts    # Data models
│   ├── routes
│   │   └── harbor.routes.ts   # API route definitions
│   └── types
│       └── index.ts           # TypeScript type definitions
├── test
│   └── harbor.test.ts         # Tests for Harbor service
├── tools
│   ├── debug-server.ts        # Debug server implementation
│   └── test-connection.ts     # Connection testing utility
├── .env.example              # Example environment variables
├── .gitignore               # Git ignore file
├── package.json            # Project dependencies
├── tsconfig.json          # TypeScript configuration
└── README.md             # Project documentation

Troubleshooting

Common Issues

Connection Failed
```
Error: Unable to connect to Harbor instance
```
- Verify HARBOR_URL is correct and accessible
- Check network connectivity
- Ensure Harbor instance is running
Authentication Failed
```
Error: Invalid credentials
```
- Verify HARBOR_USERNAME and HARBOR_PASSWORD are correct
- Check if user has required permissions
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 logging by setting:

LOG_LEVEL=debug

Support

For additional help:

Check the DEBUG.md file
Run the connection test: npm run test:connection
Review the application logs in logs/ directory

License

This project is licensed under the MIT License - see the LICENSE file for details.

mcp-harbor