jira insights mcp

Local 2025-09-01 00:34:48 0

Developer Tools @aaronsb/jira-insights-mcp

An MCP server that allows management of Jira Insights (JSM) asset schemas, enabling CRUD operations for object schemas, object types, and objects through the Model Context Protocol.

A Model Context Protocol (MCP) server for managing Jira Insights (JSM) asset schemas.

Last updated: 2025-04-09

Overview

This MCP server provides tools for interacting with Jira Insights (JSM) asset schemas through the Model Context Protocol. It allows you to manage object schemas, object types, and objects in Jira Insights.

Features

Manage object schemas (create, read, update, delete)
Manage object types (create, read, update, delete)
Manage objects (create, read, update, delete)
Query objects using AQL (Atlassian Query Language)

Prerequisites

Node.js 20 or later
Docker (for containerized deployment)
Jira Insights instance with API access
Jira API token with appropriate permissions

Installation

Local Development

Clone the repository:

git clone https://github.com/aaronsb/jira-insights-mcp.git
cd jira-insights-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Docker

Build the Docker image:

./scripts/build-local.sh

Usage

MCP Configuration

To use this MCP server with Claude or other AI assistants that support the Model Context Protocol, add it to your MCP configuration using one of the following methods:

Local Build Configuration

If you've built the project locally, use this configuration:

{
  "mcpServers": {
    "jira-insights": {
      "command": "node",
      "args": ["/path/to/jira-insights-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "LOG_MODE": "strict"
      }
    }
  }
}

Docker-based Configuration

If you prefer to use the Docker image (recommended for most users), use this configuration:

{
  "mcpServers": {
    "jira-insights": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_API_TOKEN",
        "-e", "JIRA_EMAIL",
        "-e", "JIRA_HOST",
        "ghcr.io/aaronsb/jira-insights-mcp:latest"
      ],
      "env": {
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_HOST": "https://your-domain.atlassian.net"
      }
    }
  }
}

This Docker-based configuration pulls the latest image from GitHub Container Registry and runs it with the necessary environment variables.

Running Locally for Development

For local development and testing:

# Build the Docker image
./scripts/build-local.sh

# Run the Docker container
JIRA_API_TOKEN=your_token JIRA_EMAIL=your_email JIRA_HOST=your_host ./scripts/run-local.sh

Available Tools

manage_jira_insight_schema

Manage Jira Insights object schemas with CRUD operations.

{
  "operation": "list",
  "maxResults": 10
}

manage_jira_insight_object_type

Manage Jira Insights object types with CRUD operations.

{
  "operation": "list",
  "schemaId": "1",
  "maxResults": 20
}

manage_jira_insight_object

Manage Jira Insights objects with CRUD operations and AQL queries.

{
  "operation": "query",
  "aql": "objectType = "Application"",
  "maxResults": 10
}

Available Resources

The MCP server provides several resources for accessing Jira Insights data:

jira-insights://instance/summary - High-level statistics about the Jira Insights instance
jira-insights://aql-syntax - Comprehensive guide to Assets Query Language (AQL) syntax with examples
jira-insights://schemas/all - Complete list of all schemas with their object types
jira-insights://schemas/{schemaId}/full - Complete definition of a specific schema including object types
jira-insights://schemas/{schemaId}/overview - Overview of a specific schema including metadata and statistics
jira-insights://object-types/{objectTypeId}/overview - Overview of a specific object type including attributes and statistics

Planned Improvements

We are working on several improvements to enhance the functionality and usability of the Jira Insights MCP:

High Priority Improvements

Enhanced Error Handling
More detailed error messages with specific validation issues
Suggested fixes for common errors
Operation-specific examples to help users correct issues
AQL Query Improvements
Validation and formatting utilities for AQL queries
Schema-specific example queries
Better error messages for query issues
Attribute Discovery Enhancement
Improved attribute retrieval for object types
Caching for better performance
Better handling of the "expand" parameter

Medium Priority Improvements

Object Template Generation
Templates for creating objects based on object types
Type-specific placeholder generation
Validation rules in templates
Example Query Library
Schema-specific example queries
Context-aware query suggestions
Query templates for common operations
Improved Documentation
Enhanced AQL syntax documentation
Operation-specific documentation
Common error scenarios and solutions

For more details on the planned improvements, see: - TODO.md - Comprehensive todo list with all tasks organized by priority - IMPLEMENTATION_PLAN.md - Detailed implementation plans for the high-priority improvements - HANDLER_IMPROVEMENTS.md - Specific changes needed for each handler file - IMPROVEMENT_SUMMARY.md - Concise summary of the planned improvements - docs/API_MIGRATION_TODO.md - Status of the API migration and planned improvements

Development

Scripts

npm run build: Build the TypeScript code
npm run lint: Run ESLint
npm run lint:fix: Run ESLint with auto-fix
npm run test: Run tests
npm run watch: Watch for changes and rebuild
npm run generate-diagrams: Generate TypeScript dependency diagrams

Docker Scripts

./scripts/build-local.sh: Build the Docker image
./scripts/run-local.sh: Run the Docker container

Troubleshooting

Common Issues

AQL Query Validation Errors
Ensure values with spaces are enclosed in quotes: Name = "John Doe"
Use uppercase for logical operators: AND, OR (not and, or)
Check that object types and attributes exist in your schema
Object Type Attribute Issues
When using the "expand" parameter with "attributes", ensure the object type exists
Check that you have permissions to view the attributes
API Connection Issues
Verify your Jira API token has the necessary permissions
Check that the Jira host URL is correct
Ensure your network allows connections to the Jira API

License

MIT