@mtaap/mcp 0.2.12 → 0.2.13

package/README.md

@@ -498,6 +498,12 @@ report_error -> abandon_task -> list_tasks -> assign_task (retry or pick differe
 
 ## Usage
 
+There are two ways to use the Collab MCP server:
+
+### Option 1: Local Installation (Recommended for Claude Desktop)
+
+Install and run locally using stdio transport:
+
 1. Configure your environment variables
 2. Add to your MCP client configuration (Claude Desktop, OpenCode, etc.):
 
@@ -518,6 +524,27 @@ report_error -> abandon_task -> list_tasks -> assign_task (retry or pick differe
 
 3. Use the tools from your AI agent
 
+### Option 2: Remote HTTP Server
+
+Connect to the Collab MCP server using the Streamable HTTP transport. This is useful for:
+- Claude.ai and Claude Mobile (which don't support local MCP servers)
+- Environments where you can't install npm packages
+
+Configure your MCP client to connect to the remote server:
+
+```json
+{
+  "mcpServers": {
+    "collab": {
+      "url": "https://collab.mtaap.de/mcp",
+      "headers": {
+        "X-API-Key": "your-api-key"
+      }
+    }
+  }
+}
+```
+
 ## Troubleshooting
 
 ### "COLLAB_API_KEY is required"

package/dist/cli.js

@@ -30,7 +30,7 @@ var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
 // package.json
 var package_default = {
   name: "@mtaap/mcp",
-  version: "0.2.11",
+  version: "0.2.12",
   description: "Model Context Protocol (MCP) server for AI agents to interact with Collab - the multi-tenant collaborative agent development platform",
   mcpName: "collab",
   scripts: {
@@ -39,7 +39,8 @@ var package_default = {
   main: "./dist/index.js",
   types: "./dist/index.d.ts",
   bin: {
-    "collab-mcp": "./dist/cli.js"
+    "collab-mcp": "./dist/cli.js",
+    "collab-mcp-server": "./dist/server.js"
   },
   publishConfig: {
     access: "public"
@@ -70,11 +71,13 @@ var package_default = {
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    express: "^5.0.1",
     zod: "^4.3.5"
   },
   devDependencies: {
     "@mtaap/config-typescript": "workspace:*",
     "@mtaap/core": "workspace:*",
+    "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     tsup: "^8.5.1",
     typescript: "^5.4.0"
@@ -1366,14 +1369,16 @@ Task Creation & Verification:
 
 Standard Task Workflow:
   list_projects -> get_project_context -> list_tasks(state=TODO) -> get_task -> get_task_prompt (TODO)
-  -> assign_task (returns suggested branch name)
-  -> git checkout -b <branchName> (local git command)
-  -> git push -u origin <branchName> (local git command)
-  -> report_branch (tell server about the branch)
+  -> assign_task (returns suggested branch name and worktree path)
+  -> git worktree add <worktreePath> -b <branchName> <baseBranch>
+  -> cd <worktreePath>
   -> [update_progress...]
+  -> git push -u origin <branchName>
+  -> report_branch (tell server about the branch)
   -> complete_task (returns PR suggestions)
   -> gh pr create (local gh command)
   -> report_pr (tell server about the PR)
+  -> git worktree remove <worktreePath>
 
 Resume Workflow:
   check_active_task -> (if active) get_task -> get_task_prompt (IN_PROGRESS) -> update_progress -> complete_task
@@ -1389,10 +1394,14 @@ Error Recovery:
   (abandon_task returns IN_PROGRESS tasks to TODO state)
 
 GIT OPERATIONS NOTE:
-  The agent handles all git operations locally. After assign_task returns a suggested branch name,
-  the agent creates the branch with git, pushes it, and reports it via report_branch.
-  After complete_task returns PR suggestions, the agent creates the PR with gh, and reports it via report_pr.
-  This eliminates the need for GitHub tokens on the server.
+  The agent handles all git operations locally using git worktrees for isolation.
+  After assign_task returns a suggested branch name and worktree path:
+  1. Create worktree: git worktree add <worktreePath> -b <branchName> <baseBranch>
+  2. Work in worktree directory: cd <worktreePath>
+  3. After completing work, push and call report_branch
+  4. After complete_task, create PR with gh and call report_pr
+  5. Clean up worktree: git worktree remove <worktreePath>
+  Worktrees enable parallel task execution without git conflicts.
 
 TASK STATE FLOW:
   DRAFT -> TODO -> IN_PROGRESS -> REVIEW -> DONE
@@ -1412,7 +1421,7 @@ CONSTRAINTS:
 - Always check_active_task before starting new work
 - Call update_progress frequently to checkpoint
 - Agent must have git/gh CLI configured for local git operations`;
-async function createMCPServer() {
+function initializeMCPServer(apiClient, authContext) {
   const server = new import_mcp.McpServer(
     {
       name: "collab",
@@ -1422,16 +1431,6 @@ async function createMCPServer() {
       instructions: COLLAB_SERVER_INSTRUCTIONS
     }
   );
-  const apiClient = createApiClientFromEnv();
-  let authContext;
-  try {
-    authContext = await apiClient.authenticate();
-  } catch (error) {
-    if (error instanceof ApiError) {
-      throw new Error(`Authentication failed: ${error.message}`);
-    }
-    throw error;
-  }
   const mockApiKey = {
     permissions: authContext.permissions.includes("ADMIN") ? ApiKeyPermission.ADMIN : authContext.permissions.includes("WRITE") ? ApiKeyPermission.WRITE : ApiKeyPermission.READ
   };
@@ -1528,7 +1527,7 @@ async function createMCPServer() {
   server.registerTool(
     "assign_task",
     {
-      description: "Atomically claim a task and create git branch. Race-safe - fails if already assigned. Task must be TODO.",
+      description: "Atomically claim a task. Race-safe - fails if already assigned. Task must be TODO. Returns suggested branch name and worktree path for isolated parallel development.",
       inputSchema: {
         projectId: import_zod3.z.string().describe("The project ID"),
         taskId: import_zod3.z.string().describe("The task ID to assign"),
@@ -2227,9 +2226,26 @@ async function createMCPServer() {
       };
     }
   );
-  const transport = new import_stdio.StdioServerTransport();
+  return server;
+}
+async function connectMCPServer(server, transport) {
   await server.connect(transport);
 }
+async function createMCPServer() {
+  const apiClient = createApiClientFromEnv();
+  let authContext;
+  try {
+    authContext = await apiClient.authenticate();
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw new Error(`Authentication failed: ${error.message}`);
+    }
+    throw error;
+  }
+  const server = initializeMCPServer(apiClient, authContext);
+  const transport = new import_stdio.StdioServerTransport();
+  await connectMCPServer(server, transport);
+}
 function handleApiError(error) {
   if (error instanceof ApiError) {
     return {
@@ -2266,6 +2282,7 @@ var ActiveTaskSchema = import_zod3.z.object({
   taskId: import_zod3.z.string().min(1),
   projectId: import_zod3.z.string().min(1),
   branchName: import_zod3.z.string().optional(),
+  worktreePath: import_zod3.z.string().optional(),
   startedAt: import_zod3.z.string().optional()
 });
 async function checkActiveTask() {
@@ -2419,15 +2436,17 @@ function validateEnvironment() {
 async function checkConnectivity() {
   const baseUrl = process.env.COLLAB_BASE_URL;
   console.error(`[collab-mcp] Checking connectivity to ${baseUrl}...`);
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), 1e4);
   try {
     const response = await fetch(`${baseUrl}/api/mcp/auth`, {
       method: "GET",
       headers: {
         "X-API-Key": process.env.COLLAB_API_KEY
       },
-      signal: AbortSignal.timeout(1e4)
-      // 10 second timeout
+      signal: controller.signal
     });
+    clearTimeout(timeoutId);
     if (!response.ok) {
       const data = await response.json().catch(() => ({}));
       if (response.status === 401) {
@@ -2439,7 +2458,8 @@ async function checkConnectivity() {
     }
     console.error("[collab-mcp] Connected successfully");
   } catch (error) {
-    if (error instanceof Error && error.name === "TimeoutError") {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
       console.error(`[collab-mcp] Error: Connection timed out to ${baseUrl}`);
     } else {
       console.error(`[collab-mcp] Error: Could not connect to ${baseUrl}`);