README - MCP Harbor by nomagicln

MCP Harbor

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

MCP Harbor

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

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

Usage

Command Line Arguments

The application accepts the following command line arguments:

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:

# 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

npm run dev

Running Tests

# 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

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 mode by using the --debug flag or setting:

DEBUG=true

Support

For additional help:

Review the application logs

License

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