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 stringautoPages(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 namefilters(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 projectnpm run dev- Watch mode for developmentnpm run start- Run the built servernpm 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.
