JSM Assets MCP Server

# 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 →**](./QUICK-START.md) ## 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 →**](./INSTALLATION.md) ### Quick Options **🚀 Claude Desktop (Recommended)** ```bash # Build and install .dxt package npm run build:dxt # Double-click jsm-assets-mcp.dxt → Install ``` **⚡ Claude Code** ```bash 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** ```bash 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: ```env 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` ```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: ```env 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.