JSM Assets MCP Server

# JSM Assets MCP Server

A Model Context Protocol (MCP) server that provides AI assistants like Claude access to Jira Service Management (JSM) Assets data through standardized tools.

> **🆕 New Features**: Robust automatic pagination, Claude Code support, and reliable complete data retrieval!

## 🚀 Quick Start

**Get started in under 5 minutes**: [**Quick Start Guide →**](./QUICK-START.md)

## Features

- **🔍 Search Assets with AQL**: Use Assets Query Language for complex searches with robust pagination
- **📋 Browse Object Schemas**: List all available asset schemas  
- **🏗️ Explore Object Types**: View object types within schemas
- **📝 Inspect Object Attributes**: Get detailed attribute information
- **🌳 Find Child Objects**: Search hierarchical object relationships with automatic pagination
- **⚡ Robust Pagination**: Never miss data with reliable multi-page retrieval
- **🖥️ Multi-Platform**: Works with Claude Desktop (.dxt) and Claude Code (CLI)

## Installation

**Multiple installation options available**: [**Complete Installation Guide →**](./INSTALLATION.md)

### Quick Options

**🚀 Claude Desktop (Recommended)**
```bash
# Build and install .dxt package
npm run build:dxt
# Double-click jsm-assets-mcp.dxt → Install
```

**⚡ Claude Code**
```bash
claude mcp add jsm-assets \
  -e JSM_WORKSPACE_ID="your-id" \
  -e JSM_AUTH_TOKEN="Basic your-token" \
  -- node /path/to/jsm-assets-mcp/dist/index.js
```

**🛠️ Traditional Setup**
```bash
git clone <repo-url> && cd jsm-assets-mcp
npm install && npm run build
cp .env.example .env  # Edit with your credentials
```

## Configuration

### Environment Variables

Create a `.env` file with the following variables:

```env
JSM_WORKSPACE_ID=your-workspace-id
JSM_AUTH_TOKEN=Basic your-encoded-token
JSM_BASE_URL=https://api.atlassian.com/jsm/assets/workspace
```

### Claude Desktop Integration

Add to your Claude Desktop configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "jsm-assets": {
      "command": "node",
      "args": ["/path/to/jsm-assets-mcp/dist/index.js"],
      "env": {
        "JSM_WORKSPACE_ID": "your-workspace-id",
        "JSM_AUTH_TOKEN": "Basic your-encoded-token",
        "JSM_BASE_URL": "https://api.atlassian.com/jsm/assets/workspace"
      }
    }
  }
}
```

## Available Tools

### 1. search_assets_aql
Search assets using AQL (Assets Query Language) with robust automatic pagination.

**Parameters:**
- `aqlQuery` (required): AQL query string
- `autoPages` (optional): Enable automatic pagination (default: false for backward compatibility)
- `maxPages` (optional): Maximum pages to fetch when autoPages=true (default: 10, safety limit)
- `pageSize` (optional): Objects per page when autoPages=true (default: 1000)
- `startAt` (optional): Starting index for single-page requests when autoPages=false (default: 0)
- `maxResults` (optional): Max results for single-page requests when autoPages=false (default: 1000)

**Examples:**
```
# Basic search (single page)
objectType="Installation Package" AND Key startswith IASM

# Automatic pagination to get ALL results
{
  "aqlQuery": "objectType=\"Installation Package\"",
  "autoPages": true,
  "maxPages": 20
}
```

**Pagination Behavior:**
- When `autoPages=false`: Traditional single API request (backward compatible)
- When `autoPages=true`: Uses robust pagination that continues fetching until returned count < requested count
- Avoids relying on potentially unreliable API metadata (total, isLast)
- Provides clear feedback about pages fetched and potential limits reached

### 2. get_object_schemas
List all object schemas in the workspace.

**Parameters:** None

### 3. get_object_types
Get object types for a specific schema.

**Parameters:**
- `schemaId` (required): Schema ID number

### 4. get_object_attributes
Get attributes for a specific object type.

**Parameters:**
- `objectTypeId` (required): Object type ID number

### 5. search_child_objects
Search for child objects of a parent type with automatic pagination and optional filters.

**Parameters:**
- `parentObjectType` (required): Parent object type name
- `filters` (optional): Object with optional filters:
  - `dateFrom`: Start date (YYYY-MM-DD HH:mm)
  - `dateTo`: End date (YYYY-MM-DD HH:mm)
  - `keyPrefix`: Key prefix filter
- `autoPages` (optional): Enable automatic pagination (default: true for child objects)
- `maxPages` (optional): Maximum pages to fetch when autoPages=true (default: 10, safety limit)
- `pageSize` (optional): Objects per page when autoPages=true (default: 1000)

**Note:** Child object searches default to automatic pagination since hierarchical queries often return large result sets.

## Robust Pagination

This MCP server implements a reliable pagination strategy that doesn't rely on potentially unreliable JSM API metadata:

### The Problem
JSM Assets API responses include `total` and `isLast` fields that can sometimes be inaccurate, leading to incomplete data retrieval.

### The Solution
Our robust pagination uses this reliable pattern:
1. Request N objects (e.g., 1000)
2. If exactly N objects are returned, assume more pages exist
3. Continue requesting until returned count < requested count
4. This ensures complete data retrieval without relying on API metadata

### Benefits
- ✅ **Reliable**: Gets all data regardless of API metadata accuracy
- ✅ **Safe**: Built-in maxPages limits prevent runaway requests  
- ✅ **Backward Compatible**: Single-page requests still work as before
- ✅ **Transparent**: Clear feedback about pages fetched and limits reached

### Usage Examples

**Get ALL Installation Packages (automatic pagination):**
```
Ask Claude: "Search for ALL Installation Package assets with automatic pagination"
# Uses autoPages=true to fetch complete results across multiple pages
```

**Large Hierarchical Queries:**
```
Ask Claude: "Find all child objects of Hardware type - get complete results"
# Child object searches use automatic pagination by default
```

**Single Page (traditional):**
```
Ask Claude: "Search for Installation Package assets starting with IASM (single page only)"
# Uses autoPages=false for single API request
```

## Example Queries

### Basic Asset Search
```
Ask Claude: "Search for all Installation Package assets that start with IASM"
```

### Complete Data Retrieval
```
Ask Claude: "Get ALL Hardware assets with automatic pagination - don't miss any results"
```

### Hierarchical Search
```
Ask Claude: "Find all child objects of Hardware type created in the last month"
```

### Schema Exploration
```
Ask Claude: "What object schemas are available in this workspace?"
```

### Attribute Analysis
```
Ask Claude: "What attributes are available for object type ID 123?"
```

## API Reference

### JSM Assets API Endpoints Used

- `POST /object/aql` - AQL searches
  
- `GET /objectschema/list` - List schemas
- `GET /objectschema/{id}/objecttypes/flat` - Get object types
- `GET /objecttype/{id}/attributes` - Get attributes

### Authentication

Uses Basic Authentication with pre-encoded tokens. The token should be Base64 encoded in the format:
```
email:api_token
```

## Development

### Scripts
- `npm run build` - Build the TypeScript project
- `npm run dev` - Watch mode for development
- `npm run start` - Run the built server
- `npm run clean` - Clean build artifacts

### Project Structure
```
src/
├── index.ts              # Main MCP server
├── api/                  # JSM API client
│   └── jsmClient.ts
├── tools/                # MCP tool implementations
│   ├── searchAssetsAql.ts
│   ├── getObjectSchemas.ts
│   ├── getObjectTypes.ts
│   ├── getObjectAttributes.ts
│   └── searchChildObjects.ts
├── types/                # TypeScript type definitions
│   └── index.ts
└── utils/                # Utility functions
    └── index.ts
```

## Error Handling

The server includes comprehensive error handling:
- Input validation for all parameters
- API error transformation and reporting
- Graceful fallbacks for missing data
- Debug logging when enabled

## Debugging

Enable debug logging by setting:
```env
DEBUG=true
NODE_ENV=development
```

## Troubleshooting

### Common Issues

1. **Authentication Errors**
   - Verify your token is correctly encoded
   - Check workspace ID is correct
   - Ensure you have proper JSM Assets permissions

2. **Connection Issues**
   - Verify the base URL is correct
   - Check network connectivity
   - Confirm workspace exists and is accessible

3. **Query Errors** 
   - Validate AQL syntax
   - Check object type names exist
   - Verify schema IDs are correct

### Support

For issues with the MCP server implementation, check:
- Server logs for detailed error messages
- Environment variable configuration
- Network connectivity to JSM APIs
- Token permissions and expiration

## License

ISC License - see LICENSE file for details.