Jira Insights MCP

Instructions

Implementation Reference

• src/handlers/schema-handlers.ts:16-167 (handler)

  The setupSchemaHandlers function implements the core logic for the 'manage_jira_insight_schema' tool, handling CRUD operations (get, list, create, update, delete) on Jira Insight schemas via the Jira Assets API, with schema cache management and error handling.

  export async function setupSchemaHandlers(
    server: Server,
    jiraClient: JiraClient,
    schemaCacheManager: SchemaCacheManager,
    request: any
  ): Promise<ToolResponse> {
    const { arguments: args } = request.params;
    const operation = args.operation as SchemaOperation;
  
    // Normalize parameter names (support both camelCase and snake_case)
    const schemaId = args.schemaId || args.schema_id;
    const startAt = args.startAt || args.start_at || 0;
    const maxResults = args.maxResults || args.max_results || 50;
  
    try {
      const assetsApi = await jiraClient.getAssetsApi();
  
      switch (operation) {
      case 'get': {
        if (!schemaId) {
          throw new McpError(ErrorCode.InvalidParams, 'Schema ID is required for get operation');
        }
  
        const schema = await assetsApi.schemaFind({ id: schemaId });
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(schema, null, 2),
            },
          ],
        };
      }
  
      case 'list': {
        const schemaList = await assetsApi.schemaList({
          startAt,
          maxResults,
        });
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(schemaList, null, 2),
            },
          ],
        };
      }
  
      case 'create': {
        if (!args.name) {
          throw new McpError(ErrorCode.InvalidParams, 'Name is required for create operation');
        }
  
        const newSchema = await assetsApi.schemaCreate({
          objectSchemaIn: {
            name: args.name,
            description: args.description || '',
          },
        });
  
        // Refresh the schema cache for the new schema
        await schemaCacheManager.refreshSchema(newSchema.id);
        console.error(`Schema cache refreshed for new schema ${newSchema.id}`);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(newSchema, null, 2),
            },
          ],
        };
      }
  
      case 'update': {
        if (!schemaId) {
          throw new McpError(ErrorCode.InvalidParams, 'Schema ID is required for update operation');
        }
  
        // First get the existing schema
        const existingSchema = await assetsApi.schemaFind({ id: schemaId }) as {
            name: string;
            description: string;
          };
  
        // Update with new values
        const updatedSchema = await assetsApi.schemaUpdate({
          id: schemaId,
          objectSchemaIn: {
            name: args.name || existingSchema.name,
            description: args.description !== undefined ? args.description : existingSchema.description,
          },
        });
  
        // Refresh the schema cache for the updated schema
        await schemaCacheManager.refreshSchema(schemaId);
        console.error(`Schema cache refreshed for updated schema ${schemaId}`);
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(updatedSchema, null, 2),
            },
          ],
        };
      }
  
      case 'delete': {
        if (!schemaId) {
          throw new McpError(ErrorCode.InvalidParams, 'Schema ID is required for delete operation');
        }
  
        await assetsApi.schemaDelete({ id: schemaId });
  
        // Refresh all schemas after deletion to ensure consistency
        await schemaCacheManager.refreshAllSchemas();
        console.error('Schema cache refreshed after schema deletion');
  
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({ success: true, message: `Schema ${schemaId} deleted successfully` }, null, 2),
            },
          ],
        };
      }
  
      default:
        throw new McpError(ErrorCode.InvalidParams, `Unsupported operation: ${operation}`);
      }
    } catch (error) {
      console.error('Error in schema handler:', error);
      
      if (error instanceof McpError) {
        throw error;
      }
      
      // Use the new error handler with context
      return handleError(error, operation, {
        schemaId,
        name: args.name,
        description: args.description,
        startAt,
        maxResults,
        expand: args.expand
      });
    }
  }

• src/schemas/tool-schemas.ts:5-53 (schema)

  Input schema definition for the 'manage_jira_insight_schema' tool, specifying parameters for CRUD operations including operation type, schemaId, name, description, pagination (startAt, maxResults), and expand options.

  manage_jira_insight_schema: {
    name: 'manage_jira_insight_schema',
    description: 'Manage Jira Insights object schemas with CRUD operations',
    inputSchema: {
      type: 'object',
      properties: {
        operation: {
          type: 'string',
          enum: ['get', 'list', 'create', 'update', 'delete'],
          description: 'Operation to perform on the schema',
        },
        // Parameters for get, update, delete operations
        schemaId: {
          type: 'string',
          description: 'The ID of the schema. Required for get, update, and delete operations. Can also use snake_case "schema_id".',
        },
        // Parameters for create and update operations
        name: {
          type: 'string',
          description: 'Name of the schema. Required for create operation, optional for update.',
        },
        description: {
          type: 'string',
          description: 'Description of the schema. Optional for create/update.',
        },
        // Parameters for list operation
        startAt: {
          type: 'integer',
          description: 'Index of the first schema to return (0-based). Used for list operation. Can also use snake_case "start_at".',
          default: 0,
        },
        maxResults: {
          type: 'integer',
          description: 'Maximum number of schemas to return. Used for list operation. Can also use snake_case "max_results".',
          default: 50,
        },
        // Common expansion options
        expand: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['objectTypes', 'attributes', 'statistics'],
          },
          description: 'Optional fields to include in the response',
        },
      },
      required: ['operation'],
    },
  },

• src/index.ts:152-154 (registration)

  Conditional dispatch in the MCP CallToolRequestHandler that routes requests for the 'manage_jira_insight_schema' tool to the setupSchemaHandlers function.

  if (['manage_jira_insight_schema'].includes(name)) {
    response = await setupSchemaHandlers(this.server, this.jiraClient, this.schemaCacheManager, request);
  }