targetprocess-mcp-server 2.3.0 → 2.4.0

package/README.md

@@ -51,6 +51,8 @@ User Stories
 Tasks
 - `get_in_progress_tasks_and_bugs` — Get all Tasks and Bugs currently in "In Progress" state assigned to a given user (userId)
 - `create_task` — Create a new task linked to a user story (title, userStoryId, optional description)
+- `list_my_user_stories` — List User Stories assigned to the current user, optionally filtered by state (optional state, optional take, optional skip)
+- `list_my_bugs` — List Bugs assigned to the current user, optionally filtered by state (optional state, optional take, optional skip)
 
 Cards — Read
 - `get_card_current_status` — Get EntityState, TeamState, and assigned teams for a card (id, optional resourceType: UserStory | Bug | Feature, default: UserStory)
@@ -59,6 +61,8 @@ Cards — Read
 - `get_bug_comments` — Get comments on a bug (id, optional results)
 - `get_user_story_comments` — Get comments on a user story (id, optional results)
 - `get_user_story_test_cases` — Fetch the linked test plan and all its test cases (with steps) for a user story (resourceId)
+- `get_card_relations` — Get all relations (Dependency, Blocker, Relation, Link, Duplicate) for a card, with direction and the related card (id)
+- `get_relation_types` — List the relation types available in this instance (id + name); use to find the `relationType` name for `create_card_relation` (no params)
 - `search_tp_cards` — Search TP cards by keyword or phrase in description (keyword, optional entityType: UserStories | Bugs, default: UserStories)
 
 Cards — Write
@@ -68,6 +72,14 @@ Cards — Write
   > Resolve state name → ID via `get_bug_workflows` before passing `entityStateId`
 - `update_user_story` — Update an existing user story (id, optional title, optional description, optional projectId, optional teamId, optional entityStateId)
   > Resolve state name → ID via `get_user_story_workflows` before passing `entityStateId`
+- `create_card_relation` — Create a relation between two cards (masterId, slaveId, optional relationType name, default: "Depends on")
+  > The Slave depends on the Master — the Master must be done first
+  > `relationType` is matched by name against this instance's types; resolve exact names via `get_relation_types` (it's resolved to an ID before the API call, since TP rejects relation types passed by name)
+- `delete_card_relation` — Remove a relation by its relation ID (relationId)
+  > Get the `relationId` from `get_card_relations` first — it's the relation's own ID, not a card ID
+- `update_user_story_state` — Update the sub-state (team assignment entity state) for a user story (id, optional entityStateId, optional teamId, optional teamAssignmentId)
+  > 1. Call `get_user_story_content` first to find the assigned team and `teamAssignmentId`
+  > 2. Call `get_user_story_workflows` to resolve the target state name → `entityStateId`
 - `create_bug` — Create a standalone bug (title, bugContent, optional origin, optional projectId, optional teamId, optional entityStateName)
   > `origin` accepted values: `Production - Customer`, `Production - Internal`, `Pre-Release - Customer`, `Pre-Release - Internal`, `Regression - Dev01`, `Regression - Team Env`, `Manual QA` *(default)*, `Developer Raised`, `Operations`
   > `entityStateName` accepted values: `Backlog`, `In Triage`, `Ready for Dev`, `In Dev`, `Blocked`, `PR Raised`, `Ready for Feature PCH`, `Ready for Feature QA`, `In Feature QA`, `Failed Feature QA`, `Ready for Merge`, `Ready to Deploy to Dev01`, `Ready for Dev01 QA`, `In Dev01 QA`, `Failed Dev01 QA`, `Ready to Deploy to prod`, `Closed`
@@ -101,12 +113,17 @@ Projects
 
 Teams
 - `get_teams` — Get all Targetprocess teams returning id and name (no params needed)
+- `get_teams_and_team_assignments` — Get all teams and team assignments (id and name for each) (no params needed)
 
 User
 - `get_logged_in_user` — Get the currently logged-in user's info (no params needed)
 - `get_users` — Get all Targetprocess users (no params needed)
 - `get_user_by_id` — Get a single Targetprocess user by their ID (id)
 
+Time Tracking
+- `log_time` — Log time spent on a Task, User Story, or Bug (entityId, entityType: Task | UserStory | Bug, hours, optional description, optional date)
+- `get_my_time_logs` — Get recent time log entries submitted by the current user (optional take)
+
 Developer Tools
 - `get_commit_message` — Returns a formatted commit message string for a task or bug ID (id, type: task | bug)
   > Format for task on a user story: `F#<featureId> US#<userStoryId> T#<taskId> <title>`
@@ -177,3 +194,32 @@ cd targetprocess-mcp-server
 npm install
 npm run build
 ```
+
+## Testing
+
+Tests live in `tests/` and use [Vitest](https://vitest.dev/). All tool handlers are extracted to `src/handlers/` and tested with mocked `TpClient` instances — no network calls are made.
+
+```bash
+npx vitest run        # run all tests once
+npx vitest            # watch mode
+```
+
+### Coverage
+
+**33 of 46 tools (72%) are covered by unit tests.**
+
+| Test file | Handlers covered |
+|---|---|
+| `get_bug_content.test.ts` | `get_bug_content` |
+| `get_user_story_content.test.ts` | `get_user_story_content` |
+| `get_commit_message.test.ts` | `get_commit_message` |
+| `get_current_releases.test.ts` | `get_current_releases` |
+| `get_projects.test.ts` | `get_projects` |
+| `get_logged_in_user.test.ts` | `get_logged_in_user` |
+| `get_user_by_id.test.ts` | `get_user_by_id` |
+| `release_tools.test.ts` | `get_release_user_stories`, `get_release_bugs`, `get_release_features`, `get_release_open_bugs`, `get_release_open_user_stories` |
+| `user_team_tools.test.ts` | `get_users`, `get_teams`, `get_teams_and_team_assignments` |
+| `comment_tools.test.ts` | `add_comment`, `get_user_story_comments`, `get_bug_comments` |
+| `creation_tools.test.ts` | `create_bug`, `create_user_story`, `create_feature`, `create_task`, `update_bug`, `update_user_story_state` |
+| `my_work_tools.test.ts` | `get_in_progress_tasks_and_bugs`, `list_my_user_stories`, `list_my_bugs`, `log_time`, `get_my_time_logs` |
+| `entity_tools.test.ts` | `get_feature_user_stories`, `get_user_story_bugs`, `get_card_current_status` |

package/build/handlers/add_comment.js

@@ -0,0 +1,14 @@
+export async function handleAddComment(tp, id, comment) {
+    const response = await tp.addComment(id, comment);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to add comment to user story, id: ${id}\n JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(response) }],
+    };
+}

package/build/handlers/create_bug.js

@@ -0,0 +1,14 @@
+export async function handleCreateBug(tp, params) {
+    const bugResponse = await tp.createBugOnly(params);
+    if (!bugResponse) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create bug "${params.title}"\n JSON: ${JSON.stringify(bugResponse, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(bugResponse) }],
+    };
+}

package/build/handlers/create_feature.js

@@ -0,0 +1,14 @@
+export async function handleCreateFeature(tp, params) {
+    const response = await tp.createFeature(params);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create feature "${params.title}"\n JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(response) }],
+    };
+}

package/build/handlers/create_task.js

@@ -0,0 +1,14 @@
+export async function handleCreateTask(tp, params) {
+    const response = await tp.createTask(params);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create task "${params.title}"\n JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(response) }],
+    };
+}

package/build/handlers/create_user_story.js

@@ -0,0 +1,14 @@
+export async function handleCreateUserStory(tp, params) {
+    const response = await tp.createUserStory(params);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to create user story "${params.title}"\n JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(response) }],
+    };
+}

package/build/handlers/get_bug_comments.js

@@ -0,0 +1,45 @@
+import { JSDOM } from 'jsdom';
+export async function handleGetBugComments(tp, id, results) {
+    const response = await tp.getBugComments(id, results);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get comments for bug id: ${id}`
+                }],
+        };
+    }
+    const items = response.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No comments found for bug id: ${id}`,
+                }],
+        };
+    }
+    try {
+        const parsedItems = items.map((item) => {
+            const dom = new JSDOM(`<html><body><div id="content">${item.Description}</div></body></html>`);
+            const descriptionText = dom.window.document.getElementById('content')?.textContent;
+            return {
+                id: item.Id,
+                description: descriptionText,
+                createDate: item.CreateDate,
+                owner: item.Owner.FullName,
+            };
+        });
+        return {
+            content: [{ type: 'text', text: JSON.stringify(parsedItems) }],
+        };
+    }
+    catch (error) {
+        console.error('Error parsing bug comments:', error);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to parse bug comments for bug id: ${id}`,
+                }],
+        };
+    }
+}

package/build/handlers/get_bug_content.js

@@ -0,0 +1,37 @@
+import { JSDOM } from 'jsdom';
+export async function handleGetBugContent(tp, id) {
+    const bug = await tp.getBug(id);
+    if (!bug) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get bug, id: ${id}\n JSON: ${JSON.stringify(bug, null, 2)}`
+                }],
+        };
+    }
+    const bugResult = {
+        name: bug.Name,
+        id: bug.Id,
+        description: '',
+        origin: '',
+    };
+    try {
+        const dom = new JSDOM(`<html><body><div id="content">${bug.Description}</div></body></html>`);
+        const descriptionText = dom.window.document.getElementById('content')?.textContent;
+        if (descriptionText) {
+            bugResult.description = descriptionText;
+        }
+    }
+    catch (error) {
+        console.error('Error parsing bug description:', error);
+    }
+    try {
+        bugResult.origin = bug.CustomFields?.find((field) => field?.Value === 'Origin')?.Value;
+    }
+    catch (error) {
+        console.error('Error parsing bug origin:', error);
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(bugResult) }],
+    };
+}

package/build/handlers/get_card_current_status.js

@@ -0,0 +1,23 @@
+export async function handleGetCardCurrentStatus(tp, id, resourceType = 'UserStory') {
+    const response = await tp.getCardStatus(id, resourceType);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get card status for ${resourceType} id: ${id}`
+                }],
+        };
+    }
+    const items = response.items || [];
+    if (items.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No status data found for ${resourceType} id: ${id}`,
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items[0]) }],
+    };
+}

package/build/handlers/get_commit_message.js

@@ -0,0 +1,42 @@
+export async function handleGetCommitMessage(tp, id, type) {
+    if (type === 'task') {
+        const task = await tp.getTask(id);
+        if (!task) {
+            return {
+                content: [{ type: 'text', text: `Failed to get task with id: ${id}` }],
+            };
+        }
+        const userStory = task.UserStory;
+        if (!userStory) {
+            return {
+                content: [{ type: 'text', text: `Task ${id} has no linked user story` }],
+            };
+        }
+        const feature = userStory.Feature;
+        const prefix = feature
+            ? `F#${feature.Id} US#${userStory.Id} T#${task.Id}`
+            : `US#${userStory.Id} T#${task.Id}`;
+        return {
+            content: [{ type: 'text', text: `${prefix} ${task.Name}` }],
+        };
+    }
+    const bug = await tp.getBugWithRelations(id);
+    if (!bug) {
+        return {
+            content: [{ type: 'text', text: `Failed to get bug with id: ${id}` }],
+        };
+    }
+    const userStory = bug.UserStory;
+    const feature = userStory?.Feature ?? bug.Feature;
+    if (!userStory) {
+        return {
+            content: [{ type: 'text', text: `B#${bug.Id} ${bug.Name}` }],
+        };
+    }
+    const prefix = feature
+        ? `F#${feature.Id} US#${userStory.Id} B#${bug.Id}`
+        : `US#${userStory.Id} B#${bug.Id}`;
+    return {
+        content: [{ type: 'text', text: `${prefix} ${bug.Name}` }],
+    };
+}

package/build/handlers/get_current_releases.js

@@ -0,0 +1,20 @@
+export async function handleGetCurrentReleases(tp) {
+    const releases = await tp.getCurrentReleases();
+    if (!releases) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get current releases, JSON: ${JSON.stringify(releases, null, 2)}`
+                }],
+        };
+    }
+    const items = releases.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No releases found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_feature_user_stories.js

@@ -0,0 +1,23 @@
+export async function handleGetFeatureUserStories(tp, id) {
+    const response = await tp.getFeatureUserStories(id);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get user stories for feature id: ${id}`
+                }],
+        };
+    }
+    const items = response.items || [];
+    if (items.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No user stories found in outer items for feature id: ${id}`,
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_in_progress_tasks_and_bugs.js

@@ -0,0 +1,35 @@
+export async function handleGetInProgressTasksAndBugs(tp, userId) {
+    const result = await tp.getInProgressTasksAndBugs(userId);
+    const tasks = result.tasks.map((t) => ({
+        type: 'Task',
+        id: t.Id,
+        name: t.Name,
+        state: t.EntityState?.Name,
+        userStoryId: t.UserStory?.Id,
+        userStoryName: t.UserStory?.Name,
+        featureId: t.UserStory?.Feature?.Id,
+        featureName: t.UserStory?.Feature?.Name,
+    }));
+    const bugs = result.bugs.map((b) => ({
+        type: 'Bug',
+        id: b.Id,
+        name: b.Name,
+        state: b.EntityState?.Name,
+        userStoryId: b.UserStory?.Id,
+        userStoryName: b.UserStory?.Name,
+        featureId: b.UserStory?.Feature?.Id ?? b.Feature?.Id,
+        featureName: b.UserStory?.Feature?.Name ?? b.Feature?.Name,
+    }));
+    const items = [...tasks, ...bugs];
+    if (items.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No in-progress tasks or bugs found for user ID: ${userId}`,
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_logged_in_user.js

@@ -0,0 +1,23 @@
+export async function handleGetLoggedInUser(tp) {
+    const ctx = await tp.getContext();
+    if (!ctx) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get context, JSON: ${JSON.stringify(ctx, null, 2)}`
+                }],
+        };
+    }
+    const loggedInUser = ctx.LoggedUser;
+    if (!loggedInUser) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get logged in user in this context, JSON: ${JSON.stringify(ctx, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(loggedInUser) }],
+    };
+}

package/build/handlers/get_my_time_logs.js

@@ -0,0 +1,20 @@
+export async function handleGetMyTimeLogs(tp, take) {
+    const response = await tp.getMyTimeLogs(take);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get time logs, JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    const items = response.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No time logs found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_projects.js

@@ -0,0 +1,23 @@
+export async function handleGetProjects(tp) {
+    const response = await tp.getProjects();
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get projects, JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    const items = response.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No projects found' }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(items.map((p) => ({ id: p.Id, name: p.Name })))
+            }],
+    };
+}

package/build/handlers/get_release_bugs.js

@@ -0,0 +1,20 @@
+export async function handleGetReleaseBugs(tp, name, results) {
+    const release = await tp.getReleaseBugs({ name, results });
+    if (!release) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get ${name} release bugs, JSON: ${JSON.stringify(release, null, 2)}`
+                }],
+        };
+    }
+    const items = release.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No release bugs found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_release_features.js

@@ -0,0 +1,20 @@
+export async function handleGetReleaseFeatures(tp, name, results) {
+    const release = await tp.getReleaseFeatures({ name, results });
+    if (!release) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get ${name} release features, JSON: ${JSON.stringify(release, null, 2)}`
+                }],
+        };
+    }
+    const items = release.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No release features found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_release_open_bugs.js

@@ -0,0 +1,20 @@
+export async function handleGetReleaseOpenBugs(tp, name, results, withDescription) {
+    const release = await tp.getReleaseOpenBugs({ name, results, withDescription });
+    if (!release) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get ${name} release bugs, JSON: ${JSON.stringify(release, null, 2)}`
+                }],
+        };
+    }
+    const items = release.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No release bugs found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_release_open_user_stories.js

@@ -0,0 +1,20 @@
+export async function handleGetReleaseOpenUserStories(tp, name, results, withDescription) {
+    const release = await tp.getReleaseOpenUserStories({ name, results, withDescription });
+    if (!release) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get ${name} release user stories, JSON: ${JSON.stringify(release, null, 2)}`
+                }],
+        };
+    }
+    const items = release.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No release user stories found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_release_user_stories.js

@@ -0,0 +1,20 @@
+export async function handleGetReleaseUserStories(tp, name, results, withDescription) {
+    const release = await tp.getReleaseUserStories({ name, results, withDescription });
+    if (!release) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get ${name} release user stories, JSON: ${JSON.stringify(release, null, 2)}`
+                }],
+        };
+    }
+    const items = release.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No release user stories found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}

package/build/handlers/get_teams.js

@@ -0,0 +1,41 @@
+export async function handleGetTeams(tp) {
+    const response = await tp.getTeams();
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get teams, JSON: ${JSON.stringify(response, null, 2)}`
+                }],
+        };
+    }
+    const items = response.Items || [];
+    if (items.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No teams found' }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items.map((t) => ({ id: t.Id, name: t.Name }))) }],
+    };
+}
+export async function handleGetTeamsAndTeamAssignments(tp) {
+    const teams = await tp.getTeams();
+    const teamAssignments = await tp.getTeamAssignments();
+    if (!teams || !teamAssignments) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get teams and team assignments, JSON: ${JSON.stringify({ teams, teamAssignments }, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    teams: teams.Items.map((t) => ({ id: t.Id, name: t.Name })),
+                    teamAssignments: teamAssignments.Items.map((t) => ({ id: t.Id, name: t.Team.Name })),
+                }),
+            }],
+    };
+}

package/build/handlers/get_user_by_id.js

@@ -0,0 +1,14 @@
+export async function handleGetUserById(tp, id) {
+    const user = await tp.getUser(id);
+    if (!user) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get user, id: ${id}\n JSON: ${JSON.stringify(user, null, 2)}`
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(user) }],
+    };
+}

package/build/handlers/get_user_story_bugs.js

@@ -0,0 +1,23 @@
+export async function handleGetUserStoryBugs(tp, id) {
+    const response = await tp.getUserStoryBugs(id);
+    if (!response) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Failed to get bugs for user story id: ${id}`
+                }],
+        };
+    }
+    const items = response.items || [];
+    if (items.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `No bugs found for user story id: ${id}`,
+                }],
+        };
+    }
+    return {
+        content: [{ type: 'text', text: JSON.stringify(items) }],
+    };
+}