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:

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:

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.