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)

⚡ Claude Code

🛠️ Traditional Setup

Configuration

Environment Variables

Create a .env file with the following variables:

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

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:

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):

Large Hierarchical Queries:

Single Page (traditional):

Example Queries

Basic Asset Search

Complete Data Retrieval

Hierarchical Search

Schema Exploration

Attribute Analysis

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:

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

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:

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.