@projora/mcp-server 1.0.0 → 1.2.0

package/README.md

@@ -4,18 +4,27 @@ A Model Context Protocol (MCP) server for [Projora](https://projora.app) task ma
 
 ## Features
 
+### Task Management
+- **create_task** - Create a new task in a project (specify project key, title, and optional details)
 - **start_task** - Start working on a task (sets status to "In Progress", adds comment, returns full context)
 - **complete_task** - Mark a task as done with an optional summary
 - **get_task** - Get a specific task by its key (e.g., "PRJ-123")
-- **list_projects** - List all projects
+- **update_task** - Update task fields (title, description, priority, assignee, due date)
+- **update_task_status** - Update task status
+
+### Task Lists
 - **list_tasks** - List tasks with optional filters (project, status, priority, assignee)
 - **my_tasks** - Get tasks assigned to you
 - **overdue_tasks** - Get all overdue tasks
 - **search_tasks** - Search for tasks and projects by keyword
-- **update_task** - Update task fields (title, description, priority, assignee, due date)
-- **update_task_status** - Update task status
+
+### Collaboration
 - **add_comment** - Add a comment to a task
 - **log_time** - Log time worked on a task
+- **link_branch** - Link a git branch or pull request to a task
+
+### Projects & Config
+- **list_projects** - List all projects
 - **get_project** - Get project details including linked GitHub repository
 - **get_config** - Get available statuses, priorities, and task types
 - **dashboard_stats** - Get dashboard statistics
@@ -82,6 +91,8 @@ Add to your OpenCode configuration (`opencode.json`):
 
 Once configured, use prompts like:
 
+- "Create a task in project PRJ: Fix the login button"
+- "Create a task in PRJ with title 'Add unit tests' and assign it to me"
 - "Start working on task PRJ-123"
 - "Show me my tasks"
 - "What are the overdue tasks?"
@@ -92,14 +103,18 @@ Once configured, use prompts like:
 
 ## Workflow Example
 
-1. **Start a task**: "Use projora to start working on task PRJ-123"
+1. **Create a task**: "Use projora to create a task in project PRJ: Implement user authentication"
+   - Task is created in the specified project
+   - Returns the task key (e.g., PRJ-123) for reference
+
+2. **Start the task**: "Use projora to start working on task PRJ-123"
    - Status automatically changes to "In Progress"
    - A comment is added noting work has started
    - You get the full task context including description, GitHub repo, and suggested branch name
 
-2. **Work on the task**: Make your changes, commit code, etc.
+3. **Work on the task**: Make your changes, commit code, etc.
 
-3. **Complete the task**: "Use projora to complete task PRJ-123 with summary: Implemented the new feature with tests"
+4. **Complete the task**: "Use projora to complete task PRJ-123 with summary: Implemented the new feature with tests"
    - Status changes to "Done"
    - A completion comment is added with your summary
 

package/build/index.js

@@ -471,13 +471,71 @@ async function addCommentToTask(taskId, body) {
     const result = await graphqlQuery(mutation, { taskId, body });
     return !!result?.createComment;
 }
+// Helper function to update task branch/PR info
+async function updateTaskBranchInfo(taskId, branchName, prUrl, prNumber) {
+    const input = {};
+    if (branchName !== undefined)
+        input.branchName = branchName;
+    if (prUrl !== undefined)
+        input.prUrl = prUrl;
+    if (prNumber !== undefined)
+        input.prNumber = prNumber;
+    if (Object.keys(input).length === 0)
+        return true;
+    const mutation = `
+    mutation UpdateTaskBranch($id: ID!, $input: UpdateTaskInput!) {
+      updateTask(id: $id, input: $input) {
+        id
+        branchName
+        prUrl
+        prNumber
+      }
+    }
+  `;
+    const result = await graphqlQuery(mutation, { id: taskId, input });
+    return !!result?.updateTask;
+}
+// Helper function to log time on a task
+async function logTimeOnTask(taskId, startedAt, endedAt, description) {
+    const mutation = `
+    mutation LogTime($taskId: ID!, $input: LogTimeInput!) {
+      logTime(taskId: $taskId, input: $input) {
+        id
+        durationMinutes
+        formattedDuration
+      }
+    }
+  `;
+    const result = await graphqlQuery(mutation, {
+        taskId,
+        input: {
+            description: description || null,
+            startedAt,
+            endedAt,
+        },
+    });
+    return result?.logTime || null;
+}
+// Helper to format duration in human-readable form
+function formatDuration(minutes) {
+    if (minutes < 60) {
+        return `${minutes} minute${minutes !== 1 ? 's' : ''}`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+    if (mins === 0) {
+        return `${hours} hour${hours !== 1 ? 's' : ''}`;
+    }
+    return `${hours} hour${hours !== 1 ? 's' : ''} ${mins} minute${mins !== 1 ? 's' : ''}`;
+}
 // 9. Start working on a task - get full context and set status to In Progress
 server.registerTool("start_task", {
-    description: "Start working on a task. This will: 1) Set the task status to 'In Progress', 2) Add a comment noting work has started, 3) Return comprehensive task details including description, comments, GitHub repo info, and suggested branch name.",
+    description: "Start working on a task. This will: 1) Set the task status to 'In Progress', 2) Set the branch name on the task (if provided), 3) Add a comment noting work has started, 4) Return comprehensive task details including description, comments, GitHub repo info, and suggested branch name.",
     inputSchema: {
         taskKey: z.string().describe("The task key (e.g., 'PRJ-123')"),
+        branchName: z.string().optional().describe("The git branch name being used for this task. If provided, it will be saved to the task for tracking."),
     },
-}, async ({ taskKey }) => {
+}, async ({ taskKey, branchName: providedBranchName }) => {
     const query = `
       query StartTask($taskKey: String!) {
         taskByKey(taskKey: $taskKey) {
@@ -544,9 +602,10 @@ server.registerTool("start_task", {
             }
         }
     }
-    // Add a comment noting that work has started
-    const timestamp = new Date().toISOString().split('T')[0];
-    await addCommentToTask(task.id, `Started working on this task via Claude Code on ${timestamp}`);
+    // Record the start time for time tracking
+    const startTime = new Date();
+    const startTimestamp = startTime.toISOString();
+    const dateStr = startTimestamp.split('T')[0];
     // Generate suggested branch name
     const slugifiedTitle = task.title
         .toLowerCase()
@@ -554,10 +613,24 @@ server.registerTool("start_task", {
         .replace(/^-|-$/g, '')
         .substring(0, 50);
     const suggestedBranch = `feature/${task.taskKey.toLowerCase()}-${slugifiedTitle}`;
+    // Use provided branch name or suggested one
+    const branchToUse = providedBranchName || suggestedBranch;
+    // Set the branch name on the task
+    let branchSetMessage = "";
+    if (providedBranchName) {
+        await updateTaskBranchInfo(task.id, providedBranchName);
+        branchSetMessage = `\n**Branch set:** \`${providedBranchName}\`\n`;
+    }
+    // Add a comment noting that work has started
+    const branchComment = providedBranchName ? ` on branch \`${providedBranchName}\`` : '';
+    await addCommentToTask(task.id, `Started working on this task via AI assistant on ${dateStr}${branchComment}`);
     let output = `# Task: ${task.taskKey} - ${task.title}\n`;
     if (statusUpdateMessage) {
         output += statusUpdateMessage;
     }
+    if (branchSetMessage) {
+        output += branchSetMessage;
+    }
     output += `\n`;
     output += `## Overview\n`;
     output += `- **Project**: ${project.name} (${project.key})\n`;
@@ -613,19 +686,22 @@ server.registerTool("start_task", {
         }
     }
     output += `\n---\n`;
-    output += `**Tip:** When you're done, use \`complete_task\` to mark this task as Done.\n`;
+    output += `**Started at:** ${startTimestamp}\n`;
+    output += `**Tip:** When you're done, use \`complete_task\` with \`startedAt: "${startTimestamp}"\` to automatically log time spent.\n`;
     return {
         content: [{ type: "text", text: output }],
     };
 });
-// 9b. Complete a task - mark as Done and add completion comment
+// 9b. Complete a task - mark as Done, log time, and add completion comment
 server.registerTool("complete_task", {
-    description: "Mark a task as complete/done. This will: 1) Set the task status to 'Done', 2) Add a comment with an optional summary of what was accomplished.",
+    description: "Mark a task as complete/done. This will: 1) Set the task status to 'Done', 2) Log the time spent (if startedAt is provided), 3) Set the PR URL (if provided), 4) Add a comment with the summary and time logged.",
     inputSchema: {
         taskKey: z.string().describe("The task key (e.g., 'PRJ-123')"),
-        summary: z.string().optional().describe("Optional summary of what was accomplished"),
+        summary: z.string().optional().describe("Summary of what was accomplished"),
+        startedAt: z.string().optional().describe("ISO timestamp of when work started (from start_task). Used to calculate and log time spent."),
+        prUrl: z.string().optional().describe("URL of the pull request created for this task"),
     },
-}, async ({ taskKey, summary }) => {
+}, async ({ taskKey, summary, startedAt, prUrl }) => {
     // Get the task
     const getTaskQuery = `
       query GetTaskId($taskKey: String!) {
@@ -645,6 +721,8 @@ server.registerTool("complete_task", {
     }
     const task = taskData.taskByKey;
     const previousStatus = task.status?.name || 'No status';
+    const endTime = new Date();
+    const endTimestamp = endTime.toISOString();
     // Find the "Done" status
     const doneStatus = await findStatusByName('done');
     if (!doneStatus) {
@@ -659,9 +737,47 @@ server.registerTool("complete_task", {
             content: [{ type: "text", text: `Failed to update task status. Check your permissions.` }],
         };
     }
+    // Log time if startedAt was provided
+    let timeLogMessage = "";
+    let durationMinutes = 0;
+    if (startedAt) {
+        try {
+            const startDate = new Date(startedAt);
+            durationMinutes = Math.round((endTime.getTime() - startDate.getTime()) / 60000);
+            if (durationMinutes > 0) {
+                // Format timestamps for the API (YYYY-MM-DD HH:MM:SS)
+                const formatForApi = (date) => {
+                    return date.toISOString().replace('T', ' ').substring(0, 19);
+                };
+                const timeLog = await logTimeOnTask(task.id, formatForApi(startDate), formatForApi(endTime), `AI-assisted work session${summary ? `: ${summary.substring(0, 100)}` : ''}`);
+                if (timeLog) {
+                    timeLogMessage = `Time logged: ${timeLog.formattedDuration}`;
+                }
+            }
+        }
+        catch (e) {
+            // If parsing fails, just skip time logging
+            console.error("Failed to parse startedAt timestamp:", e);
+        }
+    }
+    // Set PR URL if provided
+    let prSetMessage = "";
+    if (prUrl) {
+        // Extract PR number from URL if possible (e.g., https://github.com/owner/repo/pull/123)
+        const prMatch = prUrl.match(/\/pull\/(\d+)/);
+        const prNumber = prMatch ? parseInt(prMatch[1], 10) : undefined;
+        await updateTaskBranchInfo(task.id, undefined, prUrl, prNumber);
+        prSetMessage = `PR linked: ${prUrl}\n`;
+    }
     // Add completion comment
-    const timestamp = new Date().toISOString().split('T')[0];
-    let commentBody = `Task completed via Claude Code on ${timestamp}`;
+    const dateStr = endTimestamp.split('T')[0];
+    let commentBody = `Task completed via AI assistant on ${dateStr}`;
+    if (durationMinutes > 0) {
+        commentBody += `\n\n**Time spent:** ${formatDuration(durationMinutes)}`;
+    }
+    if (prUrl) {
+        commentBody += `\n\n**Pull Request:** ${prUrl}`;
+    }
     if (summary) {
         commentBody += `\n\n**Summary:**\n${summary}`;
     }
@@ -669,6 +785,12 @@ server.registerTool("complete_task", {
     let output = `# Task Completed: ${task.taskKey}\n\n`;
     output += `**${task.title}**\n\n`;
     output += `Status updated: ${previousStatus} → ${updated.status.name}\n`;
+    if (timeLogMessage) {
+        output += `${timeLogMessage}\n`;
+    }
+    if (prSetMessage) {
+        output += `${prSetMessage}`;
+    }
     if (summary) {
         output += `\nSummary added to task comments.\n`;
     }
@@ -817,6 +939,59 @@ server.registerTool("log_time", {
         content: [{ type: "text", text: `Logged ${result.logTime.formattedDuration} on ${taskKey}${description ? `: ${description}` : ''}` }],
     };
 });
+// 12b. Link branch or PR to a task
+server.registerTool("link_branch", {
+    description: "Link a git branch or pull request to a task. This helps track which branch/PR is associated with the task.",
+    inputSchema: {
+        taskKey: z.string().describe("The task key (e.g., 'PRJ-123')"),
+        branchName: z.string().optional().describe("The git branch name"),
+        prUrl: z.string().optional().describe("URL of the pull request"),
+    },
+}, async ({ taskKey, branchName, prUrl }) => {
+    if (!branchName && !prUrl) {
+        return {
+            content: [{ type: "text", text: `Please provide either a branch name or PR URL.` }],
+        };
+    }
+    // First get the task ID
+    const getTaskQuery = `
+      query GetTaskId($taskKey: String!) {
+        taskByKey(taskKey: $taskKey) {
+          id
+          branchName
+          prUrl
+        }
+      }
+    `;
+    const taskData = await graphqlQuery(getTaskQuery, { taskKey });
+    if (!taskData || !taskData.taskByKey) {
+        return {
+            content: [{ type: "text", text: `Task '${taskKey}' not found.` }],
+        };
+    }
+    // Extract PR number from URL if possible
+    let prNumber;
+    if (prUrl) {
+        const prMatch = prUrl.match(/\/pull\/(\d+)/);
+        prNumber = prMatch ? parseInt(prMatch[1], 10) : undefined;
+    }
+    const success = await updateTaskBranchInfo(taskData.taskByKey.id, branchName, prUrl, prNumber);
+    if (!success) {
+        return {
+            content: [{ type: "text", text: `Failed to update task. Check your permissions.` }],
+        };
+    }
+    let output = `Updated ${taskKey}:\n`;
+    if (branchName) {
+        output += `  Branch: ${branchName}\n`;
+    }
+    if (prUrl) {
+        output += `  PR: ${prUrl}\n`;
+    }
+    return {
+        content: [{ type: "text", text: output }],
+    };
+});
 // 13. Update task (general)
 server.registerTool("update_task", {
     description: "Update task fields (title, description, priority, assignee, due date, estimate)",
@@ -891,7 +1066,167 @@ server.registerTool("update_task", {
         content: [{ type: "text", text: `Updated ${result.updateTask.taskKey}: ${updatedFields}` }],
     };
 });
-// 14. Get project with GitHub info
+// 14. Create a new task
+server.registerTool("create_task", {
+    description: "Create a new task in a project. You can specify the project by key and optionally the task list name, or provide IDs directly. Returns the created task details.",
+    inputSchema: {
+        projectKey: z.string().optional().describe("The project key (e.g., 'PRJ'). Either projectKey or taskListId is required."),
+        taskListName: z.string().optional().describe("Name of the task list to add the task to (e.g., 'To Do', 'Backlog'). If not provided, uses the first task list."),
+        taskListId: z.string().optional().describe("The task list ID. If provided, projectKey and taskListName are ignored."),
+        title: z.string().describe("The task title (required)"),
+        description: z.string().optional().describe("Task description (supports markdown)"),
+        statusId: z.string().optional().describe("Status ID (use get_config to see available statuses)"),
+        priorityId: z.string().optional().describe("Priority ID (use get_config to see available priorities)"),
+        taskTypeId: z.string().optional().describe("Task type ID (use get_config to see available task types)"),
+        assigneeId: z.string().optional().describe("User ID to assign the task to"),
+        dueDate: z.string().optional().describe("Due date in YYYY-MM-DD format"),
+        startDate: z.string().optional().describe("Start date in YYYY-MM-DD format"),
+        estimatedHours: z.number().optional().describe("Estimated hours to complete the task"),
+    },
+}, async ({ projectKey, taskListName, taskListId, title, description, statusId, priorityId, taskTypeId, assigneeId, dueDate, startDate, estimatedHours }) => {
+    let resolvedTaskListId = taskListId;
+    let projectName = "";
+    // If taskListId is not provided, we need to look it up from projectKey
+    if (!resolvedTaskListId) {
+        if (!projectKey) {
+            return {
+                content: [{ type: "text", text: "Either projectKey or taskListId is required to create a task." }],
+            };
+        }
+        // Get project and its task lists
+        const projectQuery = `
+        query GetProjectWithTaskLists {
+          projects {
+            id
+            name
+            key
+            taskLists {
+              id
+              name
+              sortOrder
+            }
+          }
+        }
+      `;
+        const projectData = await graphqlQuery(projectQuery);
+        if (!projectData) {
+            return {
+                content: [{ type: "text", text: "Failed to fetch projects. Check your authentication token." }],
+            };
+        }
+        const project = projectData.projects.find(p => p.key.toLowerCase() === projectKey.toLowerCase());
+        if (!project) {
+            const availableProjects = projectData.projects.map(p => p.key).join(", ");
+            return {
+                content: [{ type: "text", text: `Project '${projectKey}' not found. Available projects: ${availableProjects}` }],
+            };
+        }
+        projectName = project.name;
+        if (project.taskLists.length === 0) {
+            return {
+                content: [{ type: "text", text: `Project '${projectKey}' has no task lists. Please create a task list first.` }],
+            };
+        }
+        // Find the task list by name or use the first one
+        if (taskListName) {
+            const taskList = project.taskLists.find(tl => tl.name.toLowerCase() === taskListName.toLowerCase());
+            if (!taskList) {
+                const availableLists = project.taskLists.map(tl => tl.name).join(", ");
+                return {
+                    content: [{ type: "text", text: `Task list '${taskListName}' not found in project '${projectKey}'. Available lists: ${availableLists}` }],
+                };
+            }
+            resolvedTaskListId = taskList.id;
+        }
+        else {
+            // Use the first task list (sorted by sortOrder)
+            const sortedLists = [...project.taskLists].sort((a, b) => a.sortOrder - b.sortOrder);
+            resolvedTaskListId = sortedLists[0].id;
+        }
+    }
+    // Build the input object
+    const input = {
+        taskListId: resolvedTaskListId,
+        title,
+    };
+    if (description !== undefined)
+        input.description = description;
+    if (statusId !== undefined)
+        input.statusId = statusId;
+    if (priorityId !== undefined)
+        input.priorityId = priorityId;
+    if (taskTypeId !== undefined)
+        input.taskTypeId = taskTypeId;
+    if (assigneeId !== undefined)
+        input.assigneeId = assigneeId;
+    if (dueDate !== undefined)
+        input.dueDate = dueDate;
+    if (startDate !== undefined)
+        input.startDate = startDate;
+    if (estimatedHours !== undefined)
+        input.estimatedHours = estimatedHours;
+    // Create the task
+    const mutation = `
+      mutation CreateTask($input: CreateTaskInput!) {
+        createTask(input: $input) {
+          id
+          taskKey
+          title
+          description
+          dueDate
+          startDate
+          estimatedHours
+          status { id name }
+          priority { id name }
+          taskType { id name }
+          assignee { id name }
+          project { id name key }
+          taskList { id name }
+          createdAt
+        }
+      }
+    `;
+    const result = await graphqlQuery(mutation, { input });
+    if (!result || !result.createTask) {
+        return {
+            content: [{ type: "text", text: "Failed to create task. Check your permissions and input values." }],
+        };
+    }
+    const task = result.createTask;
+    let output = `# Task Created: ${task.taskKey}\n\n`;
+    output += `**${task.title}**\n\n`;
+    output += `- **Project**: ${task.project.name} (${task.project.key})\n`;
+    output += `- **List**: ${task.taskList.name}\n`;
+    output += `- **Status**: ${task.status?.name || 'Default'}\n`;
+    if (task.priority) {
+        output += `- **Priority**: ${task.priority.name}\n`;
+    }
+    if (task.taskType) {
+        output += `- **Type**: ${task.taskType.name}\n`;
+    }
+    if (task.assignee) {
+        output += `- **Assignee**: ${task.assignee.name}\n`;
+    }
+    if (task.dueDate) {
+        output += `- **Due Date**: ${task.dueDate}\n`;
+    }
+    if (task.startDate) {
+        output += `- **Start Date**: ${task.startDate}\n`;
+    }
+    if (task.estimatedHours) {
+        output += `- **Estimate**: ${task.estimatedHours} hours\n`;
+    }
+    if (task.description) {
+        output += `\n## Description\n${task.description}\n`;
+    }
+    output += `\n---\n`;
+    output += `Created at: ${task.createdAt}\n`;
+    output += `\nYou can now use \`start_task\` with taskKey "${task.taskKey}" to begin working on it.`;
+    return {
+        content: [{ type: "text", text: output }],
+    };
+});
+// 15. Get project with GitHub info
 server.registerTool("get_project", {
     description: "Get project details including linked GitHub repository",
     inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projora/mcp-server",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "MCP server for Projora task management - integrate with Claude Code and OpenCode to manage tasks, update statuses, and track work",
   "type": "module",
   "bin": {