@mtaap/mcp 0.2.6 → 0.2.8

package/LICENSE

@@ -0,0 +1,20 @@
+MTAAP Collab MCP Server - Proprietary License
+
+Copyright (c) 2024-2026 MTAAP Contributors. All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of this
+Software, via any medium, is strictly prohibited.
+
+The Software is provided for use solely by authorized users in connection with the
+MTAAP Collab platform. Any use of the Software outside of its intended purpose or
+without proper authorization is prohibited.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, please contact the MTAAP team.

package/README.md

@@ -43,11 +43,34 @@ export COLLAB_API_KEY=collab_xxxxx...
 export COLLAB_BASE_URL=https://collab.mtaap.de
 ```
 
+## Task State Flow
+
+```
+DRAFT -> TODO -> IN_PROGRESS -> REVIEW -> DONE
+```
+
+- `DRAFT`: Task created, awaiting verification
+- `TODO`: Task verified, ready for assignment
+- `IN_PROGRESS`: Task assigned and being worked on
+- `REVIEW`: Work complete, PR created, awaiting approval
+- `DONE`: Task approved and completed
+
+State transitions:
+- `verify_task`: DRAFT -> TODO (or NEEDS_REVISION if rejected)
+- `update_task` on TODO: reverts to DRAFT (requires re-verification)
+- `assign_task`: TODO -> IN_PROGRESS
+- `report_pr`: marks task ready for review (REVIEW state)
+- `request_changes`: REVIEW -> IN_PROGRESS
+- `approve_task`: REVIEW -> DONE
+- `abandon_task`: IN_PROGRESS -> TODO
+
 ## Available Tools
 
-### list_projects
+### Project Discovery
+
+#### list_projects
 
-List accessible projects (personal + team via tags).
+Discover all accessible projects. Use first to find project IDs. Filter by TEAM, PERSONAL, or ALL workspaces.
 
 **Parameters:**
 | Name | Type | Required | Description |
@@ -58,24 +81,65 @@ List accessible projects (personal + team via tags).
 
 ---
 
-### list_tasks
+#### get_project_context
+
+Load project README, tech stack, and coding conventions. Call after selecting project.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID (prj_xxx format) |
+
+**Returns:** `{ readme, stack, recentCompleted, conventions }` with repository README (truncated to 2000 chars), detected dependencies, recent completed tasks, and project conventions.
+
+---
+
+#### create_personal_project
+
+Create a new project in your personal workspace linked to GitHub repository.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | Yes | Project name (max 100 chars) |
+| `description` | string | No | Project description (max 500 chars) |
+| `repositoryUrl` | string | Yes | GitHub repository URL |
+
+**Returns:** `{ success, projectId }`
+
+---
+
+#### get_version
+
+Check MCP server version and connectivity.
+
+**Parameters:** None
+
+**Returns:** `{ version, timestamp }`
+
+---
+
+### Task Management
+
+#### list_tasks
 
-List tasks with optional filtering.
+Query tasks with filters. Use state=TODO for assignable tasks, state=REVIEW for pending reviews.
 
 **Parameters:**
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
 | `projectId` | string | No | Filter by project (prj_xxx format) |
-| `state` | TaskState | No | Filter by state: `BACKLOG`, `READY`, `IN_PROGRESS`, `REVIEW`, `DONE` |
+| `state` | TaskState | No | Filter by state: `DRAFT`, `TODO`, `IN_PROGRESS`, `REVIEW`, `DONE` |
 | `assigneeId` | string | No | Filter by assignee (usr_xxx format) |
+| `includeArchived` | boolean | No | Include archived tasks (default: false) |
 
 **Returns:** Array of tasks with full details including acceptance criteria, assignee, creator, epic, PR info.
 
 ---
 
-### get_task
+#### get_task
 
-Get full task details including acceptance criteria, progress updates, and notes.
+Get complete task details with acceptance criteria and notes. Call before assign_task to understand requirements.
 
 **Parameters:**
 | Name | Type | Required | Description |
@@ -86,24 +150,145 @@ Get full task details including acceptance criteria, progress updates, and notes
 
 ---
 
-### assign_task
+#### create_task
+
+Create task with title, description, acceptance criteria. Starts in DRAFT state. Priority: LOW/MEDIUM/HIGH/CRITICAL.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID to create the task in |
+| `epicId` | string | No | Optional epic ID to associate the task with |
+| `title` | string | Yes | Task title (max 200 chars) |
+| `description` | string | Yes | Task description (max 5000 chars) |
+| `priority` | TaskPriority | No | Task priority: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` (default: MEDIUM) |
+| `acceptanceCriteria` | array | Yes | Array of `{ description: string }` (at least 1 required, max 500 chars each) |
+
+**Returns:** `{ success, taskId, state }` - Task created in DRAFT state.
+
+---
+
+#### update_task
+
+Update task details (title, description, priority, acceptanceCriteria). Only works for DRAFT and TODO states. If task is in TODO state, it reverts to DRAFT and requires re-verification.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID to update |
+| `title` | string | No | New task title |
+| `description` | string | No | New task description |
+| `priority` | TaskPriority | No | New task priority |
+| `acceptanceCriteria` | array | No | New acceptance criteria (replaces existing). Array of `{ id?: string, description: string }` |
+
+**Returns:** `{ success, taskId, state, revertedToDraft }` - If task was TODO, revertedToDraft will be true.
+
+---
+
+#### archive_task
+
+Soft-delete a task. Hidden but restorable via unarchive_task.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID to archive |
+
+**Returns:** `{ success, taskId }`
+
+---
+
+#### unarchive_task
+
+Restore previously archived task to original state.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID to restore |
+
+**Returns:** `{ success, taskId, state }`
+
+---
+
+### Task Verification
+
+#### verify_task
+
+Verify a DRAFT task and move it to TODO state. Requires task to pass programmatic validation:
+- Title: 10+ characters
+- Description: 50+ characters
+- Each acceptance criterion: 20+ characters
+
+If `approved=false`, stores feedback with NEEDS_REVISION status.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID to verify |
+| `approved` | boolean | Yes | Whether to approve the task |
+| `feedback` | string | No | Feedback for the task (required if not approved) |
+
+**Returns:** `{ success, taskId, state, verificationStatus }` - state will be TODO if approved, DRAFT with NEEDS_REVISION status if not.
+
+---
+
+#### get_task_prompt
+
+Get state-appropriate prompt for a task. Returns different prompts based on task state:
+- **DRAFT**: Verification prompt with validation requirements
+- **TODO**: Assignment prompt with task details
+- **IN_PROGRESS**: Continue prompt with progress context
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID |
+
+**Returns:** `{ prompt, task, state }` - Formatted prompt text appropriate for the task's current state.
+
+---
+
+### Task Execution
+
+#### assign_task
 
-Atomically claim a task and create a feature branch. Fails if task is already assigned or not in expected state.
+Atomically claim a task and prepare for work. Race-safe - fails if already assigned. Task must be in TODO state.
 
 **Parameters:**
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
 | `projectId` | string | Yes | Project ID (prj_xxx format) |
 | `taskId` | string | Yes | Task ID (tsk_xxx format) |
-| `expectedState` | TaskState | No | Expected task state. Defaults to `READY`. |
+| `expectedState` | TaskState | No | Expected task state. Defaults to `TODO`. |
+
+**Returns:**
+```json
+{
+  "success": true,
+  "taskId": "tsk_xxx",
+  "suggestedBranchName": "feature/TSK-123-task-title",
+  "baseBranch": "main",
+  "repositoryUrl": "https://github.com/owner/repo",
+  "note": "Branch name suggestion. Create with: git checkout -b <branchName>"
+}
+```
 
-**Returns:** `{ success, taskId, branchName }` or error if task state doesn't match.
+After receiving this response:
+1. Create the branch locally: `git checkout -b <suggestedBranchName>`
+2. Push to remote: `git push -u origin <suggestedBranchName>`
+3. Call `report_branch` to inform the server
 
 ---
 
-### update_progress
+#### update_progress
 
-Report progress on an assigned task. Updates acceptance criteria checkboxes and records status messages.
+Report progress and checkpoint work. Call frequently during execution. Marks acceptance criteria complete.
 
 **Parameters:**
 | Name | Type | Required | Description |
@@ -117,9 +302,9 @@ Report progress on an assigned task. Updates acceptance criteria checkboxes and
 
 ---
 
-### complete_task
+#### complete_task
 
-Mark task as complete and create a pull request.
+Prepare task for PR creation. Returns PR suggestions. After creating PR locally with gh CLI, call report_pr to transition to REVIEW state. Requires IN_PROGRESS state.
 
 **Parameters:**
 | Name | Type | Required | Description |
@@ -129,23 +314,57 @@ Mark task as complete and create a pull request.
 | `pullRequestTitle` | string | No | Custom PR title (max 300 chars). Defaults to `[taskId] title`. |
 | `pullRequestBody` | string | No | Custom PR body (max 10000 chars). Defaults to description + acceptance criteria. |
 
-**Returns:** `{ success, taskId, prUrl, prNumber }`
+**Returns:**
+```json
+{
+  "success": true,
+  "taskId": "tsk_xxx",
+  "suggestedPRTitle": "[TSK-123] Task title",
+  "suggestedPRBody": "## Description\n...\n## Acceptance Criteria\n...",
+  "branchName": "feature/TSK-123-task-title",
+  "baseBranch": "main",
+  "note": "Create PR with: gh pr create --title '...' --body '...'"
+}
+```
+
+After receiving this response:
+1. Create PR locally: `gh pr create --title "<suggestedPRTitle>" --body "<suggestedPRBody>"`
+2. Call `report_pr` with the PR URL and number to transition to REVIEW state
 
 ---
 
-### check_active_task
+#### add_note
 
-Check for a resumable task in `.collab/active-task.json` in the current working directory.
+Document implementation decisions. Notes persist for future reference and handoff.
 
-**Parameters:** None
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `taskId` | string | Yes | Task ID (tsk_xxx format) |
+| `content` | string | Yes | Note content (max 500 chars) |
+
+**Returns:** `{ success, noteId }`
+
+---
+
+#### abandon_task
+
+Release task assignment and optionally clean up branch. Task returns to TODO state. Use after errors or when unable to complete.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `projectId` | string | Yes | Project ID (prj_xxx format) |
+| `taskId` | string | Yes | Task ID (tsk_xxx format) |
+| `deleteBranch` | boolean | No | Whether to delete the associated branch |
 
-**Returns:** `{ hasActiveTask, task }` where task contains saved context if found.
+**Returns:** `{ success, taskId, state, branchDeleted }` - state will be `TODO`.
 
 ---
 
-### report_error
+#### report_error
 
-Report an unrecoverable error on a task. The error will be displayed in the webapp.
+Report unrecoverable errors (BUILD_FAILURE, TEST_FAILURE, CONFLICT, AUTH_ERROR, OTHER). Consider abandon_task after reporting.
 
 **Parameters:**
 | Name | Type | Required | Description |
@@ -159,70 +378,123 @@ Report an unrecoverable error on a task. The error will be displayed in the weba
 
 ---
 
-### get_project_context
+### Git Operations
+
+#### report_branch
 
-Get assembled context for a project including README, tech stack, and conventions.
+Report a branch created by the agent. Call after using git to create and push a branch. Task must be IN_PROGRESS.
 
 **Parameters:**
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `projectId` | string | Yes | Project ID (prj_xxx format) |
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID |
+| `branchName` | string | Yes | Name of the branch created (e.g., `feature/TSK-123-fix-login`) |
 
-**Returns:** `{ readme, stack, recentCompleted, conventions }` with repository README (truncated to 2000 chars), detected dependencies, recent completed tasks, and project conventions.
+**Returns:** `{ success, taskId, branchName }`
 
 ---
 
-### add_note
+#### report_pr
 
-Append implementation notes to a task you are assigned to.
+Report a PR created by the agent. Call after using gh pr create. Transitions task to REVIEW state.
 
 **Parameters:**
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `taskId` | string | Yes | Task ID (tsk_xxx format) |
-| `content` | string | Yes | Note content (max 500 chars) |
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID |
+| `pullRequestUrl` | string | Yes | Full URL of the created PR (e.g., `https://github.com/owner/repo/pull/123`) |
+| `pullRequestNumber` | number | Yes | PR number (e.g., `123`) |
 
-**Returns:** `{ success, noteId }`
+**Returns:** `{ success, taskId, state, pullRequestUrl }` - state will be `REVIEW`.
 
 ---
 
-### abandon_task
+### Code Review
+
+#### request_changes
 
-Unassign yourself from a task and optionally delete the feature branch. Task returns to `READY` state if it was `IN_PROGRESS`.
+Return task from REVIEW to IN_PROGRESS with feedback. Original assignee addresses changes.
 
 **Parameters:**
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `projectId` | string | Yes | Project ID (prj_xxx format) |
-| `taskId` | string | Yes | Task ID (tsk_xxx format) |
-| `deleteBranch` | boolean | No | Whether to delete the feature branch on GitHub |
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID to review |
+| `reviewComments` | string | Yes | Review comments explaining requested changes (max 5000 chars) |
+| `requestedChanges` | string[] | No | List of specific changes requested |
 
-**Returns:** `{ success, taskId, state, branchDeleted }`
+**Returns:** `{ success, taskId, state }` - state will be `IN_PROGRESS`.
 
 ---
 
-### create_personal_project
+#### approve_task
 
-Create a new project in your personal workspace.
+Approve completed work and mark DONE. Only for REVIEW state tasks.
 
 **Parameters:**
 | Name | Type | Required | Description |
 |------|------|----------|-------------|
-| `name` | string | Yes | Project name (max 100 chars) |
-| `description` | string | No | Project description (max 500 chars) |
-| `repositoryUrl` | string | Yes | GitHub repository URL |
+| `projectId` | string | Yes | Project ID |
+| `taskId` | string | Yes | Task ID to approve |
+| `reviewComments` | string | No | Optional approval comments (max 2000 chars) |
 
-**Returns:** `{ success, projectId }`
+**Returns:** `{ success, taskId, state }` - state will be `DONE`.
 
 ---
 
-### get_version
+### Session Management
 
-Get the current Collab MCP server version.
+#### check_active_task
+
+Check for resumable work from previous session. Always call before starting new work.
 
 **Parameters:** None
 
-**Returns:** `{ version, timestamp }`
+**Returns:** `{ hasActiveTask, task }` where task contains saved context from `.collab/active-task.json` if found.
+
+---
+
+## Workflows
+
+### Task Creation and Verification
+
+```
+create_task -> get_task_prompt (DRAFT) -> verify_task(approved=true) -> task moves to TODO
+```
+
+### Standard Task Execution
+
+```
+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)
+-> [update_progress...]
+-> complete_task (returns PR suggestions)
+-> gh pr create (local gh command)
+-> report_pr (tell server about the PR, transitions to REVIEW)
+```
+
+### Resume Previous Work
+
+```
+check_active_task -> (if active) get_task -> get_task_prompt (IN_PROGRESS) -> update_progress -> complete_task
+```
+
+### Code Review
+
+```
+list_tasks(state=REVIEW) -> get_task -> approve_task OR request_changes
+```
+
+### Error Recovery
+
+```
+report_error -> abandon_task -> list_tasks -> assign_task (retry or pick different task)
+```
 
 ## Usage
 
@@ -246,19 +518,6 @@ Get the current Collab MCP server version.
 
 3. Use the tools from your AI agent
 
-## Development
-
-```bash
-# Build
-pnpm build
-
-# Watch mode
-pnpm dev
-
-# Run locally
-COLLAB_API_KEY=your-key COLLAB_BASE_URL=https://collab.mtaap.de pnpm start
-```
-
 ## Troubleshooting
 
 ### "COLLAB_API_KEY is required"
@@ -273,10 +532,6 @@ You need to set the `COLLAB_BASE_URL` environment variable to your Collab webapp
 
 Your API key may be expired or revoked. Generate a new one at https://collab.mtaap.de/settings/api-keys
 
-### "GitHub token not configured"
-
-Git operations (branch creation, PR creation) require a GitHub token to be configured in your Collab account settings. Go to https://collab.mtaap.de/settings and add your GitHub personal access token.
-
 ### Connection issues
 
 Ensure your firewall allows outbound connections to your Collab instance. The server performs a connectivity check on startup and will report any connection issues.
@@ -285,16 +540,6 @@ Ensure your firewall allows outbound connections to your Collab instance. The se
 
 The MCP API is rate limited to 100 requests per minute. If you exceed this limit, you'll receive a 429 error with a `Retry-After` header indicating when you can retry.
 
-## Publishing
-
-This package is published as `@mtaap/mcp` to npm.
-
-```bash
-# Build and publish
-pnpm build
-npm publish
-```
-
 ## License
 
-MIT
+Proprietary - See LICENSE file for details.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node