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 →

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 →

Quick Options

🚀 Claude Desktop (Recommended)

# Build and install .dxt package
npm run build:dxt
# Double-click jsm-assets-mcp.dxt → Install

⚡ Claude Code

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

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:

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

{
  "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:

Request N objects (e.g., 1000)
If exactly N objects are returned, assume more pages exist
Continue requesting until returned count < requested count
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:

DEBUG=true
NODE_ENV=development

Troubleshooting

Common Issues

Authentication Errors
- Verify your token is correctly encoded
- Check workspace ID is correct
- Ensure you have proper JSM Assets permissions
Connection Issues
- Verify the base URL is correct
- Check network connectivity
- Confirm workspace exists and is accessible
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.

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 →

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 →

Quick Options

🚀 Claude Desktop (Recommended)

# Build and install .dxt package
npm run build:dxt
# Double-click jsm-assets-mcp.dxt → Install

⚡ Claude Code

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

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:

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

{
  "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:

Request N objects (e.g., 1000)
If exactly N objects are returned, assume more pages exist
Continue requesting until returned count < requested count
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:

DEBUG=true
NODE_ENV=development

Troubleshooting

Common Issues

Authentication Errors
- Verify your token is correctly encoded
- Check workspace ID is correct
- Ensure you have proper JSM Assets permissions
Connection Issues
- Verify the base URL is correct
- Check network connectivity
- Confirm workspace exists and is accessible
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.