@mtaap/mcp 0.2.3 → 0.2.5

package/dist/cli.js

@@ -28,7 +28,7 @@ var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 
 // src/version.ts
-var VERSION = "0.2.3";
+var VERSION = "0.2.5";
 
 // src/index.ts
 var import_zod3 = require("zod");
@@ -402,7 +402,8 @@ var ListProjectsInputSchema = import_zod2.z.object({
 var ListTasksInputSchema = import_zod2.z.object({
   projectId: import_zod2.z.string().optional(),
   state: import_zod2.z.nativeEnum(TaskState).optional(),
-  assigneeId: import_zod2.z.string().optional()
+  assigneeId: import_zod2.z.string().optional(),
+  includeArchived: import_zod2.z.boolean().optional()
 });
 var cuidOrPrefixedId = import_zod2.z.string().regex(/^([a-z0-9]+|[a-z]+_[a-zA-Z0-9]+)$/);
 var GetTaskInputSchema = import_zod2.z.object({
@@ -454,6 +455,14 @@ var ApproveTaskInputSchema = import_zod2.z.object({
   taskId: cuidOrPrefixedId,
   reviewComments: import_zod2.z.string().max(2e3).optional()
 });
+var ArchiveTaskInputSchema = import_zod2.z.object({
+  projectId: cuidOrPrefixedId,
+  taskId: cuidOrPrefixedId
+});
+var UnarchiveTaskInputSchema = import_zod2.z.object({
+  projectId: cuidOrPrefixedId,
+  taskId: cuidOrPrefixedId
+});
 var CreatePersonalProjectInputSchema = import_zod2.z.object({
   name: import_zod2.z.string().min(1).max(100),
   description: import_zod2.z.string().max(500).optional(),
@@ -495,7 +504,8 @@ var UpdateProjectInputSchema = import_zod2.z.object({
   description: import_zod2.z.string().max(500).optional(),
   repositoryUrl: import_zod2.z.string().url().optional(),
   baseBranch: import_zod2.z.string().optional(),
-  tags: import_zod2.z.array(import_zod2.z.string()).optional()
+  tags: import_zod2.z.array(import_zod2.z.string()).optional(),
+  allowMemberArchive: import_zod2.z.boolean().optional()
 });
 var CreateEpicInputSchema = import_zod2.z.object({
   projectId: cuidOrPrefixedId,
@@ -1021,6 +1031,7 @@ var MCPApiClient = class {
     if (filters.projectId) params.set("projectId", filters.projectId);
     if (filters.state) params.set("state", filters.state);
     if (filters.assigneeId) params.set("assigneeId", filters.assigneeId);
+    if (filters.includeArchived) params.set("includeArchived", "true");
     const queryString = params.toString();
     const path = queryString ? `/api/mcp/tasks?${queryString}` : "/api/mcp/tasks";
     return this.request("GET", path);
@@ -1065,6 +1076,22 @@ var MCPApiClient = class {
       deleteBranch
     });
   }
+  /**
+   * Archive a task (soft delete)
+   */
+  async archiveTask(taskId, projectId) {
+    return this.request("POST", `/api/mcp/tasks/${taskId}/archive`, {
+      projectId
+    });
+  }
+  /**
+   * Unarchive a task (restore)
+   */
+  async unarchiveTask(taskId, projectId) {
+    return this.request("DELETE", `/api/mcp/tasks/${taskId}/archive`, {
+      projectId
+    });
+  }
   /**
    * Report task error
    */
@@ -1109,18 +1136,18 @@ var MCPApiClient = class {
   }
 };
 function createApiClientFromEnv() {
-  const baseUrl = process.env.MTAAP_BASE_URL;
-  const apiKey = process.env.MTAAP_API_KEY;
+  const baseUrl = process.env.COLLAB_BASE_URL;
+  const apiKey = process.env.COLLAB_API_KEY;
   if (!baseUrl) {
-    throw new Error("MTAAP_BASE_URL environment variable is required");
+    throw new Error("COLLAB_BASE_URL environment variable is required");
   }
   if (!apiKey) {
-    throw new Error("MTAAP_API_KEY environment variable is required");
+    throw new Error("COLLAB_API_KEY environment variable is required");
   }
   return new MCPApiClient({
     baseUrl,
     apiKey,
-    debug: process.env.MTAAP_DEBUG === "true"
+    debug: process.env.COLLAB_DEBUG === "true"
   });
 }
 
@@ -1150,11 +1177,62 @@ function assertApiKeyPermission(apiKey, required, toolName) {
 }
 
 // src/index.ts
+var COLLAB_SERVER_INSTRUCTIONS = `Collab - AI-assisted software development task management platform.
+
+TOOL CATEGORIES:
+
+1. Project Discovery (READ):
+   - list_projects, get_project_context, get_version
+
+2. Task Management (READ/WRITE):
+   - list_tasks, get_task, create_task, archive_task, unarchive_task
+
+3. Task Execution (WRITE):
+   - assign_task, update_progress, add_note, complete_task, abandon_task, report_error
+
+4. Code Review (WRITE):
+   - request_changes, approve_task
+
+5. Session Management (READ):
+   - check_active_task
+
+WORKFLOWS:
+
+Standard Task Workflow:
+  list_projects -> get_project_context -> list_tasks(state=READY) -> get_task -> assign_task -> [update_progress...] -> complete_task
+
+Resume Workflow:
+  check_active_task -> (if active) get_task -> update_progress -> complete_task
+
+Review Workflow:
+  list_tasks(state=REVIEW) -> get_task -> approve_task OR request_changes
+
+Error Recovery:
+  report_error -> abandon_task(deleteBranch=false) -> list_tasks -> assign_task (retry or pick different task)
+  (abandon_task returns IN_PROGRESS tasks to READY state)
+
+TASK STATE FLOW:
+  BACKLOG -> READY -> IN_PROGRESS -> REVIEW -> DONE
+  (request_changes: REVIEW -> IN_PROGRESS)
+  (abandon_task: IN_PROGRESS -> READY)
+
+CONSTRAINTS:
+- assign_task is atomic - fails if already claimed
+- Only READY tasks can be assigned
+- complete_task requires IN_PROGRESS state
+- request_changes/approve_task require REVIEW state
+- Always check_active_task before starting new work
+- Call update_progress frequently to checkpoint`;
 async function createMCPServer() {
-  const server = new import_mcp.McpServer({
-    name: "mtaap",
-    version: VERSION
-  });
+  const server = new import_mcp.McpServer(
+    {
+      name: "collab",
+      version: VERSION
+    },
+    {
+      instructions: COLLAB_SERVER_INSTRUCTIONS
+    }
+  );
   const apiClient = createApiClientFromEnv();
   let authContext;
   try {
@@ -1171,7 +1249,7 @@ async function createMCPServer() {
   server.registerTool(
     "list_projects",
     {
-      description: "List accessible projects (personal + team via tags)",
+      description: "Discover all accessible projects. Use first to find project IDs. Filter by TEAM, PERSONAL, or ALL workspaces.",
       inputSchema: {
         workspaceType: import_zod3.z.enum(["TEAM", "PERSONAL", "ALL"]).optional().describe("Filter by workspace type")
       }
@@ -1201,11 +1279,12 @@ async function createMCPServer() {
   server.registerTool(
     "list_tasks",
     {
-      description: "Returns available tasks (filterable by project, state)",
+      description: "Query tasks with filters. Use state=READY for assignable tasks, state=REVIEW for pending reviews.",
       inputSchema: {
         projectId: import_zod3.z.string().optional().describe("Filter by project ID"),
         state: import_zod3.z.nativeEnum(TaskState).optional().describe("Filter by task state"),
-        assigneeId: import_zod3.z.string().optional().describe("Filter by assignee ID")
+        assigneeId: import_zod3.z.string().optional().describe("Filter by assignee ID"),
+        includeArchived: import_zod3.z.boolean().optional().describe("Include archived tasks (default: false)")
       }
     },
     async (args) => {
@@ -1215,7 +1294,8 @@ async function createMCPServer() {
         const tasks = await apiClient.listTasks({
           projectId: validated.projectId,
           state: validated.state,
-          assigneeId: validated.assigneeId
+          assigneeId: validated.assigneeId,
+          includeArchived: validated.includeArchived
         });
         return {
           content: [
@@ -1233,7 +1313,7 @@ async function createMCPServer() {
   server.registerTool(
     "get_task",
     {
-      description: "Full task details including acceptance criteria",
+      description: "Get complete task details with acceptance criteria and notes. Call before assign_task to understand requirements.",
       inputSchema: {
         taskId: import_zod3.z.string().describe("The task ID to retrieve")
       }
@@ -1259,7 +1339,7 @@ async function createMCPServer() {
   server.registerTool(
     "assign_task",
     {
-      description: "Atomic claim - creates branch. Fails if already taken.",
+      description: "Atomically claim a task and create git branch. Race-safe - fails if already assigned. Task must be READY.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID"),
         taskId: import_zod3.z.string().describe("The task ID to assign"),
@@ -1295,7 +1375,7 @@ async function createMCPServer() {
   server.registerTool(
     "update_progress",
     {
-      description: "Reports status, updates checkboxes, writes checkpoint",
+      description: "Report progress and checkpoint work. Call frequently during execution. Marks acceptance criteria complete.",
       inputSchema: {
         taskId: import_zod3.z.string().describe("The task ID to update"),
         statusMessage: import_zod3.z.string().optional().describe("Status message (max 1000 chars)"),
@@ -1332,7 +1412,7 @@ async function createMCPServer() {
   server.registerTool(
     "complete_task",
     {
-      description: "Marks complete, triggers PR, deletes local state file",
+      description: "Finish task and create pull request. Moves task to REVIEW. Requires IN_PROGRESS state.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID"),
         taskId: import_zod3.z.string().describe("The task ID to complete"),
@@ -1370,7 +1450,7 @@ async function createMCPServer() {
   server.registerTool(
     "check_active_task",
     {
-      description: "Check for resumable task in .mtaap/active-task.json"
+      description: "Check for resumable work from previous session. Always call before starting new work."
     },
     async () => {
       assertApiKeyPermission(
@@ -1392,7 +1472,7 @@ async function createMCPServer() {
   server.registerTool(
     "report_error",
     {
-      description: "Report unrecoverable error, displays on task in webapp",
+      description: "Report unrecoverable errors (BUILD_FAILURE, TEST_FAILURE, CONFLICT, AUTH_ERROR). Consider abandon_task after.",
       inputSchema: {
         taskId: import_zod3.z.string().describe("The task ID"),
         errorType: import_zod3.z.nativeEnum(ErrorType).describe("Error type: BUILD_FAILURE, TEST_FAILURE, CONFLICT, AUTH_ERROR, OTHER"),
@@ -1430,7 +1510,7 @@ async function createMCPServer() {
   server.registerTool(
     "get_project_context",
     {
-      description: "Returns assembled context (README, stack, conventions)",
+      description: "Load project README, tech stack, and coding conventions. Call after selecting project.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID")
       }
@@ -1460,7 +1540,7 @@ async function createMCPServer() {
   server.registerTool(
     "add_note",
     {
-      description: "Append implementation notes to task",
+      description: "Document implementation decisions. Notes persist for future reference and handoff.",
       inputSchema: {
         taskId: import_zod3.z.string().describe("The task ID"),
         content: import_zod3.z.string().describe("Note content (max 500 chars)")
@@ -1490,7 +1570,7 @@ async function createMCPServer() {
   server.registerTool(
     "abandon_task",
     {
-      description: "Unassign from a task and optionally delete the branch",
+      description: "Release task assignment and optionally clean up branch. Task returns to READY. Use after errors.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID"),
         taskId: import_zod3.z.string().describe("The task ID to abandon"),
@@ -1523,10 +1603,78 @@ async function createMCPServer() {
       }
     }
   );
+  server.registerTool(
+    "archive_task",
+    {
+      description: "Soft-delete a task. Hidden but restorable via unarchive_task.",
+      inputSchema: {
+        projectId: import_zod3.z.string().describe("The project ID"),
+        taskId: import_zod3.z.string().describe("The task ID to archive")
+      }
+    },
+    async (args) => {
+      assertApiKeyPermission(
+        mockApiKey,
+        ApiKeyPermission.WRITE,
+        "archive_task"
+      );
+      const validated = ArchiveTaskInputSchema.parse(args);
+      try {
+        const result = await apiClient.archiveTask(
+          validated.taskId,
+          validated.projectId
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return handleApiError(error);
+      }
+    }
+  );
+  server.registerTool(
+    "unarchive_task",
+    {
+      description: "Restore previously archived task to original state.",
+      inputSchema: {
+        projectId: import_zod3.z.string().describe("The project ID"),
+        taskId: import_zod3.z.string().describe("The task ID to restore")
+      }
+    },
+    async (args) => {
+      assertApiKeyPermission(
+        mockApiKey,
+        ApiKeyPermission.WRITE,
+        "unarchive_task"
+      );
+      const validated = UnarchiveTaskInputSchema.parse(args);
+      try {
+        const result = await apiClient.unarchiveTask(
+          validated.taskId,
+          validated.projectId
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2)
+            }
+          ]
+        };
+      } catch (error) {
+        return handleApiError(error);
+      }
+    }
+  );
   server.registerTool(
     "create_personal_project",
     {
-      description: "Create project in user's personal workspace",
+      description: "Create new project in personal workspace linked to GitHub repository.",
       inputSchema: {
         name: import_zod3.z.string().describe("Project name (max 100 chars)"),
         description: import_zod3.z.string().optional().describe("Project description (max 500 chars)"),
@@ -1562,7 +1710,7 @@ async function createMCPServer() {
   server.registerTool(
     "create_task",
     {
-      description: "Create a new task in a project. Requires WRITE permission and project access.",
+      description: "Create task with title, description, acceptance criteria. Starts in BACKLOG. Priority: LOW/MEDIUM/HIGH/CRITICAL.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID to create the task in"),
         epicId: import_zod3.z.string().nullable().optional().describe("Optional epic ID to associate the task with"),
@@ -1608,7 +1756,7 @@ async function createMCPServer() {
   server.registerTool(
     "request_changes",
     {
-      description: "Submit review comments requesting changes on a task in REVIEW state",
+      description: "Return task from REVIEW to IN_PROGRESS with feedback. Original assignee addresses changes.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID"),
         taskId: import_zod3.z.string().describe("The task ID to review"),
@@ -1646,7 +1794,7 @@ async function createMCPServer() {
   server.registerTool(
     "approve_task",
     {
-      description: "Approve a task in REVIEW state and mark it as DONE",
+      description: "Approve completed work and mark DONE. Only for REVIEW state tasks.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID"),
         taskId: import_zod3.z.string().describe("The task ID to approve"),
@@ -1682,7 +1830,7 @@ async function createMCPServer() {
   server.registerTool(
     "get_version",
     {
-      description: "Get the current MTAAP version"
+      description: "Check MCP server version and connectivity."
     },
     async () => {
       assertApiKeyPermission(mockApiKey, ApiKeyPermission.READ, "get_version");
@@ -1741,7 +1889,7 @@ function handleApiError(error) {
 async function checkActiveTask() {
   const fs = await import("fs");
   const path = await import("path");
-  const activeTaskPath = path.join(process.cwd(), ".mtaap", "active-task.json");
+  const activeTaskPath = path.join(process.cwd(), ".collab", "active-task.json");
   try {
     await fs.promises.access(activeTaskPath);
     const content = await fs.promises.readFile(activeTaskPath, "utf-8");
@@ -1762,34 +1910,34 @@ async function checkActiveTask() {
 function handleCliFlags() {
   const args = process.argv.slice(2);
   if (args.includes("--version") || args.includes("-v")) {
-    console.log(`mtaap-mcp v${VERSION}`);
+    console.log(`collab-mcp v${VERSION}`);
     process.exit(0);
   }
   if (args.includes("--help") || args.includes("-h")) {
-    console.log(`mtaap-mcp v${VERSION}
+    console.log(`collab-mcp v${VERSION}
 
-MTAAP MCP Server - Model Context Protocol server for MTAAP
+Collab MCP Server - Model Context Protocol server for Collab
 
 Usage:
-  mtaap-mcp [options]
+  collab-mcp [options]
 
 Options:
   -v, --version    Show version number
   -h, --help       Show this help message
 
 Environment Variables:
-  MTAAP_API_KEY    Your MTAAP API key (required)
-  MTAAP_BASE_URL   MTAAP webapp URL (required)
+  COLLAB_API_KEY    Your Collab API key (required)
+  COLLAB_BASE_URL   Collab webapp URL (required)
 
 Example mcp.json configuration:
 {
   "mcpServers": {
-    "mtaap": {
+    "collab": {
       "command": "npx",
       "args": ["@mtaap/mcp"],
       "env": {
-        "MTAAP_API_KEY": "usr_your_api_key_here",
-        "MTAAP_BASE_URL": "https://collab.mtaap.de"
+        "COLLAB_API_KEY": "collab_your_api_key_here",
+        "COLLAB_BASE_URL": "https://collab.mtaap.de"
       }
     }
   }
@@ -1799,32 +1947,32 @@ Example mcp.json configuration:
 }
 function validateEnvironment() {
   const errors = [];
-  if (!process.env.MTAAP_API_KEY) {
+  if (!process.env.COLLAB_API_KEY) {
     errors.push(
-      "MTAAP_API_KEY is required. Generate one at https://collab.mtaap.de/settings/api-keys"
+      "COLLAB_API_KEY is required. Generate one at https://collab.mtaap.de/settings/api-keys"
     );
   }
-  if (!process.env.MTAAP_BASE_URL) {
+  if (!process.env.COLLAB_BASE_URL) {
     errors.push(
-      "MTAAP_BASE_URL is required. Set to https://collab.mtaap.de for cloud or your self-hosted URL."
+      "COLLAB_BASE_URL is required. Set to https://collab.mtaap.de for cloud or your self-hosted URL."
     );
   }
   if (errors.length > 0) {
     for (const error of errors) {
-      console.error(`[mtaap-mcp] Error: ${error}`);
+      console.error(`[collab-mcp] Error: ${error}`);
     }
     console.error("\nRequired environment variables:");
-    console.error("  MTAAP_API_KEY     Your MTAAP API key");
-    console.error("  MTAAP_BASE_URL    MTAAP webapp URL (e.g., https://collab.mtaap.de)");
+    console.error("  COLLAB_API_KEY     Your Collab API key");
+    console.error("  COLLAB_BASE_URL    Collab webapp URL (e.g., https://collab.mtaap.de)");
     console.error("\nExample mcp.json configuration:");
     console.error(`{
   "mcpServers": {
-    "mtaap": {
+    "collab": {
       "command": "npx",
       "args": ["@mtaap/mcp"],
       "env": {
-        "MTAAP_API_KEY": "usr_your_api_key_here",
-        "MTAAP_BASE_URL": "https://collab.mtaap.de"
+        "COLLAB_API_KEY": "collab_your_api_key_here",
+        "COLLAB_BASE_URL": "https://collab.mtaap.de"
       }
     }
   }
@@ -1832,20 +1980,20 @@ function validateEnvironment() {
     process.exit(1);
   }
   try {
-    new URL(process.env.MTAAP_BASE_URL);
+    new URL(process.env.COLLAB_BASE_URL);
   } catch {
-    console.error(`[mtaap-mcp] Error: MTAAP_BASE_URL is not a valid URL: ${process.env.MTAAP_BASE_URL}`);
+    console.error(`[collab-mcp] Error: COLLAB_BASE_URL is not a valid URL: ${process.env.COLLAB_BASE_URL}`);
     process.exit(1);
   }
 }
 async function checkConnectivity() {
-  const baseUrl = process.env.MTAAP_BASE_URL;
-  console.error(`[mtaap-mcp] Checking connectivity to ${baseUrl}...`);
+  const baseUrl = process.env.COLLAB_BASE_URL;
+  console.error(`[collab-mcp] Checking connectivity to ${baseUrl}...`);
   try {
     const response = await fetch(`${baseUrl}/api/mcp/auth`, {
       method: "GET",
       headers: {
-        "X-API-Key": process.env.MTAAP_API_KEY
+        "X-API-Key": process.env.COLLAB_API_KEY
       },
       signal: AbortSignal.timeout(1e4)
       // 10 second timeout
@@ -1853,51 +2001,51 @@ async function checkConnectivity() {
     if (!response.ok) {
       const data = await response.json().catch(() => ({}));
       if (response.status === 401) {
-        console.error("[mtaap-mcp] Error: Invalid or expired API key");
+        console.error("[collab-mcp] Error: Invalid or expired API key");
         process.exit(1);
       }
-      console.error(`[mtaap-mcp] Error: API returned ${response.status}: ${data.error || "Unknown error"}`);
+      console.error(`[collab-mcp] Error: API returned ${response.status}: ${data.error || "Unknown error"}`);
       process.exit(1);
     }
-    console.error("[mtaap-mcp] Connected successfully");
+    console.error("[collab-mcp] Connected successfully");
   } catch (error) {
     if (error instanceof Error && error.name === "TimeoutError") {
-      console.error(`[mtaap-mcp] Error: Connection timed out to ${baseUrl}`);
+      console.error(`[collab-mcp] Error: Connection timed out to ${baseUrl}`);
     } else {
-      console.error(`[mtaap-mcp] Error: Could not connect to ${baseUrl}`);
-      console.error(`[mtaap-mcp] Details: ${error instanceof Error ? error.message : String(error)}`);
+      console.error(`[collab-mcp] Error: Could not connect to ${baseUrl}`);
+      console.error(`[collab-mcp] Details: ${error instanceof Error ? error.message : String(error)}`);
     }
     process.exit(1);
   }
 }
 async function main() {
   handleCliFlags();
-  console.error("[mtaap-mcp] Starting MTAAP MCP server...");
+  console.error("[collab-mcp] Starting Collab MCP server...");
   validateEnvironment();
   await checkConnectivity();
   try {
     await createMCPServer();
-    console.error("[mtaap-mcp] Server started successfully");
+    console.error("[collab-mcp] Server started successfully");
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    console.error(`[mtaap-mcp] Failed to start server: ${message}`);
+    console.error(`[collab-mcp] Failed to start server: ${message}`);
     process.exit(1);
   }
 }
 function setupShutdownHandlers() {
   const shutdown = (signal) => {
-    console.error(`[mtaap-mcp] Received ${signal}, shutting down...`);
+    console.error(`[collab-mcp] Received ${signal}, shutting down...`);
     process.exit(0);
   };
   process.on("SIGINT", () => shutdown("SIGINT"));
   process.on("SIGTERM", () => shutdown("SIGTERM"));
   process.on("uncaughtException", (error) => {
-    console.error("[mtaap-mcp] Uncaught exception:", error.message);
+    console.error("[collab-mcp] Uncaught exception:", error.message);
     process.exit(1);
   });
   process.on("unhandledRejection", (reason) => {
     const message = reason instanceof Error ? reason.message : String(reason);
-    console.error("[mtaap-mcp] Unhandled rejection:", message);
+    console.error("[collab-mcp] Unhandled rejection:", message);
     process.exit(1);
   });
 }