@rallycry/conveyor-mcp 3.3.0 → 3.5.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   ConveyorConnection
-} from "./chunk-OAHSTMYM.js";
+} from "./chunk-Z566YAS7.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -9,29 +9,43 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/tools/project.ts
+import { z } from "zod";
 function registerProjectTools(server2, conn2) {
   server2.tool(
-    "get_project_summary",
-    "Get overall project status: task counts by status, active builds, repo info",
+    "list_projects",
+    "List Conveyor projects available to this MCP token's user. Use a returned project id as projectId on other tools when no default project is configured or when targeting a different project.",
     {},
     async () => {
-      const summary = await conn2.getProjectSummary();
+      const projects = await conn2.listProjects();
+      return { content: [{ type: "text", text: JSON.stringify(projects, null, 2) }] };
+    }
+  );
+  server2.tool(
+    "get_project_summary",
+    "Get overall project status: task counts by status, active builds, repo info. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    {
+      projectId: z.string().optional().describe("Target Conveyor project ID")
+    },
+    async (params) => {
+      const summary = await conn2.getProjectSummary(params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
     }
   );
   server2.tool(
     "list_project_members",
-    "List project members with user ID, name, email, and access level \u2014 use to resolve a person's name or email to a user ID for task assignment or review",
-    {},
-    async () => {
-      const members = await conn2.listProjectMembers();
+    "List project members with user ID, name, email, and access level \u2014 use to resolve a person's name or email to a user ID for task assignment or review. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    {
+      projectId: z.string().optional().describe("Target Conveyor project ID")
+    },
+    async (params) => {
+      const members = await conn2.listProjectMembers(params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(members, null, 2) }] };
     }
   );
 }
 
 // src/tools/tasks.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 var CLI_EVENT_FORMATTERS = {
   thinking: (data) => String(data.message ?? ""),
   tool_use: (data) => `${data.tool}: ${String(data.input ?? "").slice(0, 1e3)}`,
@@ -69,12 +83,13 @@ var STATUS_ENUM = [
 function registerListTasks(server2, conn2) {
   server2.tool(
     "list_tasks",
-    "List project tasks, optionally filtered by status or assignment (a specific assignee, or unassigned tasks). Returns summaries \u2014 plan omitted, description truncated; use get_task for full details.",
+    "List project tasks, optionally filtered by status or assignment (a specific assignee, or unassigned tasks). Pass projectId to target a specific project; otherwise the configured default project is used. Returns summaries \u2014 plan omitted, description truncated; use get_task for full details.",
     {
-      status: z.enum(STATUS_ENUM).optional().describe("Filter by task status"),
-      assigneeId: z.string().optional().describe("Filter by assigned user ID"),
-      unassigned: z.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
-      limit: z.number().optional().describe("Max tasks to return (default 50)")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      status: z2.enum(STATUS_ENUM).optional().describe("Filter by task status"),
+      assigneeId: z2.string().optional().describe("Filter by assigned user ID"),
+      unassigned: z2.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
+      limit: z2.number().optional().describe("Max tasks to return (default 50)")
     },
     async (params) => {
       const tasks = await conn2.listTasks(params);
@@ -87,12 +102,27 @@ function registerListTasks(server2, conn2) {
 function registerGetTask(server2, conn2) {
   server2.tool(
     "get_task",
-    "Get full task details including plan, chat history, PR info, subtasks, and build status",
+    "Get full task details including plan, chat history, PR info, subtasks, and build status. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    {
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID or slug (the value in a card URL, /cards/<slug>)")
+    },
+    async (params) => {
+      const task = await conn2.getTask(params.taskId, params.projectId);
+      return { content: [{ type: "text", text: JSON.stringify(task, null, 2) }] };
+    }
+  );
+}
+function registerGetCardBySlug(server2, conn2) {
+  server2.tool(
+    "get_card_by_slug",
+    "Get full card details by the slug from a card URL (/cards/<slug>) instead of a task ID. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z.string().describe("The task ID or slug (the value in a card URL, /cards/<slug>)")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      slug: z2.string().describe("The card slug from a Conveyor card URL, e.g. 'ship-it'")
     },
     async (params) => {
-      const task = await conn2.getTask(params.taskId);
+      const task = await conn2.getCardBySlug(params.slug, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(task, null, 2) }] };
     }
   );
@@ -100,12 +130,13 @@ function registerGetTask(server2, conn2) {
 function registerCreateTask(server2, conn2) {
   server2.tool(
     "create_task",
-    "Create a new task with title, description, and optional plan. Icon, story points, and agent assignment are auto-filled when a task is created in (or later moved to) a status beyond Planning \u2014 don't spend turns on them.",
+    "Create a new task with title, description, and optional plan. Pass projectId to target a specific project; otherwise the configured default project is used. Icon, story points, and agent assignment are auto-filled when a task is created in (or later moved to) a status beyond Planning \u2014 don't spend turns on them.",
     {
-      title: z.string().describe("Task title"),
-      description: z.string().optional().describe("Task description"),
-      plan: z.string().optional().describe("Task implementation plan (markdown)"),
-      status: z.enum(["Planning", "Open"]).optional().describe("Initial status (default: Planning)")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      title: z2.string().describe("Task title"),
+      description: z2.string().optional().describe("Task description"),
+      plan: z2.string().optional().describe("Task implementation plan (markdown)"),
+      status: z2.enum(["Planning", "Open"]).optional().describe("Initial status (default: Planning)")
     },
     async (params) => {
       const task = await conn2.createTask(params);
@@ -118,14 +149,15 @@ function registerCreateTask(server2, conn2) {
 function registerUpdateTask(server2, conn2) {
   server2.tool(
     "update_task",
-    "Update task fields: title, description, plan, status, or assignment. Moving a task beyond Planning auto-fills any missing icon, story points, and agent assignment \u2014 don't spend turns on them.",
+    "Update task fields: title, description, plan, status, or assignment. Pass projectId to target a specific project; otherwise the configured default project is used. Moving a task beyond Planning auto-fills any missing icon, story points, and agent assignment \u2014 don't spend turns on them.",
     {
-      taskId: z.string().describe("The task ID"),
-      title: z.string().optional().describe("New title"),
-      description: z.string().optional().describe("New description"),
-      plan: z.string().optional().describe("New plan (markdown)"),
-      status: z.enum(STATUS_ENUM).optional().describe("New status"),
-      assignedUserId: z.string().nullable().optional().describe("User ID to assign, or null")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID"),
+      title: z2.string().optional().describe("New title"),
+      description: z2.string().optional().describe("New description"),
+      plan: z2.string().optional().describe("New plan (markdown)"),
+      status: z2.enum(STATUS_ENUM).optional().describe("New status"),
+      assignedUserId: z2.string().nullable().optional().describe("User ID to assign, or null")
     },
     async (params) => {
       const result = await conn2.updateTask(params);
@@ -138,25 +170,27 @@ function registerUpdateTask(server2, conn2) {
 function registerChatTools(server2, conn2) {
   server2.tool(
     "read_task_chat",
-    "Read messages from a task's chat. For agent execution logs use get_task_logs.",
+    "Read messages from a task's chat. Pass projectId to target a specific project; otherwise the configured default project is used. For agent execution logs use get_task_logs.",
     {
-      taskId: z.string().describe("The task ID"),
-      limit: z.number().optional().describe("Max messages to return (default 50)")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID"),
+      limit: z2.number().optional().describe("Max messages to return (default 50)")
     },
     async (params) => {
-      const messages = await conn2.getTaskChat(params.taskId, params.limit);
+      const messages = await conn2.getTaskChat(params.taskId, params.limit, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(messages, null, 2) }] };
     }
   );
   server2.tool(
     "post_to_chat",
-    "Post a message to a task's chat",
+    "Post a message to a task's chat. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z.string().describe("The task ID"),
-      content: z.string().describe("Message content")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID"),
+      content: z2.string().describe("Message content")
     },
     async (params) => {
-      await conn2.postToTaskChat(params.taskId, params.content);
+      await conn2.postToTaskChat(params.taskId, params.content, params.projectId);
       return { content: [{ type: "text", text: "Message posted" }] };
     }
   );
@@ -164,17 +198,18 @@ function registerChatTools(server2, conn2) {
 function registerGetTaskCli(server2, conn2) {
   server2.tool(
     "get_task_logs",
-    "Read CLI execution logs from a task. Returns agent reasoning, tool calls, setup output, and other execution events. For human chat use read_task_chat.",
+    "Read CLI execution logs from a task. Pass projectId to target a specific project; otherwise the configured default project is used. Returns agent reasoning, tool calls, setup output, and other execution events. For human chat use read_task_chat.",
     {
-      taskId: z.string().describe("The task ID or slug"),
-      source: z.enum(["agent", "application"]).optional().describe(
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID or slug"),
+      source: z2.enum(["agent", "application"]).optional().describe(
         "Filter by log source: 'agent' for reasoning/tool calls, 'application' for setup/dev-server output"
       ),
-      limit: z.number().optional().describe("Max entries to return (default 50, max 500)")
+      limit: z2.number().optional().describe("Max entries to return (default 50, max 500)")
     },
-    async ({ taskId, source, limit }) => {
+    async ({ taskId, source, limit, projectId: projectId2 }) => {
       const effectiveLimit = Math.min(limit ?? 50, 500);
-      const logs = await conn2.getTaskCli(taskId, effectiveLimit, source);
+      const logs = await conn2.getTaskCli(taskId, effectiveLimit, source, projectId2);
       const formatted = logs.map((log) => {
         return `[${log.timestamp}] [${log.type}] ${formatCliEventSummary(log.type, log.data)}`;
       }).join("\n");
@@ -187,14 +222,15 @@ function registerGetTaskCli(server2, conn2) {
 function registerSearchTasks(server2, conn2) {
   server2.tool(
     "search_tasks",
-    "Search tasks by tag name, text query, status, and/or assignment. Use tag names like 'agent-runner', not IDs. Returns summaries \u2014 plan omitted, description truncated; use get_task for full details.",
+    "Search tasks by tag name, text query, status, and/or assignment. Pass projectId to target a specific project; otherwise the configured default project is used. Use tag names like 'agent-runner', not IDs. Returns summaries \u2014 plan omitted, description truncated; use get_task for full details.",
     {
-      tagNames: z.array(z.string()).optional().describe('Tag names to filter by (e.g., ["agent-runner", "chat"])'),
-      searchQuery: z.string().optional().describe("Text search on title and description"),
-      statusFilters: z.array(z.enum(STATUS_ENUM)).optional().describe("Filter by one or more statuses"),
-      assigneeId: z.string().optional().describe("Filter by assigned user ID"),
-      unassigned: z.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
-      limit: z.number().optional().describe("Max results to return (default 20)")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      tagNames: z2.array(z2.string()).optional().describe('Tag names to filter by (e.g., ["agent-runner", "chat"])'),
+      searchQuery: z2.string().optional().describe("Text search on title and description"),
+      statusFilters: z2.array(z2.enum(STATUS_ENUM)).optional().describe("Filter by one or more statuses"),
+      assigneeId: z2.string().optional().describe("Filter by assigned user ID"),
+      unassigned: z2.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
+      limit: z2.number().optional().describe("Max results to return (default 20)")
     },
     async (params) => {
       const tasks = await conn2.searchTasks(params);
@@ -207,10 +243,12 @@ function registerSearchTasks(server2, conn2) {
 function registerListTags(server2, conn2) {
   server2.tool(
     "list_tags",
-    "List all project tags with their names, IDs, and colors",
-    {},
-    async () => {
-      const tags = await conn2.listTags();
+    "List all project tags with their names, IDs, and colors. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    {
+      projectId: z2.string().optional().describe("Target Conveyor project ID")
+    },
+    async (params) => {
+      const tags = await conn2.listTags(params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(tags, null, 2) }] };
     }
   );
@@ -218,12 +256,13 @@ function registerListTags(server2, conn2) {
 function registerReviewTools(server2, conn2) {
   server2.tool(
     "approve_task",
-    "Move a task forward in the review flow (ReviewPR -> ReviewDev, or -> Complete)",
+    "Move a task forward in the review flow (ReviewPR -> ReviewDev, or -> Complete). Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z.string().describe("The task ID")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID")
     },
     async (params) => {
-      const result = await conn2.approveTask(params.taskId);
+      const result = await conn2.approveTask(params.taskId, params.projectId);
       return {
         content: [{ type: "text", text: `Task approved, new status: ${result.status}` }]
       };
@@ -231,12 +270,13 @@ function registerReviewTools(server2, conn2) {
   );
   server2.tool(
     "approve_and_merge_pr",
-    "Approve and merge a child task's pull request. Only succeeds if all CI/CD checks are passing. The child task must be in ReviewPR status with a PR.",
+    "Approve and merge a child task's pull request. Pass projectId to target a specific project; otherwise the configured default project is used. Only succeeds if all CI/CD checks are passing. The child task must be in ReviewPR status with a PR.",
     {
-      childTaskId: z.string().describe("The child task ID whose PR should be approved and merged")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      childTaskId: z2.string().describe("The child task ID whose PR should be approved and merged")
     },
     async (params) => {
-      const result = await conn2.approveAndMergePR(params.childTaskId);
+      const result = await conn2.approveAndMergePR(params.childTaskId, params.projectId);
       return {
         content: [
           {
@@ -249,13 +289,14 @@ function registerReviewTools(server2, conn2) {
   );
   server2.tool(
     "request_changes",
-    "Post feedback and send task back to InProgress for more work",
+    "Post feedback and send task back to InProgress for more work. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z.string().describe("The task ID"),
-      feedback: z.string().describe("Feedback message describing requested changes")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID"),
+      feedback: z2.string().describe("Feedback message describing requested changes")
     },
     async (params) => {
-      await conn2.requestChanges(params.taskId, params.feedback);
+      await conn2.requestChanges(params.taskId, params.feedback, params.projectId);
       return { content: [{ type: "text", text: "Changes requested, task moved to InProgress" }] };
     }
   );
@@ -267,10 +308,11 @@ function formatReviewerList(reviewers) {
 function registerReviewerTools(server2, conn2) {
   server2.tool(
     "add_reviewer",
-    "Add a project member as a reviewer on a task. Idempotent \u2014 adding an existing reviewer is a no-op.",
+    "Add a project member as a reviewer on a task. Pass projectId to target a specific project; otherwise the configured default project is used. Idempotent \u2014 adding an existing reviewer is a no-op.",
     {
-      taskId: z.string().describe("The task ID or slug"),
-      userId: z.string().describe("User ID of the reviewer (use list_project_members to resolve a name or email)")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID or slug"),
+      userId: z2.string().describe("User ID of the reviewer (use list_project_members to resolve a name or email)")
     },
     async (params) => {
       const result = await conn2.addReviewer(params);
@@ -286,10 +328,11 @@ function registerReviewerTools(server2, conn2) {
   );
   server2.tool(
     "remove_reviewer",
-    "Remove a reviewer from a task. Idempotent \u2014 removing a non-reviewer is a no-op.",
+    "Remove a reviewer from a task. Pass projectId to target a specific project; otherwise the configured default project is used. Idempotent \u2014 removing a non-reviewer is a no-op.",
     {
-      taskId: z.string().describe("The task ID or slug"),
-      userId: z.string().describe("User ID of the reviewer to remove")
+      projectId: z2.string().optional().describe("Target Conveyor project ID"),
+      taskId: z2.string().describe("The task ID or slug"),
+      userId: z2.string().describe("User ID of the reviewer to remove")
     },
     async (params) => {
       const result = await conn2.removeReviewer(params);
@@ -307,6 +350,7 @@ function registerReviewerTools(server2, conn2) {
 function registerTaskTools(server2, conn2) {
   registerListTasks(server2, conn2);
   registerGetTask(server2, conn2);
+  registerGetCardBySlug(server2, conn2);
   registerCreateTask(server2, conn2);
   registerUpdateTask(server2, conn2);
   registerChatTools(server2, conn2);
@@ -318,51 +362,55 @@ function registerTaskTools(server2, conn2) {
 }
 
 // src/tools/builds.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 function registerBuildTools(server2, conn2) {
   server2.tool(
     "start_task",
-    "Start a cloud build (codespace) for a task",
+    "Start a cloud build (codespace) for a task. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z2.string().describe("The task ID")
+      projectId: z3.string().optional().describe("Target Conveyor project ID"),
+      taskId: z3.string().describe("The task ID")
     },
     async (params) => {
-      const result = await conn2.startBuild(params.taskId);
+      const result = await conn2.startBuild(params.taskId, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
   server2.tool(
     "stop_task",
-    "Stop a running cloud build for a task",
+    "Stop a running cloud build for a task. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z2.string().describe("The task ID")
+      projectId: z3.string().optional().describe("Target Conveyor project ID"),
+      taskId: z3.string().describe("The task ID")
     },
     async (params) => {
-      const result = await conn2.stopBuild(params.taskId);
+      const result = await conn2.stopBuild(params.taskId, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
   server2.tool(
     "create_release",
-    "Create a release for the project \u2014 the same flow as the Release button in the web UI. Creates a release task with a release/YYYY.MM.N branch and a PR from the dev branch to the default branch. Omit taskIds to release ALL cards currently in Review (Dev); pass a subset to cherry-pick \u2014 a cloud build agent then cherry-picks those changes and resolves conflicts. Fails if a release is already in progress or no cards are in Review (Dev).",
+    "Create a release for the project \u2014 the same flow as the Release button in the web UI. Pass projectId to target a specific project; otherwise the configured default project is used. Creates a release task with a release/YYYY.MM.N branch and a PR from the dev branch to the default branch. Omit taskIds to release ALL cards currently in Review (Dev); pass a subset to cherry-pick \u2014 a cloud build agent then cherry-picks those changes and resolves conflicts. Fails if a release is already in progress or no cards are in Review (Dev).",
     {
-      taskIds: z2.array(z2.string()).optional().describe(
+      projectId: z3.string().optional().describe("Target Conveyor project ID"),
+      taskIds: z3.array(z3.string()).optional().describe(
         "Task IDs in Review (Dev) to cherry-pick into the release. Omit to release all of them."
       )
     },
     async (params) => {
-      const result = await conn2.createRelease(params.taskIds);
+      const result = await conn2.createRelease(params.taskIds, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
   );
   server2.tool(
     "get_build_status",
-    "Check codespace and agent status for a task",
+    "Check codespace and agent status for a task. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z2.string().describe("The task ID")
+      projectId: z3.string().optional().describe("Target Conveyor project ID"),
+      taskId: z3.string().describe("The task ID")
     },
     async (params) => {
-      const status = await conn2.getBuildStatus(params.taskId);
+      const status = await conn2.getBuildStatus(params.taskId, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(status, null, 2) }] };
     }
   );
@@ -371,7 +419,7 @@ function registerBuildTools(server2, conn2) {
 // src/tools/attachments.ts
 import { readFile, stat } from "fs/promises";
 import { basename, extname } from "path";
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024;
 var MIME_BY_EXT = {
   ".png": "image/png",
@@ -406,12 +454,13 @@ function inferMimeType(filePath, override) {
 function registerListTaskFiles(server2, conn2) {
   server2.tool(
     "list_task_files",
-    "List all files attached to a task with metadata (no contents \u2014 fast and small). Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
+    "List all files attached to a task with metadata (no contents \u2014 fast and small). Pass projectId to target a specific project; otherwise the configured default project is used. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
     {
-      taskId: z3.string().describe("The task ID or slug")
+      projectId: z4.string().optional().describe("Target Conveyor project ID"),
+      taskId: z4.string().describe("The task ID or slug")
     },
     async (params) => {
-      const files = await conn2.listTaskFiles(params.taskId);
+      const files = await conn2.listTaskFiles(params.taskId, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
     }
   );
@@ -448,17 +497,19 @@ function buildAttachmentContent(file) {
 function registerGetAttachment(server2, conn2) {
   server2.tool(
     "get_attachment",
-    "Fetch one task file's content plus metadata by file ID (accepts task id or slug). Images are returned as viewable image blocks. Large text files (logs, JSON) are returned in pages \u2014 use `offset`/`maxBytes` to read more, or fetch `downloadUrl` for the whole file. Call list_task_files first to discover IDs and sizes.",
+    "Fetch one task file's content plus metadata by file ID (accepts task id or slug). Pass projectId to target a specific project; otherwise the configured default project is used. Images are returned as viewable image blocks. Large text files (logs, JSON) are returned in pages \u2014 use `offset`/`maxBytes` to read more, or fetch `downloadUrl` for the whole file. Call list_task_files first to discover IDs and sizes.",
     {
-      taskId: z3.string().describe("The task ID or slug"),
-      fileId: z3.string().describe("The file ID to fetch"),
-      offset: z3.number().int().nonnegative().optional().describe("Byte offset into text content (paging). Default 0."),
-      maxBytes: z3.number().int().positive().optional().describe("Max bytes of text content to return from offset.")
+      projectId: z4.string().optional().describe("Target Conveyor project ID"),
+      taskId: z4.string().describe("The task ID or slug"),
+      fileId: z4.string().describe("The file ID to fetch"),
+      offset: z4.number().int().nonnegative().optional().describe("Byte offset into text content (paging). Default 0."),
+      maxBytes: z4.number().int().positive().optional().describe("Max bytes of text content to return from offset.")
     },
     async (params) => {
       const file = await conn2.getAttachment(params.taskId, params.fileId, {
         offset: params.offset,
-        maxBytes: params.maxBytes
+        maxBytes: params.maxBytes,
+        projectId: params.projectId
       });
       return { content: buildAttachmentContent(file) };
     }
@@ -467,12 +518,13 @@ function registerGetAttachment(server2, conn2) {
 function registerUploadAttachment(server2, conn2) {
   server2.tool(
     "upload_attachment",
-    "Upload a local file as a task attachment (any file type, up to 25MB). The file appears under the task's Files. Pass `comment` to also post it to the task chat in the same step.",
+    "Upload a local file as a task attachment (any file type, up to 25MB). Pass projectId to target a specific project; otherwise the configured default project is used. The file appears under the task's Files. Pass `comment` to also post it to the task chat in the same step.",
     {
-      taskId: z3.string().describe("The task ID or slug"),
-      path: z3.string().describe("Absolute path to the local file to upload"),
-      comment: z3.string().optional().describe("When set, also posts the attachment to the task chat with this text"),
-      mimeType: z3.string().optional().describe("Override the mime type inferred from the file extension")
+      projectId: z4.string().optional().describe("Target Conveyor project ID"),
+      taskId: z4.string().describe("The task ID or slug"),
+      path: z4.string().describe("Absolute path to the local file to upload"),
+      comment: z4.string().optional().describe("When set, also posts the attachment to the task chat with this text"),
+      mimeType: z4.string().optional().describe("Override the mime type inferred from the file extension")
     },
     async (params) => {
       const info = await stat(params.path).catch(() => null);
@@ -494,7 +546,8 @@ function registerUploadAttachment(server2, conn2) {
       const { fileId, uploadUrl } = await conn2.requestFileUpload(params.taskId, {
         fileName,
         mimeType,
-        fileSize: info.size
+        fileSize: info.size,
+        projectId: params.projectId
       });
       const body = await readFile(params.path);
       const res = await fetch(uploadUrl, {
@@ -512,7 +565,12 @@ function registerUploadAttachment(server2, conn2) {
           ]
         };
       }
-      const result = await conn2.confirmFileUpload(params.taskId, fileId, params.comment);
+      const result = await conn2.confirmFileUpload(
+        params.taskId,
+        fileId,
+        params.comment,
+        params.projectId
+      );
       const lines = [
         `Uploaded ${result.fileName} (${info.size} bytes, ${mimeType}). File ID: ${result.fileId}`
       ];
@@ -529,17 +587,18 @@ function registerAttachmentTools(server2, conn2) {
 }
 
 // src/tools/pull-request.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 function registerPullRequestTools(server2, conn2) {
   server2.tool(
     "create_pull_request",
-    "Open a GitHub pull request for a task's existing branch (the branch must already be pushed to origin). Moves the task to ReviewPR. Returns the PR number and URL.",
+    "Open a GitHub pull request for a task's existing branch (the branch must already be pushed to origin). Pass projectId to target a specific project; otherwise the configured default project is used. Moves the task to ReviewPR. Returns the PR number and URL.",
     {
-      taskId: z4.string().describe("The task ID whose branch should be opened as a PR"),
-      title: z4.string().describe("Pull request title"),
-      body: z4.string().describe("Pull request body (markdown)"),
-      head: z4.string().optional().describe("Source branch for the PR (defaults to the task's branch)"),
-      base: z4.string().optional().describe("Target branch for the PR (defaults to the repo default)")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID whose branch should be opened as a PR"),
+      title: z5.string().describe("Pull request title"),
+      body: z5.string().describe("Pull request body (markdown)"),
+      head: z5.string().optional().describe("Source branch for the PR (defaults to the task's branch)"),
+      base: z5.string().optional().describe("Target branch for the PR (defaults to the repo default)")
     },
     async (params) => {
       const result = await conn2.createPullRequest(params);
@@ -551,7 +610,7 @@ function registerPullRequestTools(server2, conn2) {
 }
 
 // src/tools/subtasks.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var STATUS_ENUM2 = [
   "Planning",
   "Open",
@@ -566,14 +625,15 @@ var SP_DESCRIPTION = "Story point value (1=Common, 2=Magic, 3=Rare, 5=Unique)";
 function registerCreateSubtask(server2, conn2) {
   server2.tool(
     "create_subtask",
-    "Create a subtask under a parent task. Subtasks break a larger task into independently buildable pieces.",
+    "Create a subtask under a parent task. Pass projectId to target a specific project; otherwise the configured default project is used. Subtasks break a larger task into independently buildable pieces.",
     {
-      parentTaskId: z5.string().describe("The parent task ID"),
-      title: z5.string().describe("Subtask title"),
-      description: z5.string().optional().describe("Subtask description"),
-      plan: z5.string().optional().describe("Subtask implementation plan (markdown)"),
-      ordinal: z5.number().optional().describe("Ordering position among siblings"),
-      storyPointValue: z5.number().optional().describe(SP_DESCRIPTION)
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      parentTaskId: z6.string().describe("The parent task ID"),
+      title: z6.string().describe("Subtask title"),
+      description: z6.string().optional().describe("Subtask description"),
+      plan: z6.string().optional().describe("Subtask implementation plan (markdown)"),
+      ordinal: z6.number().optional().describe("Ordering position among siblings"),
+      storyPointValue: z6.number().optional().describe(SP_DESCRIPTION)
     },
     async (params) => {
       const subtask = await conn2.createSubtask(params);
@@ -586,15 +646,16 @@ function registerCreateSubtask(server2, conn2) {
 function registerUpdateSubtask(server2, conn2) {
   server2.tool(
     "update_subtask",
-    "Update a subtask's fields: title, description, plan, status, ordering, or story points. Moving a subtask beyond Planning auto-fills missing story points and agent assignment \u2014 don't spend turns on them.",
+    "Update a subtask's fields: title, description, plan, status, ordering, or story points. Pass projectId to target a specific project; otherwise the configured default project is used. Moving a subtask beyond Planning auto-fills missing story points and agent assignment \u2014 don't spend turns on them.",
     {
-      subtaskId: z5.string().describe("The subtask ID"),
-      title: z5.string().optional().describe("New title"),
-      description: z5.string().optional().describe("New description"),
-      plan: z5.string().optional().describe("New plan (markdown)"),
-      status: z5.enum(STATUS_ENUM2).optional().describe("New status"),
-      ordinal: z5.number().optional().describe("New ordering position among siblings"),
-      storyPointValue: z5.number().optional().describe(SP_DESCRIPTION)
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      subtaskId: z6.string().describe("The subtask ID"),
+      title: z6.string().optional().describe("New title"),
+      description: z6.string().optional().describe("New description"),
+      plan: z6.string().optional().describe("New plan (markdown)"),
+      status: z6.enum(STATUS_ENUM2).optional().describe("New status"),
+      ordinal: z6.number().optional().describe("New ordering position among siblings"),
+      storyPointValue: z6.number().optional().describe(SP_DESCRIPTION)
     },
     async (params) => {
       const result = await conn2.updateSubtask(params);
@@ -609,12 +670,13 @@ function registerUpdateSubtask(server2, conn2) {
 function registerListSubtasks(server2, conn2) {
   server2.tool(
     "list_subtasks",
-    "List all subtasks of a parent task with their status and ordering.",
+    "List all subtasks of a parent task with their status and ordering. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z5.string().describe("The parent task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The parent task ID")
     },
     async (params) => {
-      const subtasks = await conn2.listSubtasks(params.taskId);
+      const subtasks = await conn2.listSubtasks(params.taskId, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(subtasks, null, 2) }] };
     }
   );
@@ -622,12 +684,13 @@ function registerListSubtasks(server2, conn2) {
 function registerDeleteSubtask(server2, conn2) {
   server2.tool(
     "delete_subtask",
-    "Delete a subtask by ID. This is permanent \u2014 use update_subtask to set status to Cancelled if you only want to close it.",
+    "Delete a subtask by ID. Pass projectId to target a specific project; otherwise the configured default project is used. This is permanent \u2014 use update_subtask to set status to Cancelled if you only want to close it.",
     {
-      subtaskId: z5.string().describe("The subtask ID to delete")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      subtaskId: z6.string().describe("The subtask ID to delete")
     },
     async (params) => {
-      const result = await conn2.deleteSubtask(params.subtaskId);
+      const result = await conn2.deleteSubtask(params.subtaskId, params.projectId);
       return {
         content: [
           { type: "text", text: result.deleted ? "Subtask deleted" : "Subtask not deleted" }
@@ -644,16 +707,17 @@ function registerSubtaskTools(server2, conn2) {
 }
 
 // src/tools/dependencies.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 function registerGetDependencies(server2, conn2) {
   server2.tool(
     "get_dependencies",
-    "Get a task's dependencies and their met/unmet status (met = merged to dev). Use to confirm blockers merged, or see why a task cannot start. For task state use get_task.",
+    "Get a task's dependencies and their met/unmet status (met = merged to dev). Pass projectId to target a specific project; otherwise the configured default project is used. Use to confirm blockers merged, or see why a task cannot start. For task state use get_task.",
     {
-      taskId: z6.string().describe("The task ID")
+      projectId: z7.string().optional().describe("Target Conveyor project ID"),
+      taskId: z7.string().describe("The task ID")
     },
     async (params) => {
-      const deps = await conn2.getDependencies(params.taskId);
+      const deps = await conn2.getDependencies(params.taskId, params.projectId);
       return { content: [{ type: "text", text: JSON.stringify(deps, null, 2) }] };
     }
   );
@@ -661,10 +725,11 @@ function registerGetDependencies(server2, conn2) {
 function registerAddDependency(server2, conn2) {
   server2.tool(
     "add_dependency",
-    "Add a blocking dependency \u2014 this task cannot start until the named task is merged to dev.",
+    "Add a blocking dependency \u2014 this task cannot start until the named task is merged to dev. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      taskId: z6.string().describe("The task ID that will be blocked"),
-      dependsOnSlugOrId: z6.string().describe("Slug or ID of the task this one depends on")
+      projectId: z7.string().optional().describe("Target Conveyor project ID"),
+      taskId: z7.string().describe("The task ID that will be blocked"),
+      dependsOnSlugOrId: z7.string().describe("Slug or ID of the task this one depends on")
     },
     async (params) => {
       await conn2.addDependency(params);
@@ -675,10 +740,11 @@ function registerAddDependency(server2, conn2) {
 function registerRemoveDependency(server2, conn2) {
   server2.tool(
     "remove_dependency",
-    "Remove a previously added dependency from a task. The task is no longer blocked by the named task. Returns: confirmation string.",
+    "Remove a previously added dependency from a task. Pass projectId to target a specific project; otherwise the configured default project is used. The task is no longer blocked by the named task. Returns: confirmation string.",
     {
-      taskId: z6.string().describe("The task ID to unblock"),
-      dependsOnSlugOrId: z6.string().describe("Slug or ID of the dependency to remove")
+      projectId: z7.string().optional().describe("Target Conveyor project ID"),
+      taskId: z7.string().describe("The task ID to unblock"),
+      dependsOnSlugOrId: z7.string().describe("Slug or ID of the dependency to remove")
     },
     async (params) => {
       await conn2.removeDependency(params);
@@ -693,15 +759,16 @@ function registerDependencyTools(server2, conn2) {
 }
 
 // src/tools/suggestions.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 function registerSuggestionTools(server2, conn2) {
   server2.tool(
     "create_suggestion",
-    "Suggest a feature, improvement, rule, or idea for the project. Duplicates are deduped and your upvote is recorded.",
+    "Suggest a feature, improvement, rule, or idea for the project. Pass projectId to target a specific project; otherwise the configured default project is used. Duplicates are deduped and your upvote is recorded.",
     {
-      title: z7.string().describe("Suggestion title"),
-      description: z7.string().optional().describe("Suggestion details (markdown)"),
-      tagNames: z7.array(z7.string()).optional().describe('Tag names to categorize the suggestion (e.g., ["agent-runner"])')
+      projectId: z8.string().optional().describe("Target Conveyor project ID"),
+      title: z8.string().describe("Suggestion title"),
+      description: z8.string().optional().describe("Suggestion details (markdown)"),
+      tagNames: z8.array(z8.string()).optional().describe('Tag names to categorize the suggestion (e.g., ["agent-runner"])')
     },
     async (params) => {
       const result = await conn2.createSuggestion(params);
@@ -712,16 +779,17 @@ function registerSuggestionTools(server2, conn2) {
 }
 
 // src/tools/checklists.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 function registerListManualTests(server2, conn2) {
   server2.tool(
     "list_manual_tests",
-    "List the manual test checklist items for a task. Use to see what manual verification steps have already been recorded.",
+    "List the manual test checklist items for a task. Pass projectId to target a specific project; otherwise the configured default project is used. Use to see what manual verification steps have already been recorded.",
     {
-      taskId: z8.string().describe("The task ID or slug (the value in a card URL, /cards/<slug>)")
+      projectId: z9.string().optional().describe("Target Conveyor project ID"),
+      taskId: z9.string().describe("The task ID or slug (the value in a card URL, /cards/<slug>)")
     },
     async (params) => {
-      const items = await conn2.listManualTests(params.taskId);
+      const items = await conn2.listManualTests(params.taskId, params.projectId);
       if (items.length === 0) {
         return { content: [{ type: "text", text: "No manual tests recorded for this task." }] };
       }
@@ -736,13 +804,14 @@ function registerListManualTests(server2, conn2) {
 function registerSetManualTests(server2, conn2) {
   server2.tool(
     "set_manual_tests",
-    "Add manual test steps to a task's checklist. Existing items with the same title are automatically skipped (deduplication). Use to record specific manual verification steps that reviewers should follow when testing the task's PR.",
+    "Add manual test steps to a task's checklist. Pass projectId to target a specific project; otherwise the configured default project is used. Existing items with the same title are automatically skipped (deduplication). Use to record specific manual verification steps that reviewers should follow when testing the task's PR.",
     {
-      taskId: z8.string().describe("The task ID or slug"),
-      items: z8.array(z8.object({ title: z8.string().min(1).describe("A concise, actionable test step") })).min(1).describe("List of manual test steps to add")
+      projectId: z9.string().optional().describe("Target Conveyor project ID"),
+      taskId: z9.string().describe("The task ID or slug"),
+      items: z9.array(z9.object({ title: z9.string().min(1).describe("A concise, actionable test step") })).min(1).describe("List of manual test steps to add")
     },
     async (params) => {
-      const result = await conn2.setManualTests(params.taskId, params.items);
+      const result = await conn2.setManualTests(params.taskId, params.items, params.projectId);
       const parts = [`Created ${result.created} manual test item(s).`];
       if (result.skipped > 0) parts.push(`Skipped ${result.skipped} duplicate(s).`);
       return { content: [{ type: "text", text: parts.join(" ") }] };
@@ -754,6 +823,224 @@ function registerChecklistTools(server2, conn2) {
   registerSetManualTests(server2, conn2);
 }
 
+// src/tools/workspace.ts
+import { z as z10 } from "zod";
+
+// src/workspace-ssh-tunnel.ts
+import net from "net";
+import { once } from "events";
+import { WebSocket } from "ws";
+function withPort(url, port) {
+  const parsed = new URL(url);
+  parsed.searchParams.set("port", String(port));
+  return parsed.toString();
+}
+function toBuffer(data) {
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  return Buffer.concat(data);
+}
+async function startWorkspaceSshTunnel(options) {
+  const host = options.host ?? "127.0.0.1";
+  const server2 = net.createServer((client) => {
+    let ws = null;
+    let ready = false;
+    const pending = [];
+    client.on("data", (chunk) => {
+      if (ready && ws && ws.readyState === WebSocket.OPEN) ws.send(chunk);
+      else pending.push(chunk);
+    });
+    client.on("close", () => ws?.close());
+    client.on("error", () => ws?.close());
+    options.resolveTarget().then(({ tunnelUrl, attachToken }) => {
+      const socket = new WebSocket(withPort(tunnelUrl, options.remotePort), {
+        headers: { "x-workspace-attach-token": attachToken }
+      });
+      ws = socket;
+      socket.on("message", (data) => {
+        const chunk = toBuffer(data);
+        if (!ready) {
+          const text = chunk.toString("utf8");
+          if (text === JSON.stringify({ ok: true })) {
+            ready = true;
+            for (const buffered of pending.splice(0)) socket.send(buffered);
+            return;
+          }
+          client.destroy(new Error(`Workspace tunnel rejected connection: ${text}`));
+          socket.close();
+          return;
+        }
+        client.write(chunk);
+      });
+      socket.on("close", () => client.destroy());
+      socket.on("error", (err) => client.destroy(err));
+    }).catch((err) => {
+      client.destroy(err instanceof Error ? err : new Error(String(err)));
+    });
+  });
+  const ac = new AbortController();
+  server2.listen(options.preferredLocalPort ?? 0, host);
+  try {
+    await Promise.race([
+      once(server2, "listening", { signal: ac.signal }),
+      once(server2, "error", { signal: ac.signal }).then(([err]) => {
+        throw err instanceof Error ? err : new Error(String(err));
+      })
+    ]);
+  } catch (err) {
+    server2.close();
+    throw new Error(
+      `Failed to bind workspace SSH tunnel: ${err instanceof Error ? err.message : String(err)}`,
+      { cause: err }
+    );
+  } finally {
+    ac.abort();
+  }
+  const address = server2.address();
+  if (!address || typeof address === "string") {
+    server2.close();
+    throw new Error("Failed to bind workspace SSH tunnel");
+  }
+  return {
+    host,
+    port: address.port,
+    close: () => new Promise((resolve, reject) => {
+      server2.close((err) => {
+        if (err) reject(err);
+        else resolve();
+      });
+    })
+  };
+}
+
+// src/tools/workspace.ts
+var activeTunnels = /* @__PURE__ */ new Map();
+function createTunnelId(taskId, port) {
+  return `${taskId}:${port}:${Date.now().toString(36)}:${Math.random().toString(36).slice(2, 8)}`;
+}
+function localUrlFor(port, host, localPort) {
+  if (port === 2222) return void 0;
+  return `http://${host}:${localPort}`;
+}
+function registerAttachInfoTool(server2, conn2) {
+  server2.tool(
+    "workspace_attach_info",
+    "Return SSH/SFTP attach metadata for a running task Claudespace, plus hosted preview URLs and configured preview ports. Optionally installs an OpenSSH public key for this attach session.",
+    {
+      taskId: z10.string().describe("The task ID"),
+      sshPublicKey: z10.string().optional().describe("Optional OpenSSH public key to install into the workspace")
+    },
+    async ({ taskId, sshPublicKey }) => {
+      const info = await conn2.getWorkspaceAttachInfo(taskId, sshPublicKey);
+      return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+    }
+  );
+}
+function registerPreviewUrlsTool(server2, conn2) {
+  server2.tool(
+    "workspace_preview_urls",
+    "Return the hosted preview URLs and preview ports for a running task Claudespace. This mirrors the web UI preview link metadata.",
+    {
+      taskId: z10.string().describe("The task ID")
+    },
+    async ({ taskId }) => {
+      const info = await conn2.getWorkspaceAttachInfo(taskId);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                taskId: info.taskId,
+                sessionId: info.sessionId,
+                previewPorts: info.previewPorts,
+                previewUrls: info.previewUrls
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+}
+function registerStartTunnelTool(server2, conn2, startTunnel) {
+  server2.tool(
+    "workspace_start_tunnel",
+    "Start a local loopback tunnel through the MCP server to a running task Claudespace port. Use port 2222 for SSH/SFTP, or one of previewPorts for app access.",
+    {
+      taskId: z10.string().describe("The task ID"),
+      port: z10.number().optional().describe("Remote Claudespace port. Defaults to SSH port 2222."),
+      preferredLocalPort: z10.number().optional().describe("Preferred local loopback port. If omitted, the OS chooses one."),
+      sshPublicKey: z10.string().optional().describe("Optional OpenSSH public key to install before opening the tunnel")
+    },
+    async ({ taskId, port, preferredLocalPort, sshPublicKey }) => {
+      const info = await conn2.getWorkspaceAttachInfo(taskId, sshPublicKey);
+      const remotePort = port ?? info.ssh?.remotePort ?? 2222;
+      const handle = await startTunnel({
+        remotePort,
+        preferredLocalPort,
+        // Re-mint per connection so the tunnel outlives the attach-token TTL.
+        // The key (if any) is already installed by the call above; the refetch
+        // only needs a fresh token, so it omits sshPublicKey.
+        resolveTarget: async () => {
+          const fresh = await conn2.getWorkspaceAttachInfo(taskId);
+          return { tunnelUrl: fresh.tunnelUrl, attachToken: fresh.attachToken };
+        }
+      });
+      const tunnelId = createTunnelId(taskId, remotePort);
+      activeTunnels.set(tunnelId, handle);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                tunnelId,
+                taskId,
+                remotePort,
+                localHost: handle.host,
+                localPort: handle.port,
+                localUrl: localUrlFor(remotePort, handle.host, handle.port),
+                sshCommand: remotePort === 2222 ? `ssh -p ${handle.port} ${info.ssh?.username ?? "conveyor"}@${handle.host}` : void 0,
+                sftpCommand: remotePort === 2222 ? `sftp -P ${handle.port} ${info.ssh?.username ?? "conveyor"}@${handle.host}` : void 0,
+                previewPorts: info.previewPorts,
+                previewUrls: info.previewUrls,
+                expiresAt: info.expiresAt
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+}
+function registerStopTunnelTool(server2) {
+  server2.tool(
+    "workspace_stop_tunnel",
+    "Stop a local workspace tunnel previously opened by workspace_start_tunnel.",
+    {
+      tunnelId: z10.string().describe("Tunnel id returned by workspace_start_tunnel")
+    },
+    async ({ tunnelId }) => {
+      const tunnel = activeTunnels.get(tunnelId);
+      if (!tunnel) throw new Error("Workspace tunnel not found");
+      await tunnel.close();
+      activeTunnels.delete(tunnelId);
+      return { content: [{ type: "text", text: "Workspace tunnel stopped" }] };
+    }
+  );
+}
+function registerWorkspaceTools(server2, conn2, deps = {}) {
+  registerAttachInfoTool(server2, conn2);
+  registerPreviewUrlsTool(server2, conn2);
+  registerStartTunnelTool(server2, conn2, deps.startTunnel ?? startWorkspaceSshTunnel);
+  registerStopTunnelTool(server2);
+}
+
 // src/tools/index.ts
 function registerAllTools(server2, conn2) {
   registerProjectTools(server2, conn2);
@@ -765,16 +1052,17 @@ function registerAllTools(server2, conn2) {
   registerDependencyTools(server2, conn2);
   registerSuggestionTools(server2, conn2);
   registerChecklistTools(server2, conn2);
+  registerWorkspaceTools(server2, conn2);
 }
 
 // src/cli.ts
 var { version } = createRequire(import.meta.url)("../package.json");
 var apiUrl = process.env.CONVEYOR_API_URL;
-var projectToken = process.env.CONVEYOR_PROJECT_TOKEN;
+var projectToken = process.env.CONVEYOR_USER_TOKEN ?? process.env.CONVEYOR_PROJECT_TOKEN;
 var projectId = process.env.CONVEYOR_PROJECT_ID;
-if (!apiUrl || !projectToken || !projectId) {
+if (!apiUrl || !projectToken) {
   process.stderr.write(
-    "Error: CONVEYOR_API_URL, CONVEYOR_PROJECT_TOKEN, and CONVEYOR_PROJECT_ID environment variables are required.\n"
+    "Error: CONVEYOR_API_URL and CONVEYOR_USER_TOKEN or CONVEYOR_PROJECT_TOKEN environment variables are required. CONVEYOR_PROJECT_ID is optional and sets the default project.\n"
   );
   process.exit(1);
 }