npm package: @openpets/jira
Description: Atlassian Jira & Confluence API integration for OpenCode - project management, issue tracking, and documentation
Latest version: 1.0.11

# @opencode/jira

Atlassian Jira & Confluence API integration for OpenCode, providing comprehensive project management, issue tracking, and documentation access.

## Installation

```bash
npm install @opencode/jira
```

## Setup

1. Get your Jira API token from [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Note your Jira base URL (e.g., `https://your-company.atlassian.net`)
3. Set your credentials as environment variables:

```bash
export JIRA_BASE_URL=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your_api_token_here
```

Or create a `.env` file:

```bash
cp .env.example .env
# Edit .env and add your credentials
```

## Available Tools

### Board Operations

#### `jira-get-boards`
List all available Jira boards with optional filtering.

**Example:**
```typescript
{
  type: "scrum",
  projectKey: "PROJ"
}
```

#### `jira-get-board-details`
Get detailed information about a specific board.

**Example:**
```typescript
{
  boardId: "123"
}
```

#### `jira-get-board-issues`
Get issues from a specific board.

**Example:**
```typescript
{
  boardId: "123",
  jql: "status = 'In Progress'",
  maxResults: 50
}
```

### More Jira Tools

The plugin includes many more tools for:
- Issue operations (create, update, transition, search)
- Comments and worklogs
- Project management
- User management
- And more...

### Confluence Tools

#### `confluence-list-spaces`
List all accessible Confluence spaces.

**Example:**
```typescript
{
  status: "current",  // or "archived"
  limit: 10
}
```

#### `confluence-get-space-pages`
Get all pages in a specific space.

**Example:**
```typescript
{
  spaceKey: "DURDEN",
  limit: 25
}
```

#### `confluence-get-page-content`
Get full content and metadata for a specific page.

**Example:**
```typescript
{
  pageId: "33049",
  includeBody: true
}
```

#### `confluence-search-pages`
Search pages using CQL (Confluence Query Language).

**Example:**
```typescript
{
  cql: "space = DURDEN AND type = page",
  limit: 10,
  includeBody: false
}
```

**CQL Examples:**
```
space = DURDEN AND type = page
label = requirements
text ~ "API" AND space = EAMLI
created >= "2024-01-01" AND space = DURDEN
```

## Features

### Jira
- ✅ Full Jira REST API v2/v3 support
- ✅ Agile API integration
- ✅ JQL query support
- ✅ Issue CRUD operations
- ✅ Board and project management

### Confluence
- ✅ Confluence v1 & v2 REST API support
- ✅ CQL (Confluence Query Language) search
- ✅ Space and page management
- ✅ Full HTML content retrieval
- ✅ Page hierarchy access

### General
- ✅ Basic authentication with API tokens
- ✅ Comprehensive error handling
- ✅ Type-safe responses
- ✅ Same credentials for Jira and Confluence

## Response Format

All tools return formatted JSON strings with consistent structure:

```json
{
  "total": 10,
  "boards": [
    {
      "id": 123,
      "name": "Board Name",
      "type": "scrum",
      "location": {
        "projectKey": "PROJ"
      }
    }
  ]
}
```

Errors include helpful context:

```json
{
  "error": "Jira API error: 404 Not Found",
  "message": "Board not found",
  "boardId": "123"
}
```

## API Versions

This plugin supports:
- REST API v2 (default)
- REST API v3 (optional)
- Agile API v1.0

## Dependencies

- `dotenv` - Environment variable management

## License

MIT