Jira Insights MCP

🚀 Jira Insight MCP Server

This is a Model Context Protocol (MCP) server for managing Jira Insights asset schemas. It offers CRUD operations for asset schemas, object types, and attributes, and supports data retrieval via AQL queries.

🚀 Quick Start

This server is designed to manage Jira Insights asset schemas, providing CRUD operations for asset schemas, object types, and attributes. It also supports data retrieval through AQL queries.

✨ Features

• Asset Schema Management: Supports creating, reading, updating, and deleting asset schemas.
• Object Type Management: Provides full and incremental information about object types, including attribute expansion.
• Attribute Management: Allows retrieving detailed information of a single attribute or multiple attributes and supports searching for attributes by name.
• AQL Query: Enables complex data retrieval using AQL syntax.

📦 Prerequisites

1. Install Node.js and npm (Node 16.x or higher is recommended).
2. Install Docker (for Docker deployment).
3. Obtain a Jira API access token and ensure it has the necessary permissions.

📦 Installation

Local Development Installation

1. Clone the repository:

   git clone [Repository URL]
   cd jira-insight-mcp-server
   

2. Install dependencies:

   npm install
   

3. Start the server:

   npm start
   

Docker Deployment

1. Build the Docker image:

   ./scripts/build-local.sh
   

2. Run the container:

   ./scripts/run-local.sh
   

💻 Usage Examples

Server Configuration

You can set the following parameters via environment variables or configuration files:

• JIRA_API_TOKEN: Jira API access token.
• JIRA_HOST_URL: URL of the Jira instance.

Example Usage

# Set environment variables and start the container
export JIRA_API_TOKEN="your_token_here"
export JIRA_HOST_URL="https://your-jira-instance.atlassian.com"
docker-compose up

🛠️ Toolset

Asset Schema Management Tool

• Command: manage_jira_insight_schema
• Functions:
  • Create a new asset schema.
  • Retrieve detailed information of an asset schema with a specified ID.
  • Update an existing asset schema.
  • Delete an asset schema with a specified ID.

Object Type Management Tool

• Command: manage_jira_object_type
• Functions:
  • Retrieve complete or incremental information of all object types, supporting the expand=attributes parameter.

Attribute Management Tool

• Command: manage_jira_attribute
• Functions:
  • Retrieve detailed information of a single attribute.
  • Search for multiple attributes matching a specified name.

📊 Resource Overview

📈 Planned Improvements

High-Priority Improvements

1. Enhanced Error Handling:
   • Provide more detailed error information, including specific problem descriptions.
   • Add error repair suggestions and operation examples.
2. Optimized AQL Query Function:
   • Add query validation and formatting tools.
   • Provide example queries customized by schema.
3. Improved Attribute Discovery Mechanism:
   • Optimize attribute retrieval performance and add cache support.
   • Improve the processing logic of the expand parameter.

Medium-Priority Improvements

1. Object Template Generation:
   • Automatically generate creation templates based on object types.
   • Provide placeholder examples and validation rules.
2. Query Library Optimization:
   • Establish a query example library related to schemas.
   • Implement context-aware query suggestion functionality.

🛠️ Development Guide

Script Usage

• npm run build: Build TypeScript code.
• npm run lint: Run ESLint to check code style.
• npm run test: Execute unit tests.
• npm run watch: Enable real-time code monitoring and automatic building.

🚧 Troubleshooting

Common Issues

1. AQL Query Error:
   • Ensure values containing spaces are enclosed in double quotes, e.g., Name = "John Doe".
   • Use uppercase logical operators like AND, OR.
2. Attribute Retrieval Failure:
   • Check if the API access token is valid and has sufficient permissions.
   • Confirm if the object type ID is correct.

📂 Project Files

• Configuration file: config/default.json
• Log files: logs/

⚠️ Important Note

• After modifying the code, you need to rebuild the Docker image for the changes to take effect.
• Use environment variables to avoid hard - coding sensitive information.

For more detailed information, please refer to the project documentation or contact the development team.