# JFrog Artifactory MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with JFrog Artifactory, enabling AI assistants to manage artifacts, repositories, and perform cleanup operations through natural language interactions.

## 🌐 Deployment Options

This MCP server can be deployed in two modes:

1. **Local Mode (stdio)** - Traditional installation where each developer runs the server locally
2. **Remote Mode (HTTP)** - **NEW!** Deploy once on a central server, and all developers connect remotely

**👉 Want to host this centrally?**
- **Quick Start (5 min):** [QUICK_SETUP.md](QUICK_SETUP.md)
- **Complete Guide:** [REMOTE_DEPLOYMENT.md](REMOTE_DEPLOYMENT.md)

Benefits of remote deployment:
- ✅ No local installation required for developers
- ✅ Single point of updates and maintenance
- ✅ Centralized monitoring and logging
- ✅ Consistent version across team

## 🚀 Features

### Artifact Management
- **📄 List Artifacts** - Browse repository contents and folder structures
- **📥 Download Artifacts** - Retrieve artifacts from repositories to local filesystem
- **📤 Upload Artifacts** - Deploy artifacts to repositories
- **🔍 Get Artifact Details** - Retrieve metadata, checksums, and properties
- **🗑️ Delete Artifacts** - Remove individual artifacts with safety confirmations

### Repository Operations
- **📋 List Repositories** - Browse available repositories with optional filtering
- **🔧 Repository Management** - Access repository configurations and details

### Cleanup & Maintenance
- **🧹 Smart Cleanup** - Remove artifacts older than specified days/weeks
- **🔍 Search Old Artifacts** - Find artifacts by age with detailed size information
- **📊 Storage Analytics** - Calculate storage usage and cleanup impact
- **🛡️ Dry Run Mode** - Preview cleanup operations before execution

### Safety Features
- **⚠️ Confirmation Required** - Explicit confirmation needed for deletions
- **🔒 Input Validation** - Prevents accidental root deletions and invalid paths
- **✅ Existence Checks** - Verifies artifacts exist before operations
- **📝 Detailed Reporting** - Comprehensive operation logs and error handling

## 📋 Requirements

- Python 3.8 or higher
- JFrog Artifactory instance (Cloud or On-Premise)
- Valid JFrog authentication credentials

## 🛠️ Installation

### 1. Clone the Repository
```bash
git clone https://github.com/your-org/jfrog-mcp-server.git
cd jfrog-mcp-server
```

### 2. Install Dependencies
```bash
pip install -r requirements.txt
```

### 3. Install the Package
```bash
pip install -e .
```

## ⚙️ Configuration

### Environment Variables
Create a `.env` file in the project root:

```bash
# JFrog Artifactory Configuration
JFROG_BASE_URL=https://your-instance.jfrog.io/artifactory
JFROG_ACCESS_TOKEN=your-access-token

# Alternative: Username/Password Authentication
# JFROG_USERNAME=your-username
# JFROG_PASSWORD=your-password

# Optional: Logging Configuration
LOG_LEVEL=INFO
```

### Authentication Options

#### Option 1: Access Token (Recommended)
```bash
JFROG_BASE_URL=https://your-instance.jfrog.io/artifactory
JFROG_ACCESS_TOKEN=your-access-token
```

#### Option 2: Username/Password
```bash
JFROG_BASE_URL=https://your-instance.jfrog.io/artifactory
JFROG_USERNAME=your-username
JFROG_PASSWORD=your-password
```

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop `config.json`):

```json
{
  "mcpServers": {
    "jfrog-artifactory": {
      "command": "python",
      "args": ["-m", "jfrog_mcp"],
      "env": {
        "JFROG_BASE_URL": "https://your-instance.jfrog.io/artifactory",
        "JFROG_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}
```

## 🌐 Running as Remote HTTP Server

To deploy the MCP server as a centralized HTTP service:

### Quick Start with Docker

```bash
# Build and run
docker-compose up -d

# Check status
curl http://localhost:8000/health
```

### Run with Python

```bash
# Start HTTP server on port 8000
python -m jfrog_mcp --http

# Or specify custom host/port
python -m jfrog_mcp --http --host 0.0.0.0 --port 8000
```

**📚 For complete remote deployment guide, security setup, and client configuration, see [REMOTE_DEPLOYMENT.md](REMOTE_DEPLOYMENT.md)**

## 🔧 Usage Examples

### Repository Management
```python
# List all repositories
get_repositories()

# Filter repositories by type
get_repositories(package_type="maven")
```

### Artifact Operations
```python
# Browse repository contents
list_artifacts("my-repo-local")
list_artifacts("my-repo-local", "path/to/folder")
list_artifacts("my-repo-local", "", deep=True)  # Recursive listing

# Get artifact details
get_artifact_details("libs-release-local", "com/example/app/1.0.0/app-1.0.0.jar")

# Download an artifact
download_artifact("libs-release-local", "path/to/artifact.jar", "/local/path/artifact.jar")

# Upload an artifact
push_artifact("libs-release-local", "com/example/app/1.0.0/app-1.0.0.jar", "/local/path/app-1.0.0.jar")
```

### Safe Deletion
```python
# This will show a warning and NOT delete
delete_artifact("my-repo", "path/to/artifact.jar")

# This will actually delete the artifact
delete_artifact("my-repo", "path/to/artifact.jar", confirm_deletion=True)
```

### Cleanup Operations
```python
# Search for old artifacts (safe preview)
search_old_artifacts("libs-snapshot-local", older_than_days=30)

# Preview cleanup (dry run - safe)
cleanup_old_artifacts("libs-snapshot-local", older_than_days=30, dry_run=True)

# Execute cleanup
cleanup_old_artifacts("libs-snapshot-local", older_than_days=30, dry_run=False)

# Target specific folders
cleanup_old_artifacts("docker-local", older_than_days=60, folder_path="old-images/", dry_run=False)
```

## 🛠️ Available Tools

| Tool | Description | Safety Level |
|------|-------------|--------------|
| `get_repositories` | List available repositories | ✅ Safe |
| `list_artifacts` | Browse repository contents | ✅ Safe |
| `get_artifact_details` | Get artifact metadata | ✅ Safe |
| `download_artifact` | Download artifacts locally | ✅ Safe |
| `push_artifact` | Upload artifacts to repository | ⚠️ Modifying |
| `delete_artifact` | Delete single artifact | 🔒 Requires Confirmation |
| `search_old_artifacts` | Find artifacts by age | ✅ Safe |
| `cleanup_old_artifacts` | Bulk cleanup by age | 🔒 Supports Dry Run |

## 🛡️ Safety Features

### Deletion Protection
- All deletion operations require explicit `confirm_deletion=True` parameter
- Input validation prevents empty paths and repository root deletion
- Existence verification before attempting deletion
- Clear error messages for invalid operations

### Dry Run Mode
- Cleanup operations default to `dry_run=True`
- Preview exactly what would be deleted before execution
- Detailed reports showing affected artifacts and storage impact

### Error Handling
- Comprehensive error messages with actionable guidance
- Graceful handling of network issues and authentication failures
- Detailed logging for troubleshooting

## 🐛 Troubleshooting

### Common Issues

#### Authentication Errors
```bash
Error: 401 Unauthorized
```
- Verify your access token or username/password
- Check token permissions in JFrog Artifactory
- Ensure base URL is correct

#### Connection Issues
```bash
Error: Connection timeout
```
- Verify JFrog Artifactory URL is accessible
- Check network connectivity and firewall settings
- Validate base URL format (should include `/artifactory`)

#### Permission Errors
```bash
Error: 403 Forbidden
```
- Verify your user has appropriate repository permissions
- Check if repository exists and is accessible
- Review JFrog permission model for your user/token

### Debug Mode
Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup
```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/

# Run linting
flake8 jfrog_mcp/
```

## 📄 License

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

## 🆘 Support

For support and questions:
- Open an issue on GitHub
- Check the [JFrog Artifactory REST API documentation](https://www.jfrog.com/confluence/display/JFROG/Artifactory+REST+API)
- Review MCP protocol documentation

## 🏗️ Architecture

```
jfrog_mcp/
├── __init__.py          # Package initialization
├── __main__.py          # CLI entry point
├── config.py            # Configuration management
├── server.py            # MCP server and tool definitions
└── api/
    ├── __init__.py
    └── artifactory.py   # JFrog Artifactory API client
```

## 🔮 Future Features

- [ ] Build information management
- [ ] Repository creation and configuration
- [ ] Advanced search with AQL (Artifactory Query Language)
- [ ] Artifact properties management
- [ ] Replication status monitoring
- [ ] Docker registry specific operations
- [ ] Maven/Gradle metadata handling
- [ ] Bulk operations with progress tracking

---

**Made with ❤️ for the JFrog and MCP communities**