@agllama/mcp 0.5.0

package/dist/tools/issues.js

@@ -0,0 +1,715 @@
+import { z } from 'zod';
+import { getApiClient, LlamaApiError } from '../api-client.js';
+import { getColumnInstructionsForStatus } from '../utils/column-instructions.js';
+import { getSessionDefaults } from './session.js';
+// ============================================
+// Get Issue
+// ============================================
+export const getIssueToolName = 'llama_get_issue';
+export const getIssueToolDescription = `Get full details for a specific issue by its key (e.g., "PROJ-123").
+Returns complete issue information including description, comments, and history. Uses session defaults if orgSlug/projectKey not provided.`;
+export const getIssueToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    issueKey: z.string().describe('Issue key (e.g., "PROJ-123")'),
+});
+export async function executeGetIssue(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const client = getApiClient();
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_get_issue', {
+                orgSlug,
+                projectKey,
+                issueKey: input.issueKey,
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const issue = await client.getIssue(orgSlug, projectKey, input.issueKey);
+        return JSON.stringify({
+            success: true,
+            issue,
+        });
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to get issue: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+// ============================================
+// Create Issue
+// ============================================
+export const createIssueToolName = 'llama_create_issue';
+export const createIssueToolDescription = `Create a new issue in Llama.
+
+Issue types: EPIC, STORY, TASK, BUG, SUBTASK
+Priority levels: CRITICAL, HIGH, MEDIUM (default), LOW, TRIVIAL
+
+**IMPORTANT: SUBTASK type REQUIRES parentKey** - You must provide the parent issue key (e.g., "PROJ-123") when creating a subtask. The parent must be a STORY, TASK, or BUG.
+
+To add to a sprint, provide the sprintId from llama_context.
+Uses session defaults if orgSlug/projectKey not provided.`;
+export const createIssueToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    summary: z.string().describe('Issue title/summary'),
+    description: z.string().optional().describe('Detailed description (markdown supported)'),
+    type: z
+        .enum(['EPIC', 'STORY', 'TASK', 'BUG', 'SUBTASK'])
+        .describe('Issue type'),
+    priority: z
+        .enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'TRIVIAL'])
+        .optional()
+        .describe('Priority level (default: MEDIUM)'),
+    assigneeId: z.string().optional().describe('User ID to assign the issue to'),
+    sprintId: z.string().optional().describe('Sprint ID to add the issue to'),
+    parentKey: z.string().optional().describe('Parent issue key - REQUIRED for SUBTASK type (e.g., "PROJ-123"). Parent must be STORY, TASK, or BUG.'),
+    epicKey: z.string().optional().describe('Epic issue key to link this issue to (for STORY, TASK, BUG)'),
+    estimate: z.number().optional().describe('Story points estimate'),
+    labels: z.array(z.string()).optional().describe('Labels to attach'),
+});
+export async function executeCreateIssue(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const client = getApiClient();
+        // Validate SUBTASK requires parentKey
+        if (input.type === 'SUBTASK' && !input.parentKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'SUBTASK type requires parentKey. You must specify the parent issue key (e.g., "PROJ-123") when creating a subtask. The parent must be a STORY, TASK, or BUG.',
+            });
+        }
+        // Resolve epicKey to parentId if provided
+        let parentId;
+        if (input.epicKey) {
+            // Look up the Epic to get its ID
+            const epic = await client.getIssue(orgSlug, projectKey, input.epicKey);
+            if (epic.type !== 'EPIC') {
+                return JSON.stringify({
+                    success: false,
+                    error: `Issue ${input.epicKey} is not an Epic (type: ${epic.type})`,
+                });
+            }
+            parentId = epic.id;
+        }
+        else if (input.parentKey) {
+            // For subtasks, look up the parent to get its ID
+            const parent = await client.getIssue(orgSlug, projectKey, input.parentKey);
+            parentId = parent.id;
+        }
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_create_issue', {
+                orgSlug,
+                projectKey,
+                summary: input.summary,
+                type: input.type,
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const issue = await client.createIssue(orgSlug, projectKey, {
+            summary: input.summary,
+            description: input.description,
+            type: input.type,
+            priority: input.priority,
+            assigneeId: input.assigneeId,
+            sprintId: input.sprintId,
+            parentId,
+            estimate: input.estimate,
+            labels: input.labels,
+        });
+        return JSON.stringify({
+            success: true,
+            message: `Created issue ${issue.key}`,
+            issue: {
+                key: issue.key,
+                summary: issue.summary,
+                type: issue.type,
+                status: issue.status,
+                priority: issue.priority,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to create issue: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+// ============================================
+// Update Issue
+// ============================================
+export const updateIssueToolName = 'llama_update_issue';
+export const updateIssueToolDescription = `Update an existing issue's fields.
+Only include the fields you want to change.
+Set assigneeId or sprintId to null to unassign/remove from sprint.
+Uses session defaults if orgSlug/projectKey not provided.`;
+export const updateIssueToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    issueKey: z.string().describe('Issue key to update'),
+    summary: z.string().optional().describe('New summary'),
+    description: z.string().optional().describe('New description'),
+    type: z.enum(['EPIC', 'STORY', 'TASK', 'BUG', 'SUBTASK']).optional(),
+    priority: z.enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'TRIVIAL']).optional(),
+    statusId: z.string().optional().describe('Status ID to transition to'),
+    assigneeId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('User ID or null to unassign'),
+    sprintId: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Sprint ID or null to remove from sprint'),
+    epicKey: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('Epic issue key to link to, or null to remove from Epic'),
+    estimate: z.number().nullable().optional().describe('Story points'),
+    labels: z.array(z.string()).optional().describe('Replace all labels'),
+});
+export async function executeUpdateIssue(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const { issueKey, ...updates } = input;
+        const client = getApiClient();
+        // Build update object with only provided fields
+        const updateFields = {};
+        if (updates.summary !== undefined)
+            updateFields.summary = updates.summary;
+        if (updates.description !== undefined)
+            updateFields.description = updates.description;
+        if (updates.type !== undefined)
+            updateFields.type = updates.type;
+        if (updates.priority !== undefined)
+            updateFields.priority = updates.priority;
+        if (updates.statusId !== undefined)
+            updateFields.statusId = updates.statusId;
+        if (updates.assigneeId !== undefined)
+            updateFields.assigneeId = updates.assigneeId;
+        if (updates.sprintId !== undefined)
+            updateFields.sprintId = updates.sprintId;
+        if (updates.estimate !== undefined)
+            updateFields.estimate = updates.estimate;
+        if (updates.labels !== undefined)
+            updateFields.labels = updates.labels;
+        // Handle epicKey -> parentId conversion
+        if (updates.epicKey !== undefined) {
+            if (updates.epicKey === null) {
+                updateFields.parentId = null;
+            }
+            else {
+                // Look up the Epic to get its ID
+                const epic = await client.getIssue(orgSlug, projectKey, updates.epicKey);
+                if (epic.type !== 'EPIC') {
+                    return JSON.stringify({
+                        success: false,
+                        error: `Issue ${updates.epicKey} is not an Epic (type: ${epic.type})`,
+                    });
+                }
+                updateFields.parentId = epic.id;
+            }
+        }
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_update_issue', {
+                orgSlug,
+                projectKey,
+                issueKey,
+                updates: Object.keys(updateFields),
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const issue = await client.updateIssue(orgSlug, projectKey, issueKey, updateFields);
+        // Check if status was changed and get column instructions
+        let columnInstructions = null;
+        if (updates.statusId !== undefined) {
+            columnInstructions = await getColumnInstructionsForStatus(orgSlug, projectKey, updates.statusId);
+        }
+        const response = {
+            success: true,
+            message: `Updated issue ${issue.key}`,
+            issue: {
+                key: issue.key,
+                summary: issue.summary,
+                type: issue.type,
+                status: issue.status,
+                priority: issue.priority,
+                assignee: issue.assignee,
+            },
+        };
+        // Add column instructions if they exist
+        if (columnInstructions) {
+            response.columnInstructions = columnInstructions;
+        }
+        return JSON.stringify(response);
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to update issue: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+// ============================================
+// Delete Issue (Soft)
+// ============================================
+export const deleteIssueToolName = 'llama_delete_issue';
+export const deleteIssueToolDescription = `Soft-delete an issue. The issue can be restored later if needed.
+Use with caution - this action removes the issue from views.
+Returns the number of subtasks that were also deleted.
+Uses session defaults if orgSlug/projectKey not provided.`;
+export const deleteIssueToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    issueKey: z.string().describe('Issue key to delete'),
+});
+export async function executeDeleteIssue(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const client = getApiClient();
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_delete_issue', {
+                orgSlug,
+                projectKey,
+                issueKey: input.issueKey,
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const result = await client.deleteIssue(orgSlug, projectKey, input.issueKey);
+        return JSON.stringify({
+            success: true,
+            message: `Deleted issue ${input.issueKey}`,
+            subtasksDeleted: result.subtasksDeleted,
+            impact: result.subtasksDeleted > 0
+                ? `${result.subtasksDeleted} subtask${result.subtasksDeleted === 1 ? '' : 's'} also deleted`
+                : 'No subtasks were affected',
+        });
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to delete issue: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+// ============================================
+// Batch Create Issues
+// ============================================
+export const batchCreateIssuesToolName = 'llama_batch_create_issues';
+export const batchCreateIssuesToolDescription = `Create multiple issues in one call (max 20).
+Returns individual success/failure for each issue.
+Uses session defaults if orgSlug/projectKey not provided.
+
+**IMPORTANT: SUBTASK type REQUIRES parentKey** - When creating subtasks, you must provide the parentKey field.
+
+Example:
+  issues: [
+    { summary: "Issue 1", type: "TASK" },
+    { summary: "Issue 2", type: "BUG", priority: "HIGH" },
+    { summary: "Subtask 1", type: "SUBTASK", parentKey: "PROJ-1" }
+  ]`;
+export const batchCreateIssuesToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    issues: z
+        .array(z.object({
+        summary: z.string().describe('Issue title/summary'),
+        type: z.enum(['EPIC', 'STORY', 'TASK', 'BUG', 'SUBTASK']).describe('Issue type'),
+        description: z.string().optional().nullable().describe('Description (markdown)'),
+        priority: z
+            .enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'TRIVIAL'])
+            .optional()
+            .describe('Priority (default: MEDIUM)'),
+        assigneeId: z.string().optional().nullable().describe('Assignee user ID'),
+        sprintId: z.string().optional().nullable().describe('Sprint ID'),
+        estimate: z.number().optional().nullable().describe('Story points'),
+        labels: z.array(z.string()).optional().describe('Labels'),
+        epicKey: z.string().optional().nullable().describe('Epic key to link to (for STORY, TASK, BUG)'),
+        parentKey: z.string().optional().nullable().describe('Parent issue key - REQUIRED for SUBTASK type'),
+    }))
+        .min(1)
+        .max(20)
+        .describe('Issues to create (max 20)'),
+});
+export async function executeBatchCreateIssues(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const client = getApiClient();
+        // Validate SUBTASK issues have parentKey
+        const subtasksWithoutParent = input.issues.filter((i) => i.type === 'SUBTASK' && !i.parentKey);
+        if (subtasksWithoutParent.length > 0) {
+            return JSON.stringify({
+                success: false,
+                error: `SUBTASK type requires parentKey. The following issues are missing parentKey: ${subtasksWithoutParent.map((i) => i.summary).join(', ')}`,
+            });
+        }
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_batch_create_issues', {
+                orgSlug,
+                projectKey,
+                count: input.issues.length,
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const issues = input.issues.map((i) => ({
+            summary: i.summary,
+            type: i.type,
+            description: i.description,
+            priority: i.priority,
+            assigneeId: i.assigneeId,
+            sprintId: i.sprintId,
+            estimate: i.estimate,
+            labels: i.labels,
+            epicKey: i.epicKey,
+            parentKey: i.parentKey,
+        }));
+        const result = await client.batchCreateIssues(orgSlug, projectKey, issues);
+        return JSON.stringify({
+            success: true,
+            message: `Created ${result.succeeded} of ${result.total} issues`,
+            ...result,
+        });
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to batch create issues: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+// ============================================
+// Batch Update Status
+// ============================================
+export const batchUpdateStatusToolName = 'llama_batch_update_status';
+export const batchUpdateStatusToolDescription = `Move multiple issues to the same status in one call (max 50).
+Returns individual success/failure for each issue.
+Uses session defaults if orgSlug/projectKey not provided.
+
+First use llama_context to get valid status IDs.`;
+export const batchUpdateStatusToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    issueKeys: z
+        .array(z.string())
+        .min(1)
+        .max(50)
+        .describe('Issue keys to update (max 50)'),
+    statusId: z.string().describe('Target status ID (from llama_context)'),
+});
+export async function executeBatchUpdateStatus(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const client = getApiClient();
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_batch_update_status', {
+                orgSlug,
+                projectKey,
+                count: input.issueKeys.length,
+                statusId: input.statusId,
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const result = await client.batchUpdateStatus(orgSlug, projectKey, input.issueKeys, input.statusId);
+        return JSON.stringify({
+            success: true,
+            message: `Updated ${result.succeeded} of ${result.total} issues`,
+            ...result,
+        });
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to batch update status: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+// ============================================
+// Batch Update Issues
+// ============================================
+export const batchUpdateIssuesToolName = 'llama_batch_update_issues';
+export const batchUpdateIssuesToolDescription = `Update multiple issues with different field changes (max 50).
+Returns individual success/failure for each issue.
+Uses session defaults if orgSlug/projectKey not provided.
+
+Example:
+  updates: [
+    { issueKey: "PROJ-1", fields: { priority: "HIGH" } },
+    { issueKey: "PROJ-2", fields: { assigneeId: "user-id", estimate: 5 } }
+  ]`;
+export const batchUpdateIssuesToolSchema = z.object({
+    orgSlug: z
+        .string()
+        .optional()
+        .describe('Organization slug (uses session default if not provided)'),
+    projectKey: z
+        .string()
+        .optional()
+        .describe('Project key (uses session default if not provided)'),
+    updates: z
+        .array(z.object({
+        issueKey: z.string().describe('Issue key to update'),
+        fields: z.object({
+            summary: z.string().optional().describe('New summary'),
+            description: z.string().optional().nullable().describe('New description'),
+            priority: z
+                .enum(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW', 'TRIVIAL'])
+                .optional()
+                .describe('New priority'),
+            assigneeId: z.string().optional().nullable().describe('Assignee ID or null'),
+            sprintId: z.string().optional().nullable().describe('Sprint ID or null'),
+            estimate: z.number().optional().nullable().describe('Story points'),
+            labels: z.array(z.string()).optional().describe('Replace all labels'),
+        }),
+    }))
+        .min(1)
+        .max(50)
+        .describe('Updates to apply (max 50)'),
+});
+export async function executeBatchUpdateIssues(input) {
+    try {
+        const session = await getSessionDefaults();
+        const orgSlug = input.orgSlug ?? session?.orgSlug;
+        const projectKey = input.projectKey ?? session?.projectKey;
+        if (!orgSlug) {
+            return JSON.stringify({
+                success: false,
+                error: 'orgSlug is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        if (!projectKey) {
+            return JSON.stringify({
+                success: false,
+                error: 'projectKey is required. Either provide it or set session context with llama_set_context first.',
+            });
+        }
+        const client = getApiClient();
+        // Record tool call
+        try {
+            await client.recordToolCall('llama_batch_update_issues', {
+                orgSlug,
+                projectKey,
+                count: input.updates.length,
+            });
+        }
+        catch {
+            // Ignore recording errors
+        }
+        const updates = input.updates.map((u) => ({
+            issueKey: u.issueKey,
+            fields: {
+                summary: u.fields.summary,
+                description: u.fields.description,
+                priority: u.fields.priority,
+                assigneeId: u.fields.assigneeId,
+                sprintId: u.fields.sprintId,
+                estimate: u.fields.estimate,
+                labels: u.fields.labels,
+            },
+        }));
+        const result = await client.batchUpdateIssues(orgSlug, projectKey, updates);
+        return JSON.stringify({
+            success: true,
+            message: `Updated ${result.succeeded} of ${result.total} issues`,
+            ...result,
+        });
+    }
+    catch (error) {
+        if (error instanceof LlamaApiError) {
+            return JSON.stringify({
+                success: false,
+                error: `Failed to batch update issues: ${error.message}`,
+                statusCode: error.statusCode,
+            });
+        }
+        return JSON.stringify({
+            success: false,
+            error: error instanceof Error ? error.message : 'Unknown error',
+        });
+    }
+}
+//# sourceMappingURL=issues.js.map