mantis-manager

Manage Mantis Bug Tracker (issues, projects, users, filters, configs) via the official Mantis REST API. Supports full CRUD operations on issues, projects, users, attachments, notes, tags, relationships, and configuration management. Features dynamic instance switching with context-aware base URL and token resolution.

# Mantis Manager Skill (Enhanced)

## 🔐 Base URL & Token Resolution

### Base URL Resolution
Base URL precedence (highest to lowest):
1. `temporary_base_url` — one-time use URL for specific operations
2. `user_base_url` — user-defined URL for the current session
3. `MANTIS_BASE_URL` — environment default URL

This allows you to:
- Switch between multiple Mantis instances dynamically
- Test against staging/production environments
- Work with different client instances without changing config

**Example:**
```
// Default: uses MANTIS_BASE_URL from environment
GET {{resolved_base_url}}/issues

// Override for one operation:
temporary_base_url = "https://mantis-staging.example.com/api/rest"
GET {{resolved_base_url}}/issues

// Override for session:
user_base_url = "https://client-mantis.example.com/api/rest"
GET {{resolved_base_url}}/issues
```

### Token Resolution
Token precedence (highest to lowest):
1. `temporary_token` — one-time use token for specific operations
2. `user_token` — user-defined token for the current session
3. `MANTIS_API_TOKEN` — environment default token

Environment variables are handled via standard OpenClaw metadata: `requires.env` declares **required** variables (`MANTIS_BASE_URL`, `MANTIS_API_TOKEN`). Any other environment variables you use for Mantis should be treated as normal process env vars and are not modeled as special OpenClaw metadata fields.

### Authentication Headers
**All API requests must include:**

```
Authorization: Bearer {{resolved_token}}
Content-Type: application/json
```

**Note:** The `{{resolved_base_url}}` and `{{resolved_token}}` are determined at runtime based on the precedence rules above.

---

## 📌 Notation Used in Examples

Throughout this documentation:
- `{{MANTIS_BASE_URL}}` refers to the **resolved base URL** (could be temporary_base_url, user_base_url, or env MANTIS_BASE_URL)
- `{{resolved_token}}` refers to the **resolved token** (could be temporary_token, user_token, or env MANTIS_API_TOKEN)
- All endpoints use the pattern: `{{MANTIS_BASE_URL}}/resource/path`

**Important:** Always use the resolution logic to determine the actual URL and token at runtime.

---

## 🔄 Context Management

> The `temporary_*` and `user_*` names here are **runtime context variables used by the skill logic**, not OpenClaw metadata fields. OpenClaw does **not** define an `optional.context` metadata key; context is resolved dynamically at runtime as described below.

### Setting Temporary Values (One-Time Use)

**User queries:**
- "Use https://staging.mantis.com/api/rest for this request"
- "Connect to production instance for this operation"
- "Use token ABC123 just this once"

**Action:**
```
Set temporary_base_url = "https://staging.mantis.com/api/rest"
Set temporary_token = "ABC123"
... perform operation ...
Clear temporary_base_url
Clear temporary_token
```

**Behavior:** Temporary values are automatically cleared after one use.

### Setting Session Values (Current Session)

**User queries:**
- "Switch to client XYZ's Mantis instance"
- "Use my personal API token for all requests"
- "Connect to staging environment"

**Action:**
```
Set user_base_url = "https://client-xyz.mantis.com/api/rest"
Set user_token = "personal_token_123"
... perform multiple operations ...
// Values persist for the entire session
```

**Behavior:** Session values persist until explicitly cleared or session ends.

### Clearing Context Values

**User queries:**
- "Reset to default Mantis instance"
- "Clear my custom token"
- "Go back to environment defaults"

**Action:**
```
Clear user_base_url
Clear user_token
// Now uses MANTIS_BASE_URL and MANTIS_API_TOKEN from environment
```

### Viewing Current Context

**User queries:**
- "What Mantis instance am I connected to?"
- "Show current API configuration"
- "Which token am I using?"

**Response should show:**
```
Current Context:
- Base URL: https://client-xyz.mantis.com/api/rest (user_base_url)
- Token: user_t***123 (user_token)
- Fallback Base URL: https://default.mantis.com/api/rest (MANTIS_BASE_URL)
- Fallback Token: env_t***789 (MANTIS_API_TOKEN)
```

### Use Cases

#### Multi-Instance Management
```
// Check production issue
Set temporary_base_url = "https://prod.mantis.com/api/rest"
Get issue 123

// Check staging issue  
Set temporary_base_url = "https://staging.mantis.com/api/rest"
Get issue 123

// Compare results
```

#### Client Switching
```
// Switch to Client A
Set user_base_url = "https://clienta.mantis.com/api/rest"
Set user_token = "clienta_token"
List all projects
Get issues for project 5

// Switch to Client B
Set user_base_url = "https://clientb.mantis.com/api/rest"
Set user_token = "clientb_token"
List all projects
Get issues for project 3
```

#### Admin Operations with Impersonation
```
// Connect to main instance as admin
Set user_token = "admin_token"

// Perform operation as specific user
Set temporary header: X-Impersonate-User = "john.doe"
Get user issues

// Back to admin
Clear temporary header
```

---

## 🐞 ISSUES Operations

### List Issues
**User queries:**
- "List all issues"
- "Get issues for project 5"
- "Get issues matching filter 10"
- "Show issues assigned to me"
- "Get unassigned issues"

**Actions:**
```
GET {{MANTIS_BASE_URL}}/issues
```

**Query Parameters:**
- `page_size` — number of issues per page (default: 50)
- `page` — page number (1-indexed)
- `filter_id` — ID of saved filter to apply
- `project_id` — filter by specific project
- `select` — comma-separated fields to return (e.g., "id,summary,status")

**Special endpoints:**
```
GET {{MANTIS_BASE_URL}}/issues?filter_id={{filter_id}}
GET {{MANTIS_BASE_URL}}/projects/{{project_id}}/issues
```

### Get Single Issue
**User queries:**
- "Show issue 123"
- "Get details for bug 456"

**Action:**
```
GET {{MANTIS_BASE_URL}}/issues/{{id}}
```

### Create Issue
**User queries:**
- "Create issue with summary 'Login bug' and description 'Cannot login'"
- "Create bug in project 5 with priority high"
- "Create issue with attachments"

**Action:**
```
POST {{MANTIS_BASE_URL}}/issues
```

**Minimal body:**
```json
{
  "summary": "Issue summary",
  "description": "Detailed description",
  "category": {"name": "General"},
  "project": {"id": 1}
}
```

**Full body (optional fields):**
```json
{
  "summary": "Issue summary",
  "description": "Detailed description",
  "steps_to_reproduce": "1. Do this\n2. Do that",
  "additional_information": "Extra info",
  "category": {"id": 1, "name": "General"},
  "project": {"id": 1},
  "priority": {"id": 30, "name": "normal"},
  "severity": {"id": 50, "name": "minor"},
  "status": {"id": 10, "name": "new"},
  "reproducibility": {"id": 10, "name": "always"},
  "handler": {"id": 5},
  "tags": [{"name": "bug"}, {"name": "ui"}],
  "custom_fields": [{"field": {"id": 1}, "value": "custom value"}],
  "due_date": "2026-12-31T23:59:59+00:00",
  "version": {"name": "1.0"},
  "target_version": {"name": "2.0"}
}
```

**Create with attachments:**
```
POST {{MANTIS_BASE_URL}}/issues
```
Include `files` array in body with base64-encoded content.

### Update Issue
**User queries:**
- "Update issue 123 status to resolved"
- "Change priority of bug 456 to high"
- "Assign issue 789 to user 10"

**Action:**
```
PATCH {{MANTIS_BASE_URL}}/issues/{{id}}
```

**Example body:**
```json
{
  "status": {"name": "resolved"},
  "handler": {"id": 10},
  "priority": {"name": "high"},
  "summary": "Updated summary"
}
```

### Delete Issue
**User queries:**
- "Delete issue 123"
- "Remove bug 456"

**Action:**
```
DELETE {{MANTIS_BASE_URL}}/issues/{{id}}
```

### Monitor/Unmonitor Issue
**User queries:**
- "Monitor issue 123"
- "Stop monitoring bug 456"
- "Add user 10 as monitor on issue 789"

**Actions:**
```
POST   {{MANTIS_BASE_URL}}/issues/{{id}}/monitors
DELETE {{MANTIS_BASE_URL}}/issues/{{id}}/monitors
```

**Body (for specific user):**
```json
{
  "user": {"id": 10}
}
```

### Attach/Detach Tags
**User queries:**
- "Add tag 'critical' to issue 123"
- "Remove tag 'bug' from issue 456"

**Actio