Jira Asset Schema Orchestrator (JASO)

This repository offers an implementation of an MCP server dedicated to orchestrating schema assets within the Jira Insights (JSM) ecosystem.

Last revision: 2025-04-09

High-Level Summary

This specialized MCP endpoint exposes functionality for interacting with Jira Insights metadata structures through the Model Context Protocol. Key capabilities involve deep management of object schemas, definition of object types, and manipulation of the underlying data objects, complemented by powerful Assets Query Language (AQL) retrieval mechanisms.

Core Capabilities

• Schema Lifecycle Management: Full CRUD operations on Insight object schemas.
• Type Definition Control: Full CRUD operations on defined object types within schemas.
• Object Manipulation: Full CRUD operations on specific asset instances.
• Data Retrieval: Execute complex queries on objects utilizing AQL for targeted data extraction.

Prerequisites for Deployment

• Node.js runtime environment (version 20+ required).
• Docker (recommended for standardized deployment environments).
• Active connection credentials for the target Jira Insights installation.
• A Jira API access token provisioned with necessary administrative scopes.

Deployment Pathways

Local Environment Setup

1. Checkout the source repository: bash git clone https://github.com/aaronsb/jira-insights-mcp.git cd jira-insights-mcp

2. Install required software packages: bash npm install

3. Compile the source code: bash npm run build

Containerized Deployment (Docker)

To finalize the deployable container image:

bash ./scripts/build-local.sh

Integration and Configuration

To integrate this service with an AI assistant utilizing the MCP framework, integrate the following server configuration snippet into your main configuration file:

Local Binary Configuration

When running directly from your build artifacts:

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

Containerized Service Configuration (Recommended)

Using the published Docker image from GHCR:

{ "mcpServers": { "jirahub-assets": { "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": "your-email@example.com", "JIRA_HOST": "https://your-domain.atlassian.net" } } } }

This container method pulls the current release and executes it, requiring environment variables to be supplied at runtime.

Local Execution for Testing

For immediate local testing and development workflows:

bash

Stage the container image

./scripts/build-local.sh

Execute the containerized service, injecting credentials via shell variables

JIRA_API_TOKEN=your_token JIRA_EMAIL=your_email JIRA_HOST=your_host ./scripts/run-local.sh

Available Tool Invocation Schemas

Schema Definition Handler (manage_jira_insight_schema)

Example for enumerating existing schemas:

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

Object Type Configuration Handler (manage_jira_insight_object_type)

Example to list types belonging to a specific schema ID:

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

Asset Instance Handler (manage_jira_insight_object)

Example performing a targeted data query using AQL:

{ "operation": "query", "aql": "objectType = \"Application\" AND status = \"Active\"", "maxResults": 10 }

Accessible Endpoint References

The service exposes several informational and direct data access URIs:

• jira-insights://instance/summary: Provides aggregated statistics about the connected JSM environment.
• jira-insights://aql-syntax: Reference documentation detailing AQL structure and functions.
• jira-insights://schemas/all: Retrieval of all registered schema identifiers and their associated types.
• jira-insights://schemas/{schemaId}/full: Complete definition set for a specific schema, including nested types.
• jira-insights://schemas/{schemaId}/overview: Metadata and summary statistics for a designated schema.
• jira-insights://object-types/{objectTypeId}/overview: Detailed attribute mapping and usage metrics for an object type.

Development Roadmap (Future Work)

Future enhancements are prioritized into immediate and mid-term objectives to increase utility and robustness:

Priority 1: Stability and Query Precision

1. Advanced Exception Handling: Implementation of granular error reporting, including specific validation failure codes and suggested remediation steps. Offer runnable examples alongside error messages.
2. AQL Utility Enhancement: Integrate AQL validation and formatting tools. Provide context-aware query templates and clearer feedback on syntax errors.
3. Attribute Retrieval Optimization: Streamline the fetching of object type attributes, potentially introducing caching mechanisms and improved management of the AQL expand parameter.

Priority 2: Usability and Templating

1. Object Instantiation Templates: Introduce mechanisms to generate baseline JSON templates for new object creation, guided by the target object type definition, including placeholder values.
2. Query Repository: Establish a library of pre-vetted, common AQL queries categorized by schema or use case.
3. Documentation Refinement: Deepen the AQL syntax guide and create comprehensive documentation mapping all available operations to their required inputs and expected outputs.

For the exhaustive task list, consult TODO.md. Implementation blueprints are detailed in IMPLEMENTATION_PLAN.md, and specific handler code remediation notes are found in HANDLER_IMPROVEMENTS.md.

Development Utilities

Local Compilation & Testing Scripts

• npm run build: Compiles TypeScript source to JavaScript.
• npm run lint: Runs static code analysis via ESLint.
• npm run lint:fix: Attempts to auto-correct linting violations.
• npm run test: Executes unit and integration tests.
• npm run watch: Activates file watching for continuous compilation.
• npm run generate-diagrams: Creates visual dependency maps of the codebase.

Container Scripts

• ./scripts/build-local.sh: Prepares the Docker image locally.
• ./scripts/run-local.sh: Launches the containerized service for immediate use.

Troubleshooting Common Integration Failures

AQL Query Parsing Issues

• Quoting: String literals containing whitespace must be double-quoted (e.g., Name = "Project Alpha").
• Operators: Use capitalized boolean logic keywords (AND, OR).
• Existence Check: Confirm that the referenced object type and attribute names precisely match the schema definition.

Object Type Attribute Retrieval Failures

• If using the expand=attributes directive, confirm the underlying object type is resolvable.
• Verify the credentials hold permissions to read schema metadata.

Connectivity and Authentication Errors

• Validate the JIRA_HOST URL is fully qualified and correct.
• Confirm the supplied JIRA_API_TOKEN has sufficient scope for asset interaction.
• Check external firewall rules permitting egress traffic to Atlassian endpoints.

Legal Notice

This software is distributed under the MIT License.

== Business Management Context == Business management instrumentation encompasses the complete suite of applications, methodologies, control frameworks, and analytical solutions utilized by organizations to navigate market fluctuations, sustain competitive advantage, and optimize organizational efficacy.

=== Functional Classification === Management instrumentation can be segmented based on operational focus:

• Instrumentation for data capture and initial integrity checks across functional areas.
• Tools dedicated to process oversight, measurement, and continuous refinement.
• Systems supporting aggregated data visualization and executive decision support.

Modern management software has experienced rapid transformation driven by technological advancements, complicating the selection process for optimal tools. The persistent organizational drivers—cost reduction, revenue growth, deep customer understanding, and precision in service/product delivery—necessitate a strategic, tailored approach to tool adoption. Over-reliance on contemporary, unadapted tools often results in operational instability. The selection process must prioritize organizational fit over mere technological novelty.

=== Global Adoption Trends (2013 Benchmarks) === Historical surveys indicate that adoption patterns for management tools vary regionally, reflecting distinct market pressures. Leading categories frequently cited include:

• Strategic Roadmap Definition
• Client Relationship Orchestration
• Workforce Sentiment Analysis
• Comparative Performance Assessment
• Performance Measurement Frameworks
• Core Capability Identification
• Service Function Outsourcing
• Organizational Transformation Programs
• Logistics Network Management
• Organizational Purpose Definition
• Client Base Segmentation
• Total Quality Assurance Methodologies

=== Enterprise Software Evolution === Business-centric software, defined as programmed collections assisting users in executing corporate functions, originated with Management Information Systems (MIS) and expanded through Enterprise Resource Planning (ERP). This trajectory integrated Customer Relationship Management (CRM) and has now largely migrated to cloud-based service delivery models. Value addition is contingent upon two critical factors: the efficacy of the deployment process and the judicious selection and modification of the chosen tools to align with enterprise requirements.

== Specialized Instrumentation for SMBs == Tools specifically targeting Small and Medium Businesses (SMBs) are vital as they frequently furnish the necessary leverage to maximize operational efficiency with constrained resources...