@rashidazarang/aptly-mcp/README.md

Model Context Protocol server for Aptly package repository management - enables AI assistants to manage Debian repositories

# Aptly MCP Server

A Model Context Protocol (MCP) server for managing Debian package repositories using the Aptly package repository management tool.

## Overview

This MCP server provides AI assistants with direct access to Aptly functionality through standardized tools and resources. It enables natural language interaction with Debian package repositories, including creation, management, and publishing operations.

## Features

### MCP Tools

- **aptly_create_repo**: Create new local repositories
- **aptly_list_repos**: List all repositories with filtering options
- **aptly_add_packages**: Add packages to repositories from uploaded files
- **aptly_search_packages**: Search packages across repositories
- **aptly_create_snapshot**: Create snapshots from repositories or other snapshots
- **aptly_publish_repo**: Publish repositories/snapshots for apt consumption
- **aptly_create_mirror**: Create mirrors of remote repositories
- **aptly_upload_files**: Upload package files to the server
- **aptly_list_mirrors**: List all configured mirrors
- **aptly_update_mirror**: Update mirrors with latest packages
- **aptly_delete_repo**: Delete repositories with safety checks

### MCP Resources

- **repositories**: Dynamic listing of all repositories with metadata
- **packages**: Searchable package databases across repositories
- **mirrors**: Remote mirror status and configuration
- **publications**: Published repository information and endpoints
- **snapshots**: Available snapshots with creation dates and descriptions

## Installation

```bash
cd aptly-mcp
npm install
npm run build
```

## Configuration

### Environment Variables

```bash
export APTLY_API_URL=http://localhost:8080  # Default Aptly API endpoint
export APTLY_AUTH_TOKEN=your_token_here     # Optional authentication token
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aptly": {
      "command": "node",
      "args": ["/path/to/aptly-mcp/build/index.js"],
      "env": {
        "APTLY_API_URL": "http://localhost:8080"
      }
    }
  }
}
```

### Remote Aptly Server

For remote Aptly servers with authentication:

```json
{
  "mcpServers": {
    "aptly": {
      "command": "node",
      "args": ["/path/to/aptly-mcp/build/index.js"],
      "env": {
        "APTLY_API_URL": "https://aptly.example.com",
        "APTLY_AUTH_TOKEN": "your-auth-token"
      }
    }
  }
}
```

## Usage Examples

Once configured with Claude Desktop, you can use natural language commands:

### Repository Management
- "Create a new repository called 'production-packages' for production releases"
- "List all repositories and show their package counts"
- "Delete the 'test-repo' repository"

### Package Operations
- "Add all .deb files from the 'uploads' directory to the 'main' repository"
- "Search for packages containing 'nginx' across all repositories"
- "Remove the 'old-package' from the 'main' repository"

### Snapshot Management
- "Create a snapshot of the 'main' repository called 'v1.0-release'"
- "List all snapshots and their creation dates"
- "Create a merged snapshot from 'main' and 'contrib' repositories"

### Publishing
- "Publish the 'main' repository to the 'stable' distribution"
- "Update the published 'testing' repository with the latest snapshot"
- "List all published repositories and their endpoints"

### Mirror Management
- "Create a mirror of the Ubuntu main repository"
- "Update all mirrors to get the latest packages"
- "Show the status of the 'ubuntu-main' mirror"

## Development

### Building
```bash
npm run build
```

### Testing
```bash
npm run inspector  # Launch MCP inspector for testing
```

### Watching for Changes
```bash
npm run watch
```

## API Documentation

The server connects to Aptly's REST API. Ensure your Aptly instance is running with API enabled:

```bash
aptly api serve -listen=":8080"
```

## Security Considerations

- Use Unix domain sockets instead of network ports in production
- Implement proper authentication for remote Aptly servers
- Consider using a reverse proxy with HTTPS for production deployments
- Validate all inputs to prevent injection attacks

## License

MIT License