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.