@mtaap/mcp 0.2.12 → 0.2.13

package/dist/index.d.ts

@@ -1,9 +1,400 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { TaskState, ErrorType } from '@mtaap/core';
+
+/**
+ * MCP API Client
+ *
+ * HTTP client for communicating with the Collab webapp REST API.
+ * Replaces direct database access for a lighter, more secure MCP package.
+ */
+
+/**
+ * API Client Configuration
+ */
+interface ApiClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+    debug?: boolean;
+}
+/**
+ * Authentication context returned from the API
+ */
+interface AuthContext {
+    userId: string;
+    organizationId: string | undefined;
+    permissions: string[];
+    userName: string;
+    userEmail: string;
+}
+/**
+ * Project from API
+ */
+interface Project {
+    id: string;
+    name: string;
+    description: string | null;
+    type: string;
+    origin: string;
+    repositoryUrl: string;
+    baseBranch: string;
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Task from API
+ */
+interface Task {
+    id: string;
+    projectId: string;
+    projectName: string;
+    epicId: string | null;
+    epicName: string | null;
+    title: string;
+    description: string | null;
+    state: TaskState;
+    priority: string;
+    assigneeId: string | null;
+    assigneeName: string | null;
+    assigneeEmail: string | null;
+    createdBy: string;
+    createdByName: string | null;
+    assignedAt: string | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    branchName: string | null;
+    pullRequestUrl: string | null;
+    pullRequestNumber: number | null;
+    errorType: string | null;
+    errorMessage: string | null;
+    verificationStatus: string | null;
+    verificationFeedback: string | null;
+    verifiedAt: string | null;
+    acceptanceCriteria: Array<{
+        id: string;
+        description: string;
+        completed: boolean;
+        completedAt: string | null;
+        order: number;
+    }>;
+    progressUpdates?: Array<{
+        id: string;
+        message: string;
+        checkpoints: string[];
+        userId: string;
+        createdAt: string;
+    }>;
+    notes?: Array<{
+        id: string;
+        content: string;
+        userId: string;
+        userName: string | null;
+        createdAt: string;
+    }>;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt: string | null;
+}
+/**
+ * Project context from API
+ */
+interface ProjectContext {
+    readme: string;
+    stack: string[];
+    recentCompleted: Array<{
+        id: string;
+        title: string;
+        completedAt: string | null;
+    }>;
+    conventions: {
+        branchPrefix: string;
+        commitFormat: string;
+        testCommand: string;
+        baseBranch: string;
+        notes: string;
+    };
+}
+/**
+ * API Error
+ */
+declare class ApiError extends Error {
+    code: string;
+    status: number;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, status: number, details?: Record<string, unknown> | undefined);
+}
+/**
+ * MCP API Client
+ */
+declare class MCPApiClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    private debug;
+    private authContext;
+    constructor(config: ApiClientConfig);
+    /**
+     * Make an HTTP request to the API
+     */
+    private request;
+    /**
+     * Authenticate and get user context
+     */
+    authenticate(): Promise<AuthContext>;
+    /**
+     * Get cached auth context or authenticate
+     */
+    getAuthContext(): Promise<AuthContext>;
+    /**
+     * List accessible projects
+     */
+    listProjects(workspaceType?: string): Promise<Project[]>;
+    /**
+     * Get single project details
+     */
+    getProject(projectId: string): Promise<Project>;
+    /**
+     * Get project context (README, stack, conventions)
+     */
+    getProjectContext(projectId: string): Promise<ProjectContext>;
+    /**
+     * Create a personal project
+     */
+    createPersonalProject(name: string, description: string | undefined, repositoryUrl: string): Promise<{
+        success: boolean;
+        projectId: string;
+    }>;
+    /**
+     * Create a task in a project
+     */
+    createTask(input: {
+        projectId: string;
+        epicId?: string | null;
+        title: string;
+        description: string;
+        priority?: string;
+        acceptanceCriteria: Array<{
+            description: string;
+        }>;
+    }): Promise<{
+        success: boolean;
+        taskId: string;
+        task: Task;
+    }>;
+    /**
+     * List tasks with optional filters
+     */
+    listTasks(filters?: {
+        projectId?: string;
+        state?: TaskState;
+        assigneeId?: string;
+        includeArchived?: boolean;
+    }): Promise<Task[]>;
+    /**
+     * Get full task details
+     */
+    getTask(taskId: string): Promise<Task>;
+    /**
+     * Assign task to current user and create branch
+     */
+    assignTask(taskId: string, projectId: string, expectedState?: TaskState): Promise<{
+        success: boolean;
+        taskId: string;
+        suggestedBranchName?: string;
+        baseBranch?: string;
+        repositoryUrl?: string;
+        currentState?: string;
+        message?: string;
+        note?: string;
+    }>;
+    /**
+     * Update task progress
+     */
+    updateProgress(taskId: string, data: {
+        statusMessage?: string;
+        completedCheckpointIds?: string[];
+        currentCheckpointIndex?: number;
+    }): Promise<{
+        success: boolean;
+        taskId: string;
+    }>;
+    /**
+     * Complete task and prepare for PR creation.
+     * Returns PR suggestions for the agent to use when creating the PR locally.
+     */
+    completeTask(taskId: string, projectId: string, pullRequestTitle?: string, pullRequestBody?: string): Promise<{
+        success: boolean;
+        taskId: string;
+        suggestedPRTitle?: string;
+        suggestedPRBody?: string;
+        branchName?: string;
+        baseBranch?: string;
+        note?: string;
+    }>;
+    /**
+     * Abandon task and optionally delete branch
+     */
+    abandonTask(taskId: string, projectId: string, deleteBranch?: boolean): Promise<{
+        success: boolean;
+        taskId: string;
+        state: string;
+        branchDeleted: boolean;
+    }>;
+    /**
+     * Archive a task (soft delete)
+     */
+    archiveTask(taskId: string, projectId: string): Promise<{
+        success: boolean;
+        taskId: string;
+        archivedAt: string;
+    }>;
+    /**
+     * Unarchive a task (restore)
+     */
+    unarchiveTask(taskId: string, projectId: string): Promise<{
+        success: boolean;
+        taskId: string;
+    }>;
+    /**
+     * Report task error
+     */
+    reportError(taskId: string, errorType: ErrorType, errorMessage: string, context?: string): Promise<{
+        success: boolean;
+        taskId: string;
+    }>;
+    /**
+     * Add note to task
+     */
+    addNote(taskId: string, content: string): Promise<{
+        success: boolean;
+        noteId: string;
+    }>;
+    /**
+     * Request changes on a task in review
+     */
+    requestChanges(taskId: string, projectId: string, reviewComments: string, requestedChanges?: string[]): Promise<{
+        success: boolean;
+        taskId: string;
+        noteId: string;
+        message: string;
+    }>;
+    /**
+     * Approve a task in review and mark as DONE
+     */
+    approveTask(taskId: string, projectId: string, reviewComments?: string): Promise<{
+        success: boolean;
+        taskId: string;
+        message: string;
+    }>;
+    /**
+     * Report branch created by agent
+     */
+    reportBranch(taskId: string, projectId: string, branchName: string): Promise<{
+        success: boolean;
+        taskId: string;
+        branchName: string;
+    }>;
+    /**
+     * Report PR created by agent
+     */
+    reportPR(taskId: string, projectId: string, pullRequestUrl: string, pullRequestNumber: number): Promise<{
+        success: boolean;
+        taskId: string;
+        pullRequestUrl: string;
+        pullRequestNumber: number;
+        state: string;
+    }>;
+    /**
+     * Verify a DRAFT task to move it to TODO state
+     */
+    verifyTask(taskId: string, projectId: string, approved: boolean, feedback?: string): Promise<{
+        success: boolean;
+        taskId: string;
+        previousState: string;
+        newState: string;
+        verificationStatus: string;
+        message: string;
+        feedback?: string;
+    }>;
+    /**
+     * Get state-appropriate prompt for a task
+     */
+    getTaskPrompt(taskId: string, projectId: string): Promise<{
+        success: boolean;
+        taskId: string;
+        state: string;
+        promptType: string;
+        promptDescription: string;
+        prompt: string;
+    }>;
+    /**
+     * Update task details (DRAFT/TODO states only)
+     */
+    updateTask(taskId: string, projectId: string, data: {
+        title?: string;
+        description?: string;
+        priority?: string;
+        acceptanceCriteria?: Array<{
+            id?: string;
+            description: string;
+        }>;
+    }): Promise<{
+        success: boolean;
+        taskId: string;
+        previousState: string;
+        newState: string;
+        revertedToDraft: boolean;
+        message: string;
+        task: {
+            id: string;
+            title: string;
+            description: string;
+            priority: string;
+            state: string;
+            verificationStatus: string;
+            acceptanceCriteria: Array<{
+                id: string;
+                description: string;
+                order: number;
+            }>;
+        };
+    }>;
+}
+
+declare const VERSION: string;
+
 /**
  * Collab MCP Server
  *
  * Model Context Protocol server for AI agent integration.
  * Uses REST API to communicate with the Collab webapp.
  */
+
+/**
+ * Initialize an MCP server with all tools registered.
+ * This is the core setup used by both stdio and HTTP transports.
+ *
+ * @param apiClient - The API client for communicating with the Collab webapp
+ * @param authContext - The authenticated user context
+ * @returns The configured McpServer instance (not yet connected to a transport)
+ */
+declare function initializeMCPServer(apiClient: MCPApiClient, authContext: AuthContext): McpServer;
+/**
+ * Connect an MCP server to a transport.
+ *
+ * @param server - The MCP server instance
+ * @param transport - The transport to connect to
+ */
+declare function connectMCPServer(server: McpServer, transport: Transport): Promise<void>;
+/**
+ * Create and start an MCP server with stdio transport.
+ * This is the main entry point for CLI usage (collab-mcp command).
+ *
+ * Creates the API client, authenticates, initializes the server with all tools,
+ * and connects to stdio transport for communication with Claude Code.
+ */
 declare function createMCPServer(): Promise<void>;
 
-export { createMCPServer };
+export { ApiError, type AuthContext, MCPApiClient, VERSION, connectMCPServer, createMCPServer, initializeMCPServer };

package/dist/index.js

@@ -30,7 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  createMCPServer: () => createMCPServer
+  ApiError: () => ApiError,
+  MCPApiClient: () => MCPApiClient,
+  VERSION: () => VERSION,
+  connectMCPServer: () => connectMCPServer,
+  createMCPServer: () => createMCPServer,
+  initializeMCPServer: () => initializeMCPServer
 });
 module.exports = __toCommonJS(src_exports);
 var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
@@ -39,7 +44,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: {
@@ -48,7 +53,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"
@@ -79,11 +85,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"
@@ -1375,14 +1383,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
@@ -1398,10 +1408,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
@@ -1421,7 +1435,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",
@@ -1431,16 +1445,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
   };
@@ -1537,7 +1541,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"),
@@ -2236,9 +2240,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 {
@@ -2275,6 +2296,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() {
@@ -2346,6 +2368,11 @@ async function checkActiveTask() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createMCPServer
+  ApiError,
+  MCPApiClient,
+  VERSION,
+  connectMCPServer,
+  createMCPServer,
+  initializeMCPServer
 });
 //# sourceMappingURL=index.js.map